# Gyral 0.3.6: complete documentation

> Gyral is a small framework for web components: intents in, a pure update, a pure view out. Server rendering, forms, routing and testing built in.

Generated from https://gyral.dev. Each section below is one page; its source URL follows its title.

---

# Gyral documentation

> Learn Gyral, the Model-View-Intent framework for web components: guides, concepts and reference.

Source: https://gyral.dev/docs/

Gyral builds web components from three pure parts. **Intent** turns platform events into typed
messages, **update** turns messages into new state, and **view** turns state into HTML. Side
effects such as HTTP, routing and timers are returned from update as data, and drivers carry them
out at the edges of your app.

New here? Start with [Getting started](https://gyral.dev/docs/getting-started/). It takes about ten minutes and
ends with a working, tested component. Writing code with an agent? Connect it to Gyral's MCP
server first: [Use Gyral with coding agents](https://gyral.dev/docs/coding-agents/).

The guides build on each other, but each one stands alone. The [API reference](https://gyral.dev/docs/api/) is
generated from the published type declarations, so it always matches the code.

---

# Getting started

> Install Gyral, write your first Model-View-Intent component, use it in a page, and test it without a browser.

Source: https://gyral.dev/docs/getting-started/

In this guide you'll create a Gyral app, write a counter component, put it on a page, and test
it. You need [Node.js](https://nodejs.org) 24 or later and a package manager. The examples use
npm; pnpm and yarn work the same way.

## Create a project

The quickest start is `create-gyral`. It sets up a Vite project with Gyral, TypeScript and a
first test:

```sh
npm create gyral@latest my-app -- --template ssr
cd my-app
npm install
npm run dev
```

There are two templates:

- **`basic`**: a client-rendered app. The page loads and your components render in the
  browser. It builds [client-only](https://gyral.dev/docs/rendering-modes/#client-only-builds), without
  hydration code; remove `clientOnly: true` from `vite.config.ts` before you render any page
  on a server.
- **`ssr`**: the same component rendered on the server first, so the page works before any
  JavaScript loads, then [hydrated](https://gyral.dev/docs/server-rendering/) in place.

Leave out `--template` and it asks you which one you want.

### Or set it up by hand

Gyral works with any bundler. To add it to a [Vite](https://vite.dev) project yourself:

```sh
npm create vite@latest my-app -- --template vanilla-ts
cd my-app
npm install @gyral/core
```

`@gyral/core` is the whole runtime: Gyral renders with its own view layer and has no runtime
dependencies.

Then add Gyral's Vite preset. It adds the template compiler to `vite build`: every template is
checked and precompiled, so a mistake fails the build with a code frame and the bundle doesn't
carry the code that prepares templates at runtime:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { gyralVitePreset } from '@gyral/core/vite';

export default defineConfig({
  ...gyralVitePreset(),
});
```

To see the same checks in your editor, add the ESLint config from `@gyral/core/eslint` (see
[Views](https://gyral.dev/docs/views/#checked-before-it-runs)). Optionally, `npm install -D parse5` lets the
compiler check markup against a full HTML parser too.

## Write a component

A component is a custom element defined from four parts: its initial state, the intents it
understands, how each message changes the state, and how the state looks.

```ts
// src/counter.ts
import { define, html } from '@gyral/core';

export interface State {
  readonly count: number;
}

export type Msg = { readonly _tag: 'Increment' } | { readonly _tag: 'Decrement' };

export const Counter = define<State, Msg>()('my-counter', {
  init: () => ({ count: 0 }),
  intent: {
    Increment: () => ({ _tag: 'Increment' }),
    Decrement: () => ({ _tag: 'Decrement' }),
  },
  update: {
    Increment: (s) => ({ count: s.count + 1 }),
    Decrement: (s) => ({ count: s.count - 1 }),
  },
  view: (s, i) => html`
    <button type="button" data-intent=${i.Decrement}>Decrement</button>
    <output aria-live="polite">${s.count}</output>
    <button type="button" data-intent=${i.Increment}>Increment</button>
  `,
});
```

Read it from the bottom up:

- **The view** is an `html` template. It doesn't attach event handlers. Instead it _names_ an
  intent on each button with `data-intent`. `i` is typed from your messages, so a misspelt
  `i.Incremnt` is a compile error.
- **Intent** says how a platform event becomes a message. A click on a button carrying
  `data-intent=${i.Increment}` runs the `Increment` parser, which returns
  `{ _tag: 'Increment' }`. A parser can also read the event's value, form data or key, and
  return `undefined` to decline it.
- **Update** has one reducer per message, and TypeScript checks you have one for every message.
  A reducer returns the next state and never changes the old one.
- **Init** gives the state the component starts with.

## Use it in a page

`define()` registers the element, so importing the module is enough. Replace the contents of
`index.html`'s `<body>` and import your component:

```html
<body>
  <main>
    <h1>My first Gyral app</h1>
    <my-counter></my-counter>
  </main>
  <script type="module" src="/src/counter.ts"></script>
</body>
```

Run `npm run dev` and open the address it prints. The counter is a standard custom element with
its own Shadow DOM, so it works in any page and alongside any framework.

When the page loads an entry module instead (the `basic` template's `src/main.ts`), that module
must import every component module, for its side effect. Each new component in its own file
gets a line here, such as the stepper below:

```ts
// src/main.ts
import './counter.js';
import './stepper.js';
```

A module that nothing imports never runs, so its tag is never defined: `<my-stepper>` stays an
empty unknown element. In development, Gyral warns in the console (G0014) when a tag on the page
is still undefined 3 seconds after it loaded; production builds stay silent. A component that renders another
component in its view imports that module too.

## Read input

Intents get more than the event. Here's a step size the user can type, read from the input's
`value` and parsed before it reaches the model:

```ts
// src/stepper.ts
import { define, html } from '@gyral/core';

export interface State {
  readonly count: number;
  readonly step: number;
}

export type Msg =
  { readonly _tag: 'Increment' } | { readonly _tag: 'StepChanged'; readonly step: number };

export const Stepper = define<State, Msg>()('my-stepper', {
  init: () => ({ count: 0, step: 1 }),
  intent: {
    Increment: () => ({ _tag: 'Increment' }),
    StepChanged: ({ value }) => {
      const step = Number(value);
      // Not a whole number: ignore the keystroke, keep the last good step.
      return Number.isInteger(step) ? { _tag: 'StepChanged', step } : undefined;
    },
  },
  update: {
    Increment: (s) => ({ ...s, count: s.count + s.step }),
    StepChanged: (s, m) => ({ ...s, step: m.step }),
  },
  view: (s, i) => html`
    <label for="step">Step</label>
    <input id="step" type="number" value=${s.step} data-intent=${i.StepChanged} />
    <button type="button" data-intent=${i.Increment}>Add ${s.step}</button>
    <output aria-live="polite">${s.count}</output>
  `,
});
```

The model only ever sees a whole number. Parsing happens once, at the boundary, which is where
Gyral wants it.

## Test it

`update` is a plain function, so you can test behaviour without a browser. `@gyral/testing`
gives you `step` (one message) and `run` (a sequence):

```sh
npm install -D @gyral/testing vitest
```

```ts
// src/counter.test.ts
import { expect, it } from 'vitest';
import { run, step } from '@gyral/testing';
import { Counter } from './counter.js';

it('counts', () => {
  expect(step(Counter.spec, { count: 1 }, { _tag: 'Increment' }).state).toEqual({ count: 2 });

  const { state } = run(Counter.spec, [
    { _tag: 'Increment' },
    { _tag: 'Increment' },
    { _tag: 'Decrement' },
  ]);
  expect(state.count).toBe(1);
});
```

`Counter.spec` is the object you passed to `define()`. Tests that need the real element (clicks,
focus, rendering) run in a browser with [Vitest browser mode](https://vitest.dev/guide/browser/)
and `await settled()` before they look at the DOM; `@gyral/testing` also has helpers for server
rendering, hydration and virtual time. See [Testing](https://gyral.dev/docs/testing/).

## Next steps

- Build something real from a [recipe](https://gyral.dev/docs/recipes/): a
  [todo list with filters](https://gyral.dev/docs/recipes/#a-todo-list-with-filters) and a
  [signup form with validation](https://gyral.dev/docs/recipes/#a-signup-form-with-native-validation), each a
  complete component with tests that needs nothing beyond a `basic` app.
- Learn the three parts in depth: [Intent](https://gyral.dev/docs/intent/), [Model and update](https://gyral.dev/docs/update/)
  and [Views](https://gyral.dev/docs/views/).
- Browse the [examples](https://gyral.dev/examples/): forms, HTTP, routing, shared state and server rendering.
- See a whole application in [gyral-shop](https://github.com/gyraljs/gyral-shop).
- Before you ship, read [Deploying](https://gyral.dev/docs/deploying/) and the
  [known issues](https://gyral.dev/docs/packages/#known-issues).
- Working with a coding agent? Connect it to Gyral's MCP server and skill:
  [Use Gyral with coding agents](https://gyral.dev/docs/coding-agents/).
- Upgrading an existing app? [Versioning and stability](https://gyral.dev/docs/versioning/) explains how to move
  to 0.3.6 safely.

---

# Recipes

> Complete components to copy, with their tests. A todo list with filters, a signup form with native validation, and fixes for common bugs.

Source: https://gyral.dev/docs/recipes/

Each recipe is a whole component in one file, with its tests. They need only `@gyral/core`,
plus `@gyral/testing` and Vitest for the tests, so they work in a new `basic` app from
[create-gyral](https://gyral.dev/docs/getting-started/#create-a-project). Every recipe compiles against Gyral
0.3.6, and the site tests each one in a browser when it builds.

## A todo list with filters

Add todos, tick them off, delete them, and show all, active or done ones:

```ts
// src/todo-app.ts
import { define, each, focus, html, intentsOf, type TemplateResult } from '@gyral/core';

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

export type Filter = 'all' | 'active' | 'done';

export interface State {
  readonly todos: readonly Todo[];
  readonly nextId: number;
  readonly draft: string;
  readonly filter: Filter;
}

export type Msg =
  | { readonly _tag: 'Typed'; readonly text: string }
  | { readonly _tag: 'Add'; readonly text: string }
  | { readonly _tag: 'Toggle'; readonly id: number }
  | { readonly _tag: 'Delete'; readonly id: number }
  | { readonly _tag: 'Show'; readonly filter: Filter };

const FILTERS: readonly Filter[] = ['all', 'active', 'done'];
const LABELS: Readonly<Record<Filter, string>> = { all: 'All', active: 'Active', done: 'Done' };

const isFilter = (value: string | undefined): value is Filter => FILTERS.some((f) => f === value);

/** A row's id from its control's `value`, or `undefined` for anything else. */
const idOf = (value: string | undefined): number | undefined =>
  value !== undefined && /^\d+$/.test(value) ? Number(value) : undefined;

/** The todos a filter shows. State keeps the whole list; the view shows this. */
export const visible = (todos: readonly Todo[], filter: Filter): readonly Todo[] =>
  filter === 'all' ? todos : todos.filter((t) => t.done === (filter === 'done'));

// The intent names as a module constant, so rows can use them and stay pure.
const i = intentsOf<typeof TodoApp>();

// A row reads only its todo and module constants. Its controls carry the id, never a position.
const Row = (todo: Todo): TemplateResult =>
  html`<li>
    <label>
      <input type="checkbox" value=${todo.id} ?checked=${todo.done} data-intent=${i.Toggle} />
      ${todo.text}
    </label>
    <button
      type="button"
      value=${todo.id}
      aria-label=${`Delete ${todo.text}`}
      data-intent=${i.Delete}
    >
      Delete
    </button>
  </li>`;

export const TodoApp = define<State, Msg>()('my-todo-app', {
  init: () => ({ todos: [], nextId: 1, draft: '', filter: 'all' }),
  intent: {
    Typed: ({ value }) => ({ _tag: 'Typed', text: value ?? '' }),
    Add: ({ formData }) => {
      const text = formData?.get('text');
      return typeof text === 'string' && text.trim() !== ''
        ? { _tag: 'Add', text: text.trim() }
        : undefined;
    },
    Toggle: ({ value }) => {
      const id = idOf(value);
      return id === undefined ? undefined : { _tag: 'Toggle', id };
    },
    Delete: ({ value }) => {
      const id = idOf(value);
      return id === undefined ? undefined : { _tag: 'Delete', id };
    },
    Show: ({ value }) => (isFilter(value) ? { _tag: 'Show', filter: value } : undefined),
  },
  update: {
    Typed: (s, m) => ({ ...s, draft: m.text }),
    // Clearing `draft` empties the input; focus goes back to it for the next todo.
    Add: (s, m) => [
      {
        ...s,
        todos: [...s.todos, { id: s.nextId, text: m.text, done: false }],
        nextId: s.nextId + 1,
        draft: '',
      },
      [focus('#new-todo')],
    ],
    Toggle: (s, m) => ({
      ...s,
      todos: s.todos.map((t) => (t.id === m.id ? { ...t, done: !t.done } : t)),
    }),
    // The deleted row had focus: give it to the input, not to the page body.
    Delete: (s, m) => [{ ...s, todos: s.todos.filter((t) => t.id !== m.id) }, [focus('#new-todo')]],
    Show: (s, m) => ({ ...s, filter: m.filter }),
  },
  view: (s, i) => {
    const shown = visible(s.todos, s.filter);
    const left = s.todos.filter((t) => !t.done).length;
    return html`
      <form data-intent=${i.Add}>
        <label for="new-todo">New todo</label>
        <input
          id="new-todo"
          name="text"
          autocomplete="off"
          value=${s.draft}
          data-intent=${i.Typed}
        />
        <button>Add</button>
      </form>
      <div role="group" aria-label="Show">
        ${FILTERS.map(
          (f) =>
            html`<button
              type="button"
              value=${f}
              aria-pressed=${s.filter === f}
              data-intent=${i.Show}
            >
              ${LABELS[f]}
            </button>`,
        )}
      </div>
      <ul aria-label="Todos">
        ${each(shown, (t) => t.id, Row)}
      </ul>
      <p>${shown.length === 0 ? 'Nothing to show.' : ''}</p>
      <p><output aria-live="polite">${left} left</output></p>
    `;
  },
});
```

How it works:

- **State keeps the whole list. The view filters it.** `visible(todos, filter)` is a plain
  function that the view and the tests call. The filter is state; the filtered list isn't, so
  the two can't get out of step.
- **Controls carry the id**: `value=${todo.id}`, and the parser reads `value`. A message says
  which todo, never which row. See
  [the wrong item changes](#toggling-an-item-in-a-filtered-list-changes-the-wrong-item).
- **Rows are keyed by id**: `each(shown, (t) => t.id, Row)`. A todo keeps its element when the
  filter changes or another row goes away.
- **Rows are pure.** `Row` reads only its todo and module constants, such as
  `i = intentsOf<typeof TodoApp>()`. Its return type is written out, so `Row` and `TodoApp`
  don't infer each other's types. The view uses its own `i`.
- **The input is form state.** `value=${s.draft}` follows `Typed`, and `Add` sets `draft` back
  to `''`, which empties the input. Without `draft` in state, the text would stay after Add.
- **Focus is a command.** `Add` and `Delete` return `focus('#new-todo')`, so focus never falls
  to the page body when its row is deleted.
- The filter buttons use `.map`: three buttons that never move don't need `each`.

Test the model without a browser. `run` folds messages from `init` (or from `state`), and
`parse` runs one parser without a DOM:

```ts
// src/todo-app.test.ts
import { expect, it } from 'vitest';
import { focusTargetsIn, parse, run, step } from '@gyral/testing';
import { TodoApp, visible } from './todo-app.js';

const added = run(TodoApp.spec, [
  { _tag: 'Add', text: 'Write docs' },
  { _tag: 'Add', text: 'Ship it' },
  { _tag: 'Add', text: 'Celebrate' },
]).state;

it('adds todos with their own ids and clears the input', () => {
  expect(added.todos.map((t) => [t.id, t.text])).toEqual([
    [1, 'Write docs'],
    [2, 'Ship it'],
    [3, 'Celebrate'],
  ]);
  expect(added.draft).toBe('');
  const { commands } = step(TodoApp.spec, added, { _tag: 'Add', text: 'More' });
  expect(focusTargetsIn(commands)).toEqual([{ selector: '#new-todo' }]);
});

it('toggles and deletes by id, whatever the filter shows', () => {
  const { state } = run(
    TodoApp.spec,
    [
      { _tag: 'Toggle', id: 1 },
      { _tag: 'Show', filter: 'active' },
      // "Celebrate" is the second row on screen now, but the message names it by id.
      { _tag: 'Toggle', id: 3 },
      { _tag: 'Delete', id: 2 },
    ],
    { state: added },
  );
  expect(state.todos).toEqual([
    { id: 1, text: 'Write docs', done: true },
    { id: 3, text: 'Celebrate', done: true },
  ]);
  expect(visible(state.todos, 'active')).toEqual([]);
  expect(visible(state.todos, 'done').map((t) => t.id)).toEqual([1, 3]);
});

it('reads ids and filters from the markup, and ignores anything else', () => {
  expect(parse(TodoApp, 'Toggle', { value: '3' })).toEqual({ _tag: 'Toggle', id: 3 });
  expect(parse(TodoApp, 'Toggle', { value: 'three' })).toBeUndefined();
  expect(parse(TodoApp, 'Show', { value: 'done' })).toEqual({ _tag: 'Show', filter: 'done' });
  expect(parse(TodoApp, 'Show', { value: 'archived' })).toBeUndefined();
});
```

## A signup form with native validation

No extra packages. The browser's constraint checks find what is wrong, and your own messages
say it. The [Forms](https://gyral.dev/docs/forms/#complete-example-a-validated-form) page starts with this same
component and explains each part; here it comes with its tests:

```ts
// src/account-form.ts
import { define, focus, html } from '@gyral/core';

/** The fields, in the order they appear: the first one with an error gets focus. */
export const FIELDS = ['name', 'email', 'password', 'consent'] as const;
export type Field = (typeof FIELDS)[number];

/** One message per field; `''` means no error. */
export type Errors = Readonly<Record<Field, string>>;

export const NO_ERRORS: Errors = { name: '', email: '', password: '', consent: '' };

export interface State {
  readonly errors: Errors;
  /** What the live region announces after a rejected submit; `''` otherwise. */
  readonly summary: string;
  /** The clean values after a successful signup. */
  readonly account: { readonly name: string; readonly email: string } | undefined;
}

export type Msg =
  | { readonly _tag: 'Rejected'; readonly errors: Errors }
  | { readonly _tag: 'SignedUp'; readonly name: string; readonly email: string }
  | { readonly _tag: 'Checked'; readonly field: Field; readonly error: string };

const isField = (name: string): name is Field => FIELDS.some((f) => f === name);

/**
 * Your message for a field's first problem, from the browser's own checks (`validity`), or
 * `''` when the field is fine. The constraints in the markup (`required`, `type="email"`,
 * `minlength`) still decide what is wrong; `novalidate` only stops the browser from
 * blocking the submit and showing its own bubble.
 */
export function problemWith(input: HTMLInputElement): string {
  const { validity } = input;
  // A checkbox is missing when unchecked. `required` accepts "   ", so blank text is missing too.
  const missing =
    input.type === 'checkbox' ? !input.checked : validity.valueMissing || input.value.trim() === '';
  switch (input.name) {
    case 'name':
      return missing ? 'Enter your name.' : '';
    case 'email':
      if (missing) return 'Enter your email address.';
      return validity.typeMismatch ? 'Enter an email address like ada@example.com.' : '';
    case 'password':
      if (missing) return 'Enter a password.';
      // `tooShort` is set only for typed values; the length check also covers a pre-filled one.
      return validity.tooShort || input.value.length < input.minLength
        ? 'Use at least 8 characters.'
        : '';
    case 'consent':
      return missing ? 'Accept the privacy policy to continue.' : '';
    default:
      return '';
  }
}

/** What the status region announces after a successful signup. */
const welcome = (account: State['account']): string =>
  account === undefined ? '' : `Welcome, ${account.name}! We’ll write to ${account.email}.`;

/** Reads a submitted form: every field's error, or the clean values. */
function submission(form: Element, data: FormData | undefined): Msg | undefined {
  if (!(form instanceof HTMLFormElement) || data === undefined) return undefined;
  const errors: Record<Field, string> = { ...NO_ERRORS };
  for (const field of FIELDS) {
    const input = form.elements.namedItem(field);
    if (input instanceof HTMLInputElement) errors[field] = problemWith(input);
  }
  if (FIELDS.some((f) => errors[f] !== '')) return { _tag: 'Rejected', errors };
  const text = (field: Field): string => {
    const value = data.get(field);
    return typeof value === 'string' ? value.trim() : '';
  };
  // The password stays in the form data: never keep it in state.
  return { _tag: 'SignedUp', name: text('name'), email: text('email') };
}

export const AccountForm = define<State, Msg>()('my-account-form', {
  init: () => ({ errors: NO_ERRORS, summary: '', account: undefined }),
  intent: {
    // Not a message tag, so it may return either message.
    Submit: ({ target, formData }) => submission(target, formData),
    // Text fields send it on `input`, the checkbox on `change`.
    Checked: ({ target }) =>
      target instanceof HTMLInputElement && isField(target.name)
        ? { _tag: 'Checked', field: target.name, error: problemWith(target) }
        : undefined,
  },
  update: {
    // Show every error at once, announce how many, and focus the first field that has one.
    Rejected: (s, m) => {
      const count = FIELDS.filter((f) => m.errors[f] !== '').length;
      const first = FIELDS.find((f) => m.errors[f] !== '');
      const summary = `Fix ${String(count)} ${count === 1 ? 'field' : 'fields'} to continue.`;
      const focusFirst = first === undefined ? [] : [focus(`#${first}`)];
      return [{ ...s, errors: m.errors, summary }, focusFirst];
    },
    // In an app, this also returns the command that posts the form.
    SignedUp: (_s, m) => ({
      errors: NO_ERRORS,
      summary: '',
      account: { name: m.name, email: m.email },
    }),
    // While the user types, only a field that already shows an error is checked again,
    // so a message changes or disappears as soon as the value is fixed.
    Checked: (s, m) =>
      s.errors[m.field] === '' ? s : { ...s, errors: { ...s.errors, [m.field]: m.error } },
  },
  // No `value` bindings: what the user typed stays in the fields after a rejected submit.
  view: (s, i) => html`
    <form novalidate data-intent=${i.Submit}>
      <p role="alert">${s.summary}</p>

      <label for="name">Name</label>
      <input
        id="name"
        name="name"
        autocomplete="name"
        required
        aria-invalid=${s.errors.name !== ''}
        aria-describedby="name-error"
        data-intent=${i.Checked}
      />
      <p id="name-error">${s.errors.name}</p>

      <label for="email">Email</label>
      <input
        id="email"
        name="email"
        type="email"
        autocomplete="email"
        required
        aria-invalid=${s.errors.email !== ''}
        aria-describedby="email-error"
        data-intent=${i.Checked}
      />
      <p id="email-error">${s.errors.email}</p>

      <label for="password">Password</label>
      <input
        id="password"
        name="password"
        type="password"
        autocomplete="new-password"
        required
        minlength="8"
        aria-invalid=${s.errors.password !== ''}
        aria-describedby="password-error"
        data-intent=${i.Checked}
      />
      <p id="password-error">${s.errors.password}</p>

      <input
        id="consent"
        name="consent"
        type="checkbox"
        required
        aria-invalid=${s.errors.consent !== ''}
        aria-describedby="consent-error"
        data-intent=${i.Checked}
      />
      <label for="consent">I accept the privacy policy</label>
      <p id="consent-error">${s.errors.consent}</p>

      <button>Create account</button>
    </form>
    <p role="status">${welcome(s.account)}</p>
  `,
});
```

How it works:

- **`novalidate` on the form, constraints on the fields.** `required`, `type="email"` and
  `minlength` still set each field's `validity`. `novalidate` stops the browser from blocking
  the submit. Without it, a failing constraint shows the browser's bubble and no `submit` event
  fires, so your messages never appear.
- **The submit parser reads `validity`.** `problemWith(input)` turns `valueMissing`,
  `typeMismatch`, `tooShort` and an unchecked checkbox into your words. `Submit` checks every
  field and returns `Rejected` with all the errors, or `SignedUp` with clean values. Reading the
  form is input parsing, the intent layer's job; reducers see only the result.
- **Check what the browser doesn't.** `required` accepts a name made of spaces, so the parser
  trims first. `tooShort` is set only after the user types, not for a value set by script or
  rendered by a server, so the parser checks the length too.
- **Errors are state**: one string per field, `''` for none. The view writes `aria-invalid` and
  the message, and `aria-describedby` links the message to its field.
- **Focus goes to the first invalid field**, through a `focus()` command from `Rejected`,
  and the `role="alert"` paragraph announces how many fields to fix.
- **An error clears as soon as the field is fixed.** Each field sends `Checked` on input (the
  checkbox on change). The reducer updates only a field that already shows an error, so nothing
  turns red while someone is still typing.
- **Enter submits.** The form has a submit button, so Enter in any field submits it, like a
  click.
- **No password in state.** `SignedUp` carries the name and the email. To send the form to a
  server, keep the raw `FormData` in the message and post it with a command, as in
  [Submitting to the server](https://gyral.dev/docs/forms/#submitting-to-the-server).

The reducers are tested without a browser:

```ts
// src/account-form.test.ts
import { expect, it } from 'vitest';
import { focusTargetsIn, run, step } from '@gyral/testing';
import { AccountForm, NO_ERRORS } from './account-form.js';

const rejected = {
  name: '',
  email: 'Enter an email address like ada@example.com.',
  password: 'Use at least 8 characters.',
  consent: '',
};

it('shows every error, announces how many and focuses the first invalid field', () => {
  const { state, commands } = step(
    AccountForm.spec,
    { errors: NO_ERRORS, summary: '', account: undefined },
    { _tag: 'Rejected', errors: rejected },
  );
  expect(state.errors).toEqual(rejected);
  expect(state.summary).toBe('Fix 2 fields to continue.');
  expect(focusTargetsIn(commands)).toEqual([{ selector: '#email' }]);
});

it('clears an error as soon as the field is fixed, and leaves untouched fields alone', () => {
  const { state } = run(AccountForm.spec, [
    { _tag: 'Rejected', errors: rejected },
    { _tag: 'Checked', field: 'email', error: '' },
    { _tag: 'Checked', field: 'name', error: 'Enter your name.' },
  ]);
  expect(state.errors).toEqual({ ...rejected, email: '' });
});

it('welcomes the new user and forgets old errors', () => {
  const { state } = run(AccountForm.spec, [
    { _tag: 'Rejected', errors: rejected },
    { _tag: 'SignedUp', name: 'Ada', email: 'ada@example.com' },
  ]);
  expect(state).toEqual({
    errors: NO_ERRORS,
    summary: '',
    account: { name: 'Ada', email: 'ada@example.com' },
  });
});
```

The submit parser reads the form's fields, so test it in a browser too. In a `basic` app,
`npm test` runs both files in Chromium. `mount()` sets values with script, which is why the
parser's own length check matters:

```ts
// src/account-form.browser.test.ts
import { expect, it } from 'vitest';
import { mount } from '@gyral/testing';
import { AccountForm } from './account-form.js';

it('reads the browser’s checks on submit and focuses the first invalid field', async () => {
  const form = await mount(AccountForm);
  await form.type('#email', 'ada');
  await form.type('#password', 'short');
  await form.click('button');

  expect(form.$('[role="alert"]')?.textContent).toBe('Fix 4 fields to continue.');
  expect(form.$('#name-error')?.textContent).toBe('Enter your name.');
  expect(form.$('#email-error')?.textContent).toBe('Enter an email address like ada@example.com.');
  expect(form.$('#password-error')?.textContent).toBe('Use at least 8 characters.');
  expect(form.$('#consent-error')?.textContent).toBe('Accept the privacy policy to continue.');
  expect(form.el.shadowRoot?.activeElement?.id).toBe('name');

  await form.type('#name', '  Ada  ');
  expect(form.$('#name-error')?.textContent).toBe('');
  await form.type('#email', 'ada@example.com');
  await form.type('#password', 'correct horse');
  await form.click('#consent');
  expect(form.$('#consent-error')?.textContent).toBe('');
  await form.click('button');
  expect(form.$('[role="status"]')?.textContent).toBe(
    'Welcome, Ada! We’ll write to ada@example.com.',
  );
  form.dispose();
});
```

To validate on the server with the same rules, use one schema for both sides:
[Forms](https://gyral.dev/docs/forms/#one-schema-for-both-sides).

## Troubleshooting

### Toggling an item in a filtered list changes the wrong item

**What you see.** With a filter on, ticking a row ticks a different item, often one that isn't
shown.

**Why.** The control carries the row's position, and the reducer uses it as an index into the
whole list:

```ts
// Wrong: in the view, `n` is the row's place in the filtered list…
${visible(s.todos, s.filter).map(
  (t, n) => html`<input type="checkbox" value=${n} data-intent=${i.Toggle} />`,
)}

// …and the reducer reads it as a place in the whole list.
Toggle: (s, m) => ({
  ...s,
  todos: s.todos.map((t, n) => (n === m.index ? { ...t, done: !t.done } : t)),
}),
```

With "Active" showing, the second row on screen may be the fourth todo, so the reducer changes
`s.todos[1]` instead. A sort or a search breaks it the same way.

**Fix.** Carry the id, and find the item by id:

- Put `value=${todo.id}` on the control, and parse `value` as an id.
- Match by id in the reducer: `t.id === m.id`.
- Key the list by id: `each(shown, (t) => t.id, Row)`.

A key alone doesn't fix it. The key keeps each element with its item; the message still has to
say which item. The [todo list](#a-todo-list-with-filters) recipe does all three.

### Custom error messages never show

**What you see.** Submitting an empty form shows the browser's bubble ("Please fill out this
field"), and your parser never runs.

**Why.** Without `novalidate`, the browser checks `required`, `type="email"`, `minlength` and
`pattern` before it fires `submit`. When one fails, there is no `submit` event, so there is no
intent.

**Fix.** Add `novalidate` to the `<form>` and keep the constraints on the fields. Read each
field's `validity` in the submit parser, as the
[signup form](#a-signup-form-with-native-validation) does.

---

# Use Gyral with coding agents

> Connect Claude Code, VS Code or any MCP client to the Gyral MCP server, hosted or local, install the agent skill, and give agents llms-small.txt.

Source: https://gyral.dev/docs/coding-agents/

A coding agent writes better Gyral code when it can look things up instead of guessing. Gyral
gives agents four things, and they work together:

- **The MCP server**, `@gyral/mcp`: searches these docs, returns exact API signatures and
  working examples, scaffolds components, and typechecks code against your project. It runs
  locally or at `https://mcp.gyral.dev/mcp`.
- **The agent skill**: the rules and the API in a form agents load on demand.
- **[llms-small.txt](https://gyral.dev/llms-small.txt)**: the rules, one complete component and tested recipes
  in one small file.
- **An `AGENTS.md`** in every app `create-gyral` makes.

## The hosted MCP server

`https://mcp.gyral.dev/mcp` is a public MCP server over Streamable HTTP. It needs no token and
no install, and it only reads: it answers from Gyral's docs, API and examples.

In Claude Code:

```sh
claude mcp add --transport http gyral https://mcp.gyral.dev/mcp
```

In VS Code, add it to `.vscode/mcp.json`:

```json
{ "servers": { "gyral": { "type": "http", "url": "https://mcp.gyral.dev/mcp" } } }
```

Any other client that speaks Streamable HTTP: add a server with the URL
`https://mcp.gyral.dev/mcp` and no authentication.

The hosted server has every tool except `check_snippet`, which needs your project's
TypeScript and packages. It can run an older `@gyral/mcp` than the latest release; its
`initialize` response and `https://mcp.gyral.dev/healthz` report the version it serves. This
page describes the tools as `@gyral/mcp` 0.3.6 provides them.

## The local MCP server

Run the server on your machine when the agent writes code. It adds `check_snippet`, which
typechecks against the TypeScript and `@gyral/*` versions installed in your project
(TypeScript 5 or 6; TypeScript 7 has no compiler API, so there it asks you to run your own
typecheck), and
`scaffold_component` reads your `package.json`. Start it from the project directory:

```sh
claude mcp add gyral -- npx -y @gyral/mcp
```

That's Claude Code. Other clients:

- **Codex**: `codex mcp add gyral -- npx -y @gyral/mcp`
- **Cursor**, in `.cursor/mcp.json`:

  ```json
  { "mcpServers": { "gyral": { "command": "npx", "args": ["-y", "@gyral/mcp"] } } }
  ```

- **VS Code**, in `.vscode/mcp.json`:

  ```json
  { "servers": { "gyral": { "type": "stdio", "command": "npx", "args": ["-y", "@gyral/mcp"] } } }
  ```

- **Any other client**: run `npx -y @gyral/mcp` as a stdio server.

npx fetches the latest `@gyral/mcp` release unless your project has another version installed.

The local server answers from the docs bundled with its own version, so it works offline and
matches the Gyral you install. Set `GYRAL_DOCS_URL=https://gyral.dev/llms-full.txt` to load
the latest docs at startup instead; it falls back to the bundled copy after 3 seconds.
`GYRAL_PROJECT_DIR` points `check_snippet` at another directory than the working one.

## The tools

| Tool                 | What it returns                                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `start_here`         | The mental model, the rules, the workflow, and which example or guide covers which task                                    |
| `search_docs`        | Ranked doc sections for a query: title, URL and snippet                                                                    |
| `get_doc`            | One docs page, or one section with `#anchor`, such as `forms#the-server-half`                                              |
| `get_api`            | The declaration, doc comment and import line of an export, with usage code and the next call; on a miss, the nearest names |
| `list_examples`      | Every example and what it shows                                                                                            |
| `get_example`        | One example's component source                                                                                             |
| `scaffold_component` | Starting code: `basic`, `form`, `form-native` or `ssr-page`, importing only what you have                                  |
| `check_snippet`      | Type errors for a module against your project, with a suggested fix for each (local only)                                  |

The workflow the server teaches, first in its instructions and in every tool description: call
`start_here` once, start from `get_example` or `scaffold_component`, write the module right
away, then run `check_snippet` and apply its suggested fixes until it passes. Use `get_api` only
for a name you already saw in an example or an error, not to read the API type by type.

`get_api` steers back to that loop. On a function with a matching example, such as
`define`, `each`, `fieldErrors` or `every`, it adds a short usage module and the call that gives
working code for the task, such as `scaffold_component({ tag: "signup-form", kind: "form-native" })`.
On a type, it adds a note that TypeScript infers it and that the real type errors come from
`check_snippet` (on the local server) or your typecheck. `get_api("*")` groups the functions by task, with the example or scaffold to start from,
and collapses the types into one line. The local stdio server also counts reads (every docs, API and example lookup) since the
agent last called `scaffold_component` or `check_snippet`: from the third `get_example`, the
fourth `get_api` or the eighth read of any kind, its answers end with a nudge that names the
examples read and suggests adapting the closest one, then `check_snippet`. The HTTP server, hosted or your own, keeps no
state between requests, so it never nudges.

`scaffold_component` imports only packages your project has installed, and
writes a model test only when `@gyral/testing` and `vitest` are there. `form-native` needs no
dependencies: it turns the browser's own constraint checks into your messages. `check_snippet`
also flags Gyral mistakes TypeScript can't see, such as a one-call `define` or side effects in
`update`.

The server also offers the resources `gyral://llms.txt`, `gyral://skill` and
`gyral://skill/references/{name}`, and a `build-gyral-component` prompt.

### Host your own

`gyral-mcp http` runs the server behind the hosted one: read-only, anonymous Streamable HTTP
at `/mcp`, without `check_snippet`. It listens on `127.0.0.1:3000` by default, and needs
`GYRAL_MCP_PUBLIC_ORIGIN` set to the origin it's served from:

```sh
GYRAL_MCP_PUBLIC_ORIGIN=http://127.0.0.1:3000 npx -y @gyral/mcp http
```

It is configured by environment variables only; `gyral-mcp http --help` lists them. Put it
behind TLS, and pin the package version you deploy. The
[package README](https://github.com/gyraljs/gyral/blob/v0.3.6/packages/mcp/README.md#public-hosting)
has the details.

## The agent skill

The skill teaches an agent the rules and the API, with a reference per topic that it loads
when the task needs it. Every code block in it typechecks against the packages.
`SKILL.md` opens with where to start from working code (the recipes, llms-small.txt and the MCP
loop) and the rule that the entry must import every component module, and its forms reference
starts with native validation, as the [Forms guide](https://gyral.dev/docs/forms/) does.

In Claude Code, add Gyral's repository as a plugin marketplace and install the plugin:

```text
/plugin marketplace add gyraljs/gyral
/plugin install gyral@gyral
```

From a shell: `claude plugin marketplace add gyraljs/gyral && claude plugin install gyral@gyral`.

Other agents: copy
[`skills/gyral/`](https://github.com/gyraljs/gyral/tree/v0.3.6/skills/gyral) into the agent's
skills or rules folder, or point it at `SKILL.md`.

## Docs for agents

- **[llms-small.txt](https://gyral.dev/llms-small.txt)**: read first. The mental model, MUST and DO NOT rules, a
  complete component with tests, the recipes, and where each export comes from, in under
  40 KB. Every code block in it compiles against the released packages.
- **[llms.txt](https://gyral.dev/llms.txt)**: the index of every page, each with a line on when to read it.
- **[llms-full.txt](https://gyral.dev/llms-full.txt)**: all the docs, the API reference and the examples in one
  file.
- Every docs page has a Markdown copy: add `index.md` to its URL, as in
  `/docs/testing/index.md`.

## New apps

`npm create gyral@latest` writes an `AGENTS.md` into every project, and a `CLAUDE.md` that
imports it, so an agent that opens the project learns the rules and the commands before it
writes anything. See [Getting started](https://gyral.dev/docs/getting-started/#create-a-project).

---

# Components

> How define() turns a spec into a custom element, and how components pass data to each other with props and outputs.

Source: https://gyral.dev/docs/components/

A Gyral component is a standard custom element. You don't write a class: you describe the
component as data, and `define()` builds the element, a plain `HTMLElement` subclass. This page covers the parts of that
description, then how components talk to each other: **props down, outputs up**.

## Anatomy of define()

```ts
// src/greeter.ts
import { define, html } from '@gyral/core';

export interface State {
  readonly name: string;
}

export type Msg = { readonly _tag: 'NameChanged'; readonly name: string };

export const Greeter = define<State, Msg>()('my-greeter', {
  init: () => ({ name: '' }),
  intent: {
    NameChanged: ({ value }) => ({ _tag: 'NameChanged', name: value ?? '' }),
  },
  update: {
    NameChanged: (s, m) => ({ ...s, name: m.name.trim() }),
  },
  view: (s, i) => html`
    <label for="name">Your name</label>
    <input id="name" autocomplete="given-name" data-intent=${i.NameChanged} />
    <p>${s.name === '' ? 'Hello!' : `Hello, ${s.name}!`}</p>
  `,
});
```

`define<State, Msg>()(tag, spec)` registers `<my-greeter>` and returns its class. It is two
calls: the first takes the types you write (state, messages, props, outputs), the second the
tag and spec, so TypeScript can still infer the intent names from the spec's `intent` keys. A
component needs `init` and `view`; `intent` and `update` come with messages, and the rest is
optional:

| Part            | What it is                                                                                                     | Guide                                                                                                 |
| --------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `init`          | The starting state, computed from props. May also start one-shot commands.                                     | [Model and update](https://gyral.dev/docs/update/)                                                                     |
| `subscriptions` | The long-running commands that should be running for this state and props (clocks, feeds, watches).            | [Subscriptions](https://gyral.dev/docs/update/#subscriptions)                                                          |
| `intent`        | Parsers that turn platform events into messages. Their keys are the component's intent names.                  | [Intent](https://gyral.dev/docs/intent/)                                                                               |
| `update`        | One pure reducer per message tag: state in, next state (and commands) out.                                     | [Model and update](https://gyral.dev/docs/update/)                                                                     |
| `view`          | A pure function from state to an `html` template that _names_ intents.                                         | [Views](https://gyral.dev/docs/views/)                                                                                 |
| `props`         | Inputs from the parent or from attributes, declared with `prop.*` builders.                                    | [below](#props)                                                                                       |
| `styles`        | Shadow-root CSS: `css` values or strings.                                                                      | [Styling](https://gyral.dev/docs/styling/)                                                                             |
| `stores`        | Shared state the component reads.                                                                              | [Shared state](https://gyral.dev/docs/stores/)                                                                         |
| `shadow`        | `false` renders into light DOM; `{ delegatesFocus: true }` passes focus to the first focusable element inside. | [Styling](https://gyral.dev/docs/styling/#light-dom-components), [Views](https://gyral.dev/docs/views/#focusing-into-a-child-component) |
| `hydrate`       | When a server-rendered instance hydrates: `load`, `idle`, `visible`, `interaction`.                            | [Server rendering](https://gyral.dev/docs/server-rendering/)                                                           |

A few more optional fields cover rarer needs: `error` (a fallback view, see
[Error handling](https://gyral.dev/docs/error-handling/)), `states`
(custom states for CSS, see [Styling](https://gyral.dev/docs/styling/#custom-states)), `viewTransition` (render a
change inside a View Transition, see [Views](https://gyral.dev/docs/views/#view-transitions)), `renderOnFrame`
(message tags from bursty sources, such as a socket feed or a sensor, that render once per
animation frame), and `formAssociated` (a component that takes part in a native form, see
[Custom form controls](https://gyral.dev/docs/form-associated/)).

The type parameters are the contract. `State` is a plain data record (JSON, when the component
is [server-rendered](https://gyral.dev/docs/server-rendering/#loading-components-in-the-browser)), `Msg` a union of tagged objects, and TypeScript checks that `update` has a reducer for every tag and that the view
only names intents that exist.

`define()` registers the tag when its module runs, so the page's entry module (or a module it
imports) must import every component module: `import './greeter.js';` in `src/main.ts`. A
component module that nothing imports never runs, and its tag stays an empty unknown element;
development builds warn (G0014) when a tag is still undefined 3 seconds after the page loaded. A parent that renders a child imports it too, as `Total` imports `Stepper`
[below](#child-components-and-outputs).

`define()` returns the element class. Its `spec` property is the object you passed in, which is
how [tests](https://gyral.dev/docs/testing/) run `update` without a DOM. Export it as
`export const Greeter = define…`, and the Vite preset writes `HTMLElementTagNameMap` entries for
every such component into `.gyral/elements.d.ts` (list that file in your tsconfig's `include`),
so `document.querySelector('my-greeter')` is typed with no declaration of your own. It reads
calls in code, not in comments or strings. For `tsc` outside Vite, the
`gyral-types` command writes the same file.

## Props

Props are the component's inputs. Declare each one with a `prop` builder. A builder says how
an attribute's string becomes a value, and a prop whose type can't be `undefined` must say how a
value is guaranteed: `required` or `default`.

```ts
// src/badge.ts
import { define, html, prop, type Stateless } from '@gyral/core';

export interface Props {
  readonly label: string;
  readonly count: number;
  readonly note: string | undefined;
}

export const Badge = define<Stateless, never, Props>()('my-badge', {
  props: {
    label: prop.string({ required: true }),
    count: prop.number({ default: 0 }),
    note: prop.string(),
  },
  intent: {},
  update: {},
  view: (_s, _i, { props }) => html`
    <span>${props.label}: <data value=${props.count}>${props.count}</data></span>
    ${props.note === undefined ? '' : html`<small>${props.note}</small>`}
  `,
});
```

- **Read props as context.** Every reducer and the view get `{ props }` as their last argument.
  Don't copy props into state just to read them.
- **`required: true`** is a promise from the parent. A missing value logs one warning per
  instance at first render.
- **`default`** is used whenever the element's own value is missing.
- A component with no state of its own uses `Stateless` and can leave out `init`.
- Don't name a prop after a built-in element property such as `hidden`, `title` or `id`. It is
  an error in development, because the prop would replace the platform's behaviour.

### Builders and attributes

| Builder                     | The attribute is parsed with           | Attribute name         |
| --------------------------- | -------------------------------------- | ---------------------- |
| `prop.string(opts?)`        | nothing: the string as is              | kebab-case of the prop |
| `prop.number(opts?)`        | `Number(v)`; empty or `NaN` is invalid | kebab-case             |
| `prop.boolean(opts?)`       | present is `true`, absent is `false`   | kebab-case             |
| `prop.json(schema, opts?)`  | `JSON.parse`, then the schema          | kebab-case             |
| `prop.value(schema, opts?)` | no attribute: set it as a property     | none                   |

A prop named `maxValue` reads the attribute `max-value`; pass `attribute: 'name'` to choose
another, or `attribute: false` for a property only. The options are `required`, `default`,
`attribute` and `schema`, and `equals` for `prop.json` and `prop.value`
([below](#when-a-prop-counts-as-changed)).

The schemas are [Standard Schema](https://standardschema.dev), so any library that implements it
works: valibot, zod, ArkType. `string`, `number` and `boolean` carry tiny built-in schemas, so
simple props need no library; pass `schema` to narrow one, such as
`prop.string({ schema: v.picklist(['asc', 'desc']), default: 'asc' })`.

Attributes are strings from outside your code, so they are **always validated**. An invalid
value is logged with the tag, the prop and the schema's issues, then treated as missing, so its
`default` applies. Property sets come from typed code and are validated in development only.
Props never write attributes back; state that CSS needs goes through
[custom states](https://gyral.dev/docs/styling/#custom-states).

### Objects, type guards and identity

Objects and arrays travel as properties, declared with `prop.value`. Its check can be a
Standard Schema or a plain type guard:

```ts
// src/seat-picker.ts
import * as v from 'valibot';
import { define, html, prop, type PropsOf, type Stateless } from '@gyral/core';

export interface Seat {
  readonly row: number;
  readonly label: string;
}

/** A type guard: the simplest check for a property. */
const isSeat = (u: unknown): u is Seat =>
  typeof u === 'object' &&
  u !== null &&
  'row' in u &&
  typeof u.row === 'number' &&
  'label' in u &&
  typeof u.label === 'string';

/** Declared once and passed by name, so production builds can leave it out. */
const Seats = v.array(v.object({ row: v.number(), label: v.string() }));

const props = {
  seats: prop.value(Seats, { default: [] }),
  chosen: prop.value(isSeat),
  /** `null` means "nobody"; leaving it unset means the default. */
  holder: prop.value(v.nullable(v.string()), { default: 'Box office' }),
};

export const SeatPicker = define<Stateless, never, PropsOf<typeof props>>()('my-seat-picker', {
  props,
  intent: {},
  update: {},
  view: (_s, _i, { props: p }) => html`
    <p>${p.seats.length} seats, held by ${p.holder ?? 'nobody'}</p>
    ${p.chosen === undefined ? '' : html`<p>Chosen: ${p.chosen.label}</p>`}
  `,
});
```

- **A type guard** `(u: unknown) => u is T` works in `prop.value()` and `prop.json()`, and the
  prop's type is its `T`. A guard that returns `false` is reported like a schema issue, with the
  guard's name.
- **A property keeps the object it was given**: after `el.seats = seats`, `el.seats === seats`.
  Development checks the value and keeps the input, not the schema's output; production skips
  the check. So a schema for a property should **check, not decode**: turning strings into
  `Date`s, filling in defaults or stripping keys would happen only to attributes, whose value is
  the parse's output.
- **Declare a schema once and pass it by name.** Production client builds never run a
  `prop.value` check, and the Vite preset removes it when it is a name (`prop.value(Seats)`,
  `schemas.seat`) or an inline function, so the schema's code can leave the bundle. A call
  written in place, such as `prop.value(v.array(Seat))`, stays, because evaluating it could have
  effects. `prop.json` keeps its check: attributes are always parsed.
- **Whether the schema really leaves is up to the bundler.** Vite 8.3 (Rolldown) keeps schema
  code in a lazily loaded chunk once the schema library sits in a chunk shared with the entry,
  even when its builders are marked free of side effects. So the saving shows in single-chunk
  builds, and for schemas whose library isn't shared across chunks.
- **`null` for an explicit "nobody".** A `default` replaces only `undefined`: setting a prop to
  `undefined`, or removing its attribute, brings the default back. Make the schema nullable and
  pass `.holder=${null}` (or the attribute `holder="null"` with `prop.json`).

### When a prop counts as changed

A write whose value equals the old one changes nothing: no render, no `PropsChanged`. That
holds for property sets and attribute changes alike, so a parent may write the same value on
every render without making the child do any work.

| Builder                       | Equal when                                                 |
| ----------------------------- | ---------------------------------------------------------- |
| `string`, `number`, `boolean` | `Object.is(old, new)`                                      |
| `json`                        | `JSON.stringify` gives the same text (it is JSON data)     |
| `value`                       | `Object.is(old, new)`, or what its `equals` option returns |

So a parent can bind a fresh object on every render, `.range=${{ min: s.min, max: s.max }}`, to
a `prop.json` prop: the same JSON is the same value. Keys in a different order only cost an
extra render. `prop.value` holds anything, class instances and DOM nodes included, so it keeps
identity unless you say what "the same" means. `equals` receives the old and the new value,
`undefined` when unset, and `prop.json` takes it too:

```ts
// src/results-table.ts
import { define, html, prop, type PropsOf, type Stateless } from '@gyral/core';

export interface Sort {
  readonly key: string;
  readonly dir: 'asc' | 'desc';
}

const isSort = (u: unknown): u is Sort =>
  typeof u === 'object' &&
  u !== null &&
  'key' in u &&
  typeof u.key === 'string' &&
  'dir' in u &&
  (u.dir === 'asc' || u.dir === 'desc');

const isRange = (u: unknown): u is { readonly min: number; readonly max: number } =>
  typeof u === 'object' &&
  u !== null &&
  'min' in u &&
  typeof u.min === 'number' &&
  'max' in u &&
  typeof u.max === 'number';

const sortLabel = (sort: Sort): string =>
  `Sorted by ${sort.key}, ${sort.dir === 'asc' ? 'ascending' : 'descending'}`;

const props = {
  /** Compared by JSON text: a fresh but equal object changes nothing. */
  range: prop.json(isRange, { default: { min: 0, max: 100 } }),
  /** Compared field by field, instead of by identity. */
  sort: prop.value(isSort, { equals: (a, b) => a?.key === b?.key && a?.dir === b?.dir }),
};

export const ResultsTable = define<Stateless, never, PropsOf<typeof props>>()('my-results-table', {
  props,
  intent: {},
  update: {},
  view: (_s, _i, { props: p }) => html`
    <p>Prices ${p.range.min} to ${p.range.max}</p>
    ${p.sort === undefined ? '' : html`<p>${sortLabel(p.sort)}</p>`}
  `,
});
```

When no `equals` fits, keep bound objects stable in the parent instead: build them in a reducer,
so they live in state, rather than in the view, so an unchanged object is the same object.

### Reacting to prop changes

When a declared prop changes after the first render, the component receives the framework
message `PropsChanged`, with the new and previous props (a write of an [equal
value](#when-a-prop-counts-as-changed) sends nothing). Its reducer is optional. It is the only
way props enter state, so "reset when the user changes" is explicit:

```ts
// src/user-notes.ts
import { define, html, prop } from '@gyral/core';

export interface State {
  readonly draft: string;
}

export type Msg = { readonly _tag: 'Typed'; readonly text: string };

export const UserNotes = define<State, Msg, { readonly userId: string }>()('my-user-notes', {
  props: { userId: prop.string({ required: true }) },
  init: () => ({ draft: '' }),
  intent: { Typed: ({ value }) => ({ _tag: 'Typed', text: value ?? '' }) },
  update: {
    Typed: (s, m) => ({ ...s, draft: m.text }),
    // A different user: start a fresh draft.
    PropsChanged: (s, m) => (m.props.userId === m.prev.userId ? s : { draft: '' }),
  },
  view: (s, i, { props }) => html`
    <label for="notes">Note about ${props.userId}</label>
    <input id="notes" data-intent=${i.Typed} value=${s.draft} />
  `,
});
```

Like any reducer, the `PropsChanged` reducer may return commands, for example to load data for
the new user.

## Child components and outputs

A parent sets a child's props in its view, as attributes (`step="5"`) or as properties
(`.step=${5}`, the way objects and arrays travel), and listens to the child's **outputs**. A
child reports up by returning an output from a reducer, a command like any other, so the child
stays pure and testable. Build the helper once with `const emit = outputs<Out>()`, a module
constant like `intentsOf<typeof Component>()`: typed by the output union, so an output of the
wrong shape fails to compile in the child.

```ts
// src/stepper.ts
import { define, html, outputs, prop, type Stateless } from '@gyral/core';

/** What the stepper tells its parent. */
export type StepperOutput = { readonly _tag: 'Stepped'; readonly by: number };

const emit = outputs<StepperOutput>();

type Msg = { readonly _tag: 'Step'; readonly by: number };

export const Stepper = define<Stateless, Msg, { readonly step: number }, StepperOutput>()(
  'my-stepper',
  {
    props: { step: prop.number({ default: 1 }) },
    intent: {
      Step: ({ value }) => ({ _tag: 'Step', by: Number(value) }),
    },
    update: {
      Step: (s, m, { props }) => [s, [emit({ _tag: 'Stepped', by: m.by * props.step })]],
    },
    view: (_s, i, { props }) => html`
      <button type="button" value="-1" data-intent=${i.Step}>−${props.step}</button>
      <button type="button" value="1" data-intent=${i.Step}>+${props.step}</button>
    `,
  },
);
```

The fourth type parameter is the output union. The parent parses outputs as intents, with
`child()`, which types the output by the child class:

```ts
// src/total.ts
import { child, define, html } from '@gyral/core';
import { Stepper } from './stepper.js';

export interface State {
  readonly total: number;
}

export type Msg = { readonly _tag: 'Add'; readonly by: number };

export const Total = define<State, Msg>()('my-total', {
  init: () => ({ total: 0 }),
  intent: {
    Add: child(Stepper, (out) => ({ _tag: 'Add', by: out.by })),
  },
  update: {
    Add: (s, m) => ({ total: s.total + m.by }),
  },
  view: (s, i) => html`
    <my-stepper .step=${5} data-intent=${i.Add}></my-stepper>
    <p>Total: <output>${s.total}</output></p>
  `,
});
```

- Outputs are delivered as a `gyral-output` event from the child's host, and they reach only
  the direct parent: once the parent's `child()` intent takes one, it goes no further. A
  grandchild's outputs never reach the grandparent, and content slotted into a child belongs to
  the component that wrote it.
- Leave the mapper's return type off, as above. Annotating it with the whole union,
  `(out): Msg => …`, fails with a long `IntentParser<…>` error, because each intent produces its
  own variant (see [Intent](https://gyral.dev/docs/intent/#typing-parsers)).
- The mapper also receives the child element, typed with its props, which is how an item in a
  list says which item it is: `child(Item, (out, el) => ({ _tag: 'Item', id: el.itemId, out }))`.
- For lists, render children with `each(items, key, row)`. Keys keep each child, and its state,
  attached to its item when the list reorders (see [Views](https://gyral.dev/docs/views/#lists)).
- A component that contains itself (a folder tree) passes a function, `child(() => Folder, …)`,
  so the class can refer to itself.

Shadow DOM does the isolating, and `each` does the list.

### Outputs and other code

A parent that isn't a Gyral component, such as page script or an element from another library,
hears a Gyral child's outputs as events. `OUTPUT_EVENT` (`'gyral-output'`) names the event, its
`detail` is the output, and `OutputEvent<OutputsOf<typeof Child>>` types it:

```ts
// src/reviews.ts
import { OUTPUT_EVENT, type OutputEvent, type OutputsOf } from '@gyral/core';
import { Stepper } from './stepper.js';

// Listen on the child or on an ancestor in the same tree.
document.querySelector('#reviews')?.addEventListener(OUTPUT_EVENT, (event) => {
  const { detail } = event as OutputEvent<OutputsOf<typeof Stepper>>;
  console.log(`Stepped by ${String(detail.by)}`, event.target);
});
```

The event bubbles but isn't composed, so it stays in the tree the child sits in. The other
direction works too: any custom element talks to a Gyral parent by dispatching
`new CustomEvent(OUTPUT_EVENT, { detail: { _tag: 'Picked' }, bubbles: true })` on itself, so
children don't have to be Gyral components. [Using Gyral in other
frameworks](https://gyral.dev/docs/other-frameworks/#outputs-the-gyral-output-event) has recipes.

## Escape hatches

- **`el.send(msg)`** feeds a message into a component from imperative code (a canvas, an
  observer). Prefer intents and drivers where you can.
- **Any custom element.** Gyral components are plain custom elements, and any other custom
  element works alongside them, whether you wrote it by hand or with another library (see
  [Using third-party web components](https://gyral.dev/docs/third-party-components/)). Gyral adds a loop, not a
  walled garden.

---

# Intent

> How Gyral turns clicks, input, form submissions and keys into typed messages, and why the view never holds event handlers.

Source: https://gyral.dev/docs/intent/

**Intent** answers one question: what did the user mean? It turns platform events into
messages, and it is the only place where raw input is read. Everything after it, the model and
the view, works with typed, already-parsed data.

Building a form with validation? The [Forms](https://gyral.dev/docs/forms/#complete-example-a-validated-form)
page starts with a complete, copyable component: the submit intent, the messages, the reducers,
focus and the error markup in one file. [Form submissions](#form-submissions) below sums it up.

```ts
// src/search-box.ts
import { define, html } from '@gyral/core';

export interface State {
  readonly query: string;
  readonly submitted: string | undefined;
}

export type Msg =
  | { readonly _tag: 'Typed'; readonly query: string }
  | { readonly _tag: 'Search'; readonly query: string }
  | { readonly _tag: 'Clear' };

export const SearchBox = define<State, Msg>()('my-search-box', {
  init: () => ({ query: '', submitted: undefined }),
  intent: {
    Typed: ({ value }) => ({ _tag: 'Typed', query: value ?? '' }),
    Search: ({ formData }) => {
      const q = formData?.get('q');
      return typeof q === 'string' && q.trim() !== ''
        ? { _tag: 'Search', query: q.trim() }
        : undefined;
    },
    Clear: ({ key }) => (key === 'Escape' ? { _tag: 'Clear' } : undefined),
  },
  update: {
    Typed: (s, m) => ({ ...s, query: m.query }),
    Search: (s, m) => ({ ...s, submitted: m.query }),
    Clear: () => ({ query: '', submitted: undefined }),
  },
  view: (s, i) => html`
    <search data-intent=${i.Clear} data-intent-on="keydown">
      <form data-intent=${i.Search}>
        <label for="q">Search</label>
        <input id="q" name="q" type="search" value=${s.query} data-intent=${i.Typed} />
        <button>Search</button>
      </form>
    </search>
    <p>${s.submitted === undefined ? 'Nothing searched yet.' : `Results for “${s.submitted}”`}</p>
  `,
});
```

## Naming intents in markup

The view puts `data-intent=${i.Search}` on an element. `i` holds the intent names (the keys of
`intent`), typed, so a misspelt intent is a compile error. When that element's trigger event fires, Gyral calls the
parser registered under the same name in `intent`, and sends whatever it returns through
`update`.

A parser that only sends its tag can be written `true`: `intent: { Clear: true }` is
`Clear: () => ({ _tag: 'Clear' })`. It works when the message has no other fields, and is a type
error otherwise. A component with no intents leaves `intent` out, and one with no messages
leaves `update` out too.

The view never attaches a closure. That keeps it a pure function of state, which matters for
[server rendering](https://gyral.dev/docs/server-rendering/) (the markup the server sends already names every
intent) and for testing (there's nothing to call but `update`).

## Trigger events

Each element has a natural event, so you rarely say which one:

| Element                                  | Fires on                                |
| ---------------------------------------- | --------------------------------------- |
| `<form>`                                 | `submit` (Gyral prevents the page load) |
| `<input>` (text-like), `<textarea>`      | `input`                                 |
| checkbox and radio `<input>`, `<select>` | `change`                                |
| a custom element (a child component)     | its outputs                             |
| anything else (`<button>`, …)            | `click`                                 |

Override it with `data-intent-on`, such as `data-intent-on="keydown"`. Any event type works
there: `keyup`, `focusin`, `focusout`, `toggle` (popovers and `<details>`), `command` (invoker
commands, below), `pointerdown` or a third-party element's own event. A component listens only
for the events its templates name, so a component without keyboard intents never runs intent
lookup on a keystroke. If the value itself is bound, `data-intent-on=${…}`, the component listens
for `keydown`, `keyup`, `focusin`, `focusout`, `toggle` and `command` as well; for any other
event, write a per-event attribute such as `data-intent-pointerdown=${i.Press}` (below), which
the component always listens for.

`data-intent-on` also takes a list, separated by spaces: `data-intent-on="keydown keyup"` fires
the intent for both events. The parser tells them apart with `event.type`. Use a list when the
events mean the same thing to the model, such as the press and the release of a
[hold-to-record button](#press-and-hold).

## One element, an intent per event

When each event on an element means something different, name an intent per event type with
`data-intent-<event>`. A task in a sortable list grabs on `pointerdown`, drops on `pointerup`,
moves with the keyboard and tracks focus, all on the `<li>` itself:

```ts
// src/task-list.ts
import { define, each, html, intentsOf, type TemplateResult } from '@gyral/core';

export interface Task {
  readonly id: string;
  readonly title: string;
}

export interface State {
  readonly tasks: readonly Task[];
  readonly dragging: string | undefined;
  readonly focused: string | undefined;
}

export type Msg =
  | { readonly _tag: 'Grab'; readonly id: string }
  | { readonly _tag: 'Drop'; readonly id: string }
  | { readonly _tag: 'Move'; readonly id: string; readonly by: -1 | 1 }
  | { readonly _tag: 'Focus'; readonly id: string };

// The component's intent names, for rows. A row's return type is written out, or the row and
// `TaskList`'s type would infer each other.
const i = intentsOf<typeof TaskList>();

const TaskRow = (t: Task): TemplateResult =>
  html`<li
    tabindex="0"
    data-id=${t.id}
    data-intent-pointerdown=${i.Grab}
    data-intent-pointerup=${i.Drop}
    data-intent-keydown=${i.Move}
    data-intent-focusin=${i.Focus}
  >
    ${t.title}
  </li>`;

const idOf = (el: Element): string => el.getAttribute('data-id') ?? '';

/** Moves the task `id` to the place `to(from)` gives, clamped to the list. */
const moved = (tasks: readonly Task[], id: string, to: (from: number) => number) => {
  const from = tasks.findIndex((t) => t.id === id);
  const task = tasks[from];
  if (task === undefined) return tasks;
  const rest = tasks.filter((t) => t !== task);
  const at = Math.max(0, Math.min(rest.length, to(from)));
  return [...rest.slice(0, at), task, ...rest.slice(at)];
};

export const TaskList = define<State, Msg>()('my-task-list', {
  init: () => ({
    tasks: [
      { id: 'a', title: 'Write the brief' },
      { id: 'b', title: 'Review the designs' },
    ],
    dragging: undefined,
    focused: undefined,
  }),
  intent: {
    Grab: ({ target }) => ({ _tag: 'Grab', id: idOf(target) }),
    // Released over another task: the dragged one moves there.
    Drop: ({ target }) => ({ _tag: 'Drop', id: idOf(target) }),
    // Alt+ArrowUp and Alt+ArrowDown move the focused task; other keys keep their default.
    Move: ({ target, key, event }) => {
      const by = key === 'ArrowUp' ? -1 : key === 'ArrowDown' ? 1 : 0;
      if (by === 0 || !(event instanceof KeyboardEvent) || !event.altKey) return undefined;
      event.preventDefault();
      return { _tag: 'Move', id: idOf(target), by };
    },
    Focus: ({ target }) => ({ _tag: 'Focus', id: idOf(target) }),
  },
  update: {
    Grab: (s, m) => ({ ...s, dragging: m.id }),
    Drop: (s, m) => {
      const onto = s.tasks.findIndex((t) => t.id === m.id);
      return s.dragging === undefined
        ? s
        : { ...s, dragging: undefined, tasks: moved(s.tasks, s.dragging, () => onto) };
    },
    Move: (s, m) => ({ ...s, tasks: moved(s.tasks, m.id, (from) => from + m.by) }),
    Focus: (s, m) => ({ ...s, focused: m.id }),
  },
  view: (s) => html`
    <ul aria-label="Tasks">
      ${each(s.tasks, (t) => t.id, TaskRow)}
    </ul>
  `,
});
```

- **Per-event attributes come first.** For an event of type T, an element's `data-intent-T`
  answers before its plain `data-intent`, which keeps handling its own trigger. Lookup still
  starts at the element that was hit and goes outward, and the nearest element with an intent
  for that event wins.
- **Write the event name in lower case**, as event types are: `data-intent-pointerdown`. The HTML
  parser lower-cases attribute names, so an event whose name has capitals, such as a library's
  `valueChange`, can't be named this way: `data-intent-valueChange` becomes
  `data-intent-valuechange`. Put such a name in `data-intent-on` instead.
- **`data-intent-on` is reserved** for the trigger list. It is never read as an event called
  `on`.
- **The component listens for every event these names mention**, bound or static, in list rows
  and in `raw()` markup too. No `events` entry is needed.
- `data-intent-keydown=${s.editing ? i.Key : nothing}` gives the element that intent only while
  editing.

When the events share one message, keep one `data-intent` with a `data-intent-on` list instead.
And an intent can still sit on an ancestor, as `Clear` does in the first example: keys typed in
the input bubble to the `<search>` around it. `data-intent-keydown=${i.Clear}` on the input
itself would work as well.

## What a parser receives

A parser gets an `IntentInput` object, and the component's read-only context as a second
argument (see [props, state and stores in a parser](#props-state-and-stores-in-a-parser)):

| Field      | Holds                                                                          |
| ---------- | ------------------------------------------------------------------------------ |
| `value`    | The `value` of the input, select, textarea or button that has the intent       |
| `checked`  | `checked`, for checkboxes and radios                                           |
| `formData` | The submitted `FormData` (with the submitter button), for a `<form>`           |
| `key`      | `KeyboardEvent.key`, for `keydown` and `keyup`                                 |
| `newState` | `'open'` or `'closed'`, for `toggle`                                           |
| `detail`   | The `detail` of any `CustomEvent`: a child's output, a library element's event |
| `command`  | The invoker command and its source, for `command`                              |
| `name`     | The intent's name: the `data-intent-<event>` or `data-intent` value            |
| `event`    | The raw event                                                                  |
| `target`   | The element that carries the intent                                            |

Prefer the parsed fields to `event`: they read the same way for every element, and they're
what [tests](https://gyral.dev/docs/testing/) can construct.

### The intent element and the element that was hit

Read the element with the intent from `target`, not from the event. Gyral listens on the
component's root, so `event.currentTarget` is that root (the shadow root, or the host of a
light-DOM component), and `event.target` is whatever was hit inside the element: the `<span>`
in a button's label, an icon. `target` is always the element whose intent attribute answered.
Compare the two when it matters where an event started, as in
[declining](#declining-passing-an-event-outward).

`detail` is `unknown` until the parser checks it, with a type guard or a schema, because any
element can dispatch a `CustomEvent`. [Using third-party web
components](https://gyral.dev/docs/third-party-components/#what-the-parser-gets) shows a map's custom event
parsed this way.

## Parse, don't validate

A parser returns one of three things:

- **A message** of its own tag's variant.
- **`undefined`** to decline the event. Above, `Clear` declines every key but Escape, and
  `Search` declines an empty query. Declining is not an error, and an intent further out may
  still take the event ([below](#declining-passing-an-event-outward)).
- **`IntentRejected`**, a framework message with field issues, when input fails a schema. The
  [Forms](https://gyral.dev/docs/forms/) helpers `form()` and `field()` produce it for you.

Parsers may return a promise, because schema validation can be async. They must not do side
effects. The one exception is `event.preventDefault()`, for example to stop arrow keys moving
the caret.

## Form submissions

A `<form>` with `data-intent` runs its parser on `submit`, and Gyral prevents the page load. The
parser gets the form as `target` and the submitted values as `formData`. To validate, read each
field's `validity` from `target.elements` and return one message with every error, or one with
the clean values:

- **Name the submit intent something that isn't a message tag**, such as `Submit`, so it can
  return either message (`Rejected` or `SignedUp`). See
  [Intent names that aren't messages](#intent-names-that-arent-messages).
- **Put `novalidate` on the form** and keep `required`, `type="email"` and `minlength` on the
  fields. Without it, a failing constraint stops the `submit` event and the parser never runs.
- **Keep errors in state** and render them next to their fields with `aria-invalid` and
  `aria-describedby`. Focus the first invalid field with a `focus()` command from the reducer:
  the parser may not move focus, because that is a side effect.
- **With a schema**, `form(definition, toMsg)` parses the `FormData` for you and returns
  `IntentRejected` with field issues; `fieldErrors(issues)` groups them by field.

The whole component, ready to copy, is
[Forms: Complete example](https://gyral.dev/docs/forms/#complete-example-a-validated-form). The schema path is
[Forms: form() and invalid()](https://gyral.dev/docs/forms/#form-and-invalid).

## Declining: passing an event outward

Lookup starts at the element that was hit and goes outward, and the nearest element with an
intent for the event runs its parser. When that parser returns `undefined` synchronously, it
declines: the next element outward with an intent for the same event gets it, up to the
component's root. So a container's keyboard shortcuts and its fields' own keys live together:

```ts
// src/note-editor.ts
import { define, html } from '@gyral/core';

export interface State {
  readonly body: string;
  readonly draft: string;
  readonly tags: readonly string[];
  readonly saving: boolean;
}

export type Msg =
  | { readonly _tag: 'Body'; readonly text: string }
  | { readonly _tag: 'Draft'; readonly text: string }
  | { readonly _tag: 'AddTag'; readonly tag: string }
  | { readonly _tag: 'Save' };

/** Ctrl+S, or Command+S on a Mac. */
const isSave = (event: Event, key: string | undefined): boolean =>
  key === 's' && event instanceof KeyboardEvent && (event.ctrlKey || event.metaKey);

export const NoteEditor = define<State, Msg>()('my-note-editor', {
  init: () => ({ body: '', draft: '', tags: [], saving: false }),
  intent: {
    Body: ({ value }) => ({ _tag: 'Body', text: value ?? '' }),
    Draft: ({ value }) => ({ _tag: 'Draft', text: value ?? '' }),
    // The tag field keeps Enter. Every other key declines, so Ctrl+S goes on to Save.
    AddTag: ({ key, value }) => {
      const tag = value?.trim() ?? '';
      return key === 'Enter' && tag !== '' ? { _tag: 'AddTag', tag } : undefined;
    },
    // The editor's shortcut, wherever focus is inside it.
    Save: ({ key, event }) => {
      if (!isSave(event, key)) return undefined;
      event.preventDefault(); // not the browser's "Save page as"
      return { _tag: 'Save' };
    },
  },
  update: {
    Body: (s, m) => ({ ...s, body: m.text }),
    Draft: (s, m) => ({ ...s, draft: m.text }),
    AddTag: (s, m) => ({ ...s, draft: '', tags: [...s.tags, m.tag] }),
    // In an app, this also returns the command that sends the note.
    Save: (s) => ({ ...s, saving: true }),
  },
  view: (s, i) => html`
    <section aria-label="Note" data-intent-keydown=${i.Save}>
      <label for="body">Note</label>
      <textarea id="body" data-intent=${i.Body}>${s.body}</textarea>
      <label for="tag">Add a tag</label>
      <input id="tag" value=${s.draft} data-intent=${i.Draft} data-intent-keydown=${i.AddTag} />
      <p>Tags: ${s.tags.join(', ')}</p>
      <p role="status">${s.saving ? 'Saving…' : ''}</p>
    </section>
  `,
});
```

A keystroke in the textarea has no `keydown` intent of its own, so it goes straight to `Save`.
In the tag field, `AddTag` answers first: it takes Enter and declines everything else, and the
section's `Save` sees Ctrl+S from there too.

- **Only a synchronous `undefined` declines.** A parser that returns a promise has taken the
  event, whatever the promise resolves to: lookup can't wait for it.
- **Declining stays inside the component.** A nested component's lookup ends at its own root.
  The outer component sees the same event through its own listener, once.
- **To skip events by where they started** rather than by key, compare `event.target` (the
  element that was hit) with `target` (the element with the intent).

## Props, state and stores in a parser

A parser's second argument is a read-only context: `props` and the component's `state`, as they
are when the event fires, and `read(store)` for the stores in the spec's `stores`. Parsers that don't need it
take one parameter. Use it when the decision must be made during the event, such as whether to
call `preventDefault()`: by the time a reducer runs, the browser has already acted.

A listbox owns the arrow keys of its orientation and leaves the others to the page:

```ts
// src/folders.ts
import { define, html, prop } from '@gyral/core';

export interface Props {
  /** `vertical` lists take ArrowUp and ArrowDown; `horizontal` ones ArrowLeft and ArrowRight. */
  readonly orientation: string;
}

export type Msg = { readonly _tag: 'Step'; readonly by: -1 | 1 };

const FOLDERS = ['Inbox', 'Drafts', 'Sent'] as const;

const KEYS: Readonly<Record<string, readonly [string, string]>> = {
  vertical: ['ArrowUp', 'ArrowDown'],
  horizontal: ['ArrowLeft', 'ArrowRight'],
};

export const Folders = define<{ readonly active: number }, Msg, Props>()('my-folders', {
  props: { orientation: prop.string({ default: 'vertical' }) },
  init: () => ({ active: 0 }),
  intent: {
    // Only the arrow keys this orientation owns are taken; the others still scroll the page.
    Step: ({ key, event }, { props }) => {
      const [back, next] = KEYS[props.orientation] ?? KEYS.vertical ?? ['', ''];
      const by = key === back ? -1 : key === next ? 1 : 0;
      if (by === 0) return undefined;
      event.preventDefault();
      return { _tag: 'Step', by };
    },
  },
  update: {
    Step: (s, m) => ({ active: (s.active + m.by + FOLDERS.length) % FOLDERS.length }),
  },
  view: (s, i, { props }) => html`
    <ul
      role="listbox"
      tabindex="0"
      aria-label="Folders"
      aria-orientation=${props.orientation}
      aria-activedescendant=${`folder-${String(s.active)}`}
      data-intent-keydown=${i.Step}
    >
      ${FOLDERS.map(
        (name, n) =>
          html`<li id=${`folder-${String(n)}`} role="option" aria-selected=${n === s.active}>
            ${name}
          </li>`,
      )}
    </ul>
  `,
});
```

Where the user is often decides the default, and that's state. A seat grid keeps Tab while
there is a next seat, and lets it move focus on from the last one:

```ts
// src/seats.ts
import { define, html } from '@gyral/core';

interface Grid {
  readonly cell: number;
  readonly cells: number;
}
type Msg = { readonly _tag: 'NextCell' };

export const Seats = define<Grid, Msg>()('my-seat-grid', {
  init: () => ({ cell: 0, cells: 12 }),
  intent: {
    NextCell: ({ key, event }, { state }) => {
      if (key !== 'Tab' || state.cell === state.cells - 1) return undefined;
      event.preventDefault();
      return { _tag: 'NextCell' };
    },
  },
  update: { NextCell: (s) => ({ ...s, cell: s.cell + 1 }) },
  view: (s, i) => html`
    <div role="grid" tabindex="0" aria-label="Seats" data-intent-keydown=${i.NextCell}>
      Seat ${s.cell + 1} of ${s.cells}
    </div>
  `,
});
```

`state` includes messages sent earlier in the same task, before the next render. Read it,
don't write it: apart from `preventDefault()`, a parser stays pure, and the view doesn't need
to write `data-first`/`data-last` attributes just so a parser can read them.

Keep parsers pure apart from `preventDefault()`: they read the context, they never write.
`form()`, `field()` and `child()` return one-parameter parsers, so code that calls one directly,
`field(schema, toMsg)(input)`, still works.

## Typing parsers

Each key in `intent` produces its own variant: the `Search` parser above returns a
`{ _tag: 'Search'; … }`. Inside the spec, leave the return type off, and the key types it.

Don't annotate a parser with the whole union. `(): Msg => …` widens it, and TypeScript answers
with a long error that ends in "`IntentParser<Msg, …>` is not assignable to …". A parser written
outside the spec returns its variant:

```ts
// src/search-parser.ts
import type { IntentInput } from '@gyral/core';
import type { Msg } from './search-box.js';

/** The variant, not the union; `undefined` declines the event. */
export const parseSearch = ({
  formData,
}: IntentInput): Extract<Msg, { _tag: 'Search' }> | undefined => {
  const q = formData?.get('q');
  return typeof q === 'string' && q.trim() !== '' ? { _tag: 'Search', query: q.trim() } : undefined;
};
```

`_tag: 'Search' as const` in the returned object works too. The same holds for the mappers of
`child()`, `form()` and `field()`. To type a parser that reads the context, use
`IntentParser<Variant, Props>`, or `IntentParser<Variant, Props, State>` when it reads `state`.
`Variant<Msg, 'Search'>` from `@gyral/core` names the variant without `Extract`,
and `ParseResult<M>` is what a parser may return: a message, `IntentRejected` or `undefined`.
`StandardSchemaV1` is exported too, for helpers that take a schema the way `field()` and
`defineForm()` do.

## Buttons carry their own data

A button's `value` is part of `IntentInput`, so a list of buttons needs one intent, not one
closure per row:

```html
<button type="button" value="sku-42" data-intent="AddToCart">Add to cart</button>
```

The parser reads `value` and the reducer finds the product. This is also what keeps the markup
meaningful without JavaScript.

## Several controls, one intent

Controls that all change one thing don't need a message each. Give them the same intent and
tell them apart by their `name`, as in a search filters panel:

```ts
// src/search-filters.ts
import { define, html } from '@gyral/core';

export interface Filters {
  readonly category: string;
  readonly sort: string;
}

export type Msg = {
  readonly _tag: 'Filter';
  readonly field: keyof Filters;
  readonly value: string;
};

const FIELDS: readonly (keyof Filters)[] = ['category', 'sort'];
const isField = (name: string): name is keyof Filters => FIELDS.some((f) => f === name);

export const SearchFilters = define<Filters, Msg>()('my-search-filters', {
  init: () => ({ category: 'all', sort: 'relevance' }),
  intent: {
    // One parser for every <select>: the name says which filter changed.
    Filter: ({ target, value }) => {
      const name = target.getAttribute('name') ?? '';
      return isField(name) && value !== undefined
        ? { _tag: 'Filter', field: name, value }
        : undefined;
    },
  },
  update: {
    Filter: (s, m) => ({ ...s, [m.field]: m.value }),
  },
  view: (s, i) => html`
    <label>
      Category
      <select name="category" data-intent=${i.Filter}>
        <option value="all" ?selected=${s.category === 'all'}>All</option>
        <option value="books" ?selected=${s.category === 'books'}>Books</option>
      </select>
    </label>
    <label>
      Sort by
      <select name="sort" data-intent=${i.Filter}>
        <option value="relevance" ?selected=${s.sort === 'relevance'}>Relevance</option>
        <option value="price" ?selected=${s.sort === 'price'}>Price</option>
      </select>
    </label>
  `,
});
```

Give each control its own message only when the reducers really differ. A view that names an
intent with no parser fails to compile: `Property 'Category' does not exist on type
'IntentNames<"Filter">'`.

## Intent names that aren't messages

Sometimes each control does something different, but all of them end in the same message. A
table toolbar's Archive, Restore and Duplicate buttons all become one request to the server.
Give each control its own parser key: the keys of `intent` are the component's intent names,
and a key that isn't a message tag may return any message.

```ts
// src/doc-table.ts
import { define, each, html, intentsOf, type TemplateResult } from '@gyral/core';

export interface Doc {
  readonly id: number;
  readonly title: string;
  readonly archived: boolean;
}

export type Action =
  { readonly kind: 'archive' | 'restore'; readonly id: number } | { readonly kind: 'duplicate' };

export type Msg = { readonly _tag: 'Request'; readonly action: Action };

export interface State {
  readonly docs: readonly Doc[];
  readonly pending: readonly Action[];
}

const i = intentsOf<typeof DocTable>(); // the parser keys, for rows

const idOf = (target: Element): number =>
  Number(target.closest('[data-id]')?.getAttribute('data-id'));

const request = (action: Action): Msg => ({ _tag: 'Request', action });

const Row = (doc: Doc): TemplateResult =>
  html`<li data-id=${doc.id}>
    ${doc.title}
    <button type="button" data-intent=${doc.archived ? i.Restore : i.Archive}>
      ${doc.archived ? 'Restore' : 'Archive'}
    </button>
  </li>`;

export const DocTable = define<State, Msg>()('my-doc-table', {
  init: () => ({ docs: [], pending: [] }),
  intent: {
    Archive: ({ target }) => request({ kind: 'archive', id: idOf(target) }),
    Restore: ({ target }) => request({ kind: 'restore', id: idOf(target) }),
    Duplicate: () => request({ kind: 'duplicate' }),
  },
  // One reducer for all three. In an app, it also returns the command that sends the request.
  update: { Request: (s, m) => ({ ...s, pending: [...s.pending, m.action] }) },
  // The view uses its own `i`; the module constant is for rows.
  view: (s, i) => html`
    <ul>
      ${each(s.docs, (doc) => doc.id, Row)}
    </ul>
    <button type="button" data-intent=${i.Duplicate}>Duplicate</button>
  `,
});
```

- **The intent names are the keys of `intent`.** `define<State, Msg>()(…)` takes them from the
  object you write, so there is nothing to declare twice.
- **A key that is a message tag returns that message**, as before. Any other key may return any
  message and gets no reducer: `update` has keys only for messages.
- **`i` holds exactly the keys.** Markup that names an intent with no parser fails to compile.
  For rows, `intentsOf<typeof Component>()` gives the same names as a module constant; write the
  row's return type (`: TemplateResult`), and use the view's own `i` inside the component.
- **A misspelled key is a new intent name.** The view's correct name then fails with
  `Property 'Archive' does not exist on type 'IntentNames<"Archvie" | …>'. Did you mean
'Archvie'?`, so fix the key; a key no template names at all is reported by the
  `gyral/unused-intent` lint rule.

It is a type-level feature: the keys were always the names at runtime. Prefer one shared intent
([previous section](#several-controls-one-intent)) when one parser that reads `name` is
clearer; give each control its own key when the parsers differ.

## Press and hold

A hold-to-record button, like a voice message in a chat, needs the press and the release. List
both in `data-intent-on` and read `event.type`: one intent, one message with a `down` flag.

The release must arrive even when the pointer leaves the button before it lets go. That is
**pointer capture**: an [element hook](https://gyral.dev/docs/views/#element-hooks) of a few lines calls
`setPointerCapture` on `pointerdown`, so the pointer's events stay with the element until release.

```ts
// src/capture-pointer.ts
import { defineHook } from '@gyral/core';

function capture(this: Element, event: Event): void {
  try {
    this.setPointerCapture((event as PointerEvent).pointerId);
  } catch {
    // Not an active pointer (a synthetic event): nothing to capture.
  }
}

/** Keeps a pointer's events on this element from `pointerdown` until release. */
export const capturePointer = defineHook<[]>({
  client: (el) => {
    el.addEventListener('pointerdown', capture);
  },
  dispose: (el) => {
    el.removeEventListener('pointerdown', capture);
  },
});
```

```ts
// src/record-button.ts
import { define, html } from '@gyral/core';
import { capturePointer } from './capture-pointer.js';

export interface State {
  readonly recording: boolean;
}

export type Msg = { readonly _tag: 'Record'; readonly down: boolean };

const PRESS = new Set(['pointerdown', 'keydown']);

export const RecordButton = define<State, Msg>()('my-record-button', {
  init: () => ({ recording: false }),
  intent: {
    Record: ({ event, key }) => {
      if (event instanceof KeyboardEvent) {
        if (key !== ' ' || event.repeat) return undefined;
        event.preventDefault(); // no page scroll, and no click when Space comes up
      }
      return { _tag: 'Record', down: PRESS.has(event.type) };
    },
  },
  update: {
    // In an app, these also start and stop the microphone with commands.
    Record: (_s, m) => ({ recording: m.down }),
  },
  view: (s, i) => html`
    <button
      type="button"
      aria-pressed=${s.recording}
      ${capturePointer()}
      data-intent=${i.Record}
      data-intent-on="pointerdown pointerup pointercancel keydown keyup"
    >
      ${s.recording ? 'Recording…' : 'Hold to record'}
    </button>
  `,
});
```

`pointercancel`, when the browser takes the touch over for scrolling, is a release too. For the keyboard, the same button holds while Space is down, and the parser ignores
auto-repeat.

- Give the button `touch-action: none` in CSS, so a held finger doesn't scroll or zoom, and
  `user-select: none`, so a long press doesn't select the label.
- A button that may disappear mid-press, in a render that drops it, never gets its `pointerup`.
  Also list `lostpointercapture` and treat it as a release, ignoring ones from other elements
  (`event.target !== target`): the event bubbles.
- While an element holds capture, the browser sends that pointer's events to it. Intents on the
  capturing element keep firing, but intents on elements _inside_ it stop until release. Put
  `capturePointer()` on the element whose intent needs the release, not on a container of other
  controls.
- Keys reach the button only while it has focus. For a shortcut anywhere on the page, read keys
  in a driver: a [subscription](https://gyral.dev/docs/outside-state/) to `keydown` and `keyup` on `window`.

## The element under a captured pointer

While an element holds pointer capture, every move lands on it, not on what the pointer is
over. To trace a path across items (drawing across a grid of cells, selecting a range of days
by dragging), capture on the container and ask the component's root which element is under the
pointer: `elementFromPoint` on the shadow root (or `document` for a light-DOM component) sees
inside the shadow tree. The cell carries its index in `data-cell`:

```ts
// src/path-grid.ts
import { define, html } from '@gyral/core';
import { capturePointer } from './capture-pointer.js';

interface State {
  readonly path: readonly number[];
}
type Msg = { readonly _tag: 'Trace'; readonly cell: number; readonly start: boolean };

const CELLS = Array.from({ length: 16 }, (_, n) => n);

export const PathGrid = define<State, Msg>()('my-path-grid', {
  init: () => ({ path: [] }),
  intent: {
    Trace: ({ event, target }) => {
      if (!(event instanceof PointerEvent)) return undefined;
      if (event.type === 'pointermove' && event.buttons === 0) return undefined;
      const root = target.getRootNode() as Document | ShadowRoot;
      const under = root.elementFromPoint(event.clientX, event.clientY);
      const cell = under?.closest('[data-cell]')?.getAttribute('data-cell');
      if (cell == null) return undefined;
      return { _tag: 'Trace', cell: Number(cell), start: event.type === 'pointerdown' };
    },
  },
  update: {
    Trace: (s, m) =>
      m.start ? { path: [m.cell] } : s.path.at(-1) === m.cell ? s : { path: [...s.path, m.cell] },
  },
  view: (s, i) => html`
    <div
      class="grid"
      ${capturePointer()}
      data-intent=${i.Trace}
      data-intent-on="pointerdown pointermove"
    >
      ${CELLS.map(
        (n) => html`<span data-cell=${n} class=${s.path.includes(n) ? 'on' : ''}>${n}</span>`,
      )}
    </div>
  `,
});
```

Give the container `touch-action: none` so a finger traces instead of scrolling.

## Invoker commands

An element with `data-intent-on="command"` receives
[invoker commands](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API)
aimed at it, from buttons anywhere in the component:

```ts
// src/shopping-list.ts
import { define, each, html } from '@gyral/core';

export interface State {
  readonly items: readonly string[];
}

export type Msg = { readonly _tag: 'Command'; readonly command: '--add' | '--clear' };

const Item = (item: string) => html`<li>${item}</li>`;

export const ShoppingList = define<State, Msg>()('my-shopping-list', {
  init: () => ({ items: [] }),
  intent: {
    Command: ({ command }) =>
      command?.command === '--add' || command?.command === '--clear'
        ? { _tag: 'Command', command: command.command }
        : undefined,
  },
  update: {
    Command: (s, m) =>
      m.command === '--add'
        ? { items: [...s.items, `Item ${String(s.items.length + 1)}`] }
        : { items: [] },
  },
  view: (s, i) => html`
    <button type="button" commandfor="list" command="--add">Add item</button>
    <button type="button" commandfor="list" command="--clear">Clear</button>
    <ul id="list" data-intent=${i.Command} data-intent-on="command">
      ${each(s.items, (item) => item, Item)}
    </ul>
  `,
});
```

Invoker commands are newly available in browsers. Where the native `CommandEvent` is missing,
Gyral dispatches an equivalent event for custom (`--…`) commands, so the same markup works
everywhere. Built-in commands such as `show-modal` are left to the browser.

## Isolation

Only `data-intent` elements in the component's own render root count. A click inside a child
component belongs to the child, never to the parent, because the child's shadow root is a
boundary. Light-DOM components keep the same rule by stopping at the next Gyral host. A parser
that declines passes the event outward only within its own component.

---

# Model and update

> State as plain data, one pure reducer per message, commands returned as data, and the framework messages Gyral sends you.

Source: https://gyral.dev/docs/update/

The **model** is your component's state. **Update** is how it changes: a record of reducers,
one per message tag, each a pure function from the current state and a message to the next
state. Nothing else changes state, so every change is visible to tests and to
[devtools](https://gyral.dev/docs/devtools/).

```ts
// src/todo.ts
import { define, each, html, intentsOf, type TemplateResult } from '@gyral/core';

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

export interface State {
  readonly todos: readonly Todo[];
  readonly nextId: number;
}

export type Msg =
  | { readonly _tag: 'Add'; readonly text: string }
  | { readonly _tag: 'Toggle'; readonly id: number }
  | { readonly _tag: 'ClearDone' };

const i = intentsOf<typeof TodoList>();

const Item = (t: Todo): TemplateResult =>
  html`<li>
    <button type="button" value=${t.id} aria-pressed=${t.done} data-intent=${i.Toggle}>
      ${t.text}
    </button>
  </li>`;

export const TodoList = define<State, Msg>()('my-todo-list', {
  init: () => ({ todos: [], nextId: 1 }),
  intent: {
    Add: ({ formData }) => {
      const text = formData?.get('text');
      return typeof text === 'string' && text.trim() !== ''
        ? { _tag: 'Add', text: text.trim() }
        : undefined;
    },
    Toggle: ({ value }) => ({ _tag: 'Toggle', id: Number(value) }),
    ClearDone: () => ({ _tag: 'ClearDone' }),
  },
  update: {
    Add: (s, m) => ({
      todos: [...s.todos, { id: s.nextId, text: m.text, done: false }],
      nextId: s.nextId + 1,
    }),
    Toggle: (s, m) => ({
      ...s,
      todos: s.todos.map((t) => (t.id === m.id ? { ...t, done: !t.done } : t)),
    }),
    ClearDone: (s) => ({ ...s, todos: s.todos.filter((t) => !t.done) }),
  },
  view: (s, i) => html`
    <form data-intent=${i.Add}>
      <label for="text">New todo</label>
      <input id="text" name="text" required />
      <button>Add</button>
    </form>
    <ul>
      ${each(s.todos, (t) => t.id, Item)}
    </ul>
    <button type="button" data-intent=${i.ClearDone}>Clear done</button>
  `,
});
```

## State is plain data

Keep state a record of JSON values: strings, numbers, booleans, `null`, arrays and plain
objects. No `Date`, `Map` or class instances. Three things depend on it:

- **Server rendering** writes each component's state into the page as JSON, and the browser
  resumes from it. A `Date` would come back as a string. In development, the server warns when
  a seed won't survive the trip.
- **Devtools** and tests can print and compare state.
- **Reducers return new objects.** State is never mutated, so "did it change?" is a reference
  check.

Model what can happen with unions rather than flags. `{ _tag: 'Loading' } | { _tag: 'Found';
repos } | { _tag: 'Failed'; message }` can't be loading and failed at once; two booleans can.

The module's `i` is `intentsOf<typeof TodoList>()`: the same typed intent names the view
receives, as a module constant, so the list's `Item` row can name an intent and stay a pure
function of its todo ([Lists](https://gyral.dev/docs/views/#lists)). The row's return type is written out, and
the view uses its own `i`, so the row and the component don't infer each other's types. `aria-pressed=${t.done}` writes `"true"` or `"false"`, the way
ARIA expects.

## One reducer per message

`update` is keyed by message tag, and its type requires a reducer for every tag in `Msg`. Add
a message and the compiler shows you every component that has to handle it.

A reducer receives the state, the message (narrowed to its variant, so `m.id` is typed) and the
context, `{ props, read }`: the component's [props](https://gyral.dev/docs/components/#props) and a reader for
[shared stores](https://gyral.dev/docs/stores/). Reducers are pure: no `fetch`, no `Date.now()`, no
`Math.random()`, no DOM.

A reducer written outside the spec, to share it or test it alone, is typed with `Reducer` and
`Variant` from `@gyral/core` (type-only exports). `Variant<Msg, 'Add'>` is the
member of `Msg` tagged `'Add'`:

```ts
// src/shelf.ts
import { define, html, type Reducer, type Variant } from '@gyral/core';

interface State {
  readonly books: readonly string[];
}
type Msg = { readonly _tag: 'Add'; readonly title: string } | { readonly _tag: 'Clear' };

export const add: Reducer<State, Msg, Variant<Msg, 'Add'>> = (s, m) => ({
  books: [...s.books, m.title],
});

export const Shelf = define<State, Msg>()('my-shelf', {
  init: () => ({ books: [] }),
  intent: { Add: ({ value }) => ({ _tag: 'Add', title: value ?? '' }), Clear: true },
  update: { Add: add, Clear: () => ({ books: [] }) },
  view: (s, i) => html`
    <button type="button" value="Middlemarch" data-intent=${i.Add}>Add Middlemarch</button>
    <button type="button" data-intent=${i.Clear}>Clear</button>
    <output>${s.books.join(', ')}</output>
  `,
});
```

## Returning commands

To do anything outside the model, a reducer returns a tuple: the next state and a list of
**commands**. A command is a description of a side effect, run by a driver. The answer comes
back as another message.

```ts
// src/save-button.ts
import { define, html } from '@gyral/core';
import { delay } from '@gyral/time';

export interface State {
  readonly saving: boolean;
}

export type Msg = { readonly _tag: 'Save' } | { readonly _tag: 'Saved' };

export const SaveButton = define<State, Msg>()('my-save-button', {
  init: () => ({ saving: false }),
  intent: { Save: true },
  update: {
    // State plus a command: answer `Saved` after half a second.
    Save: (s) => (s.saving ? s : [{ saving: true }, [delay<Msg>(500, { _tag: 'Saved' })]]),
    Saved: () => ({ saving: false }),
  },
  view: (s, i) => html`
    <button type="button" data-intent=${i.Save} ?disabled=${s.saving}>
      ${s.saving ? 'Saving…' : 'Save'}
    </button>
  `,
});
```

The return type is `Next<State, Msg>`: either a state, or `[state, commands]`. State is never an
array, so the two can't be confused. `init` can return commands too, to load data when the
component appears. `Save: true` is the short form of a parser that only sends its tag; it works
for messages with no other fields. [Effects and drivers](https://gyral.dev/docs/effects/) covers commands in depth.

## Subscriptions

Work that should keep running while some condition holds (a clock, polling, a socket, a store or
media-query watch) doesn't start in a reducer. `subscriptions(state, props)` returns the
commands that should be running now, and Gyral keeps the running set in step with it:

```ts
// src/clock.ts
import { define, html } from '@gyral/core';
import { every } from '@gyral/time';

export interface State {
  readonly running: boolean;
  readonly now: number;
}

export type Msg = { readonly _tag: 'Toggle' } | { readonly _tag: 'Tick'; readonly now: number };

export const Clock = define<State, Msg>()('my-clock', {
  init: () => ({ running: false, now: 0 }),
  // While running, tick every second; pausing stops the timer, resuming starts it again.
  subscriptions: (s) => (s.running ? [every(1000, (now): Msg => ({ _tag: 'Tick', now }))] : []),
  intent: { Toggle: true },
  update: {
    Toggle: (s) => ({ ...s, running: !s.running }),
    Tick: (s, m) => ({ ...s, now: m.now }),
  },
  view: (s, i) => html`
    <button type="button" data-intent=${i.Toggle}>${s.running ? 'Pause' : 'Start'}</button>
    <p><time>${s.now === 0 ? '—' : new Date(s.now).toLocaleTimeString()}</time></p>
  `,
});
```

After the first render and after every update and props change, Gyral compares the list with
what is running, lane by lane (a command's `key`, else its driver's name): a new lane starts, a
missing lane is stopped, a lane whose input changed restarts, and an unchanged lane keeps
running. Inputs are compared as data: functions inside them are ignored, so an inline selector
such as `(s) => s.unread` doesn't restart a lane on every update. To restart when a selector
changes, put what it depends on in the key, for example one that includes the room id.
Moving the element keeps subscriptions running, removing it stops them, and attaching it again
starts them from the current state. So there is no start in `init`, no restart on
`PropsChanged` and no reconnect handling. `every(ms, (now) => msg)` sends the time at once and
then every `ms`. In model tests, `subscriptionsFor(Clock.spec, state, props)` returns the list.

## Framework messages

Gyral sends five messages of its own, plus three to
[form-associated components](https://gyral.dev/docs/form-associated/) (`FormReset`, `FormDisabled` and
`FormStateRestore`). Their reducers are optional: leave one out and the message changes nothing.

| Message          | Sent when                                                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `PropsChanged`   | A declared prop changed after the first render. Has `props` and `prev`. [Props](https://gyral.dev/docs/components/#reacting-to-prop-changes)              |
| `IntentRejected` | Input failed a schema in `form()` or `field()`, or the server rejected a form. [Forms](https://gyral.dev/docs/forms/)                                     |
| `StoreChanged`   | A store the component reads changed. [Shared state](https://gyral.dev/docs/stores/)                                                                       |
| `Hydrated`       | The component is live in the browser, once, after its first render. Has `serverRendered`.                                                |
| `Errored`        | An update, parser or command of this component failed. Has `phase` and `error` (a `GyralError`). [Error handling](https://gyral.dev/docs/error-handling/) |

`Hydrated` is the hook for progressive enhancement: render the no-JavaScript version on the
server and in the first client render (so hydration matches), then switch to the enhanced UI
in the `Hydrated` reducer.

## Starting from messages

Every Gyral element has an `initialMessages` property. Messages listed there run through
`update` right after `init`, before the first render, on the server too. The server uses it to
render a form with the errors from a rejected submission through the component's own
`IntentRejected` reducer, so errors look the same with or without JavaScript.

## State in CSS and in transitions

Two optional spec fields read the model, so the model stays the one source of truth:

- **`states: (s) => ({ loading: s.results._tag === 'Loading' })`** mirrors boolean facts onto the
  element's [custom states](https://gyral.dev/docs/styling/#custom-states), for CSS:
  `:host(:state(loading))`.
- **`viewTransition: (prev, next, msg) => boolean`** renders a state change inside
  `document.startViewTransition`, for route changes and list reorders. It is skipped where the
  browser doesn't support it, or when the user prefers reduced motion.

---

# Views

> Views are pure functions from state to html templates. Name intents, render keyed lists, bind form state, and let the compiler check markup.

Source: https://gyral.dev/docs/views/

A **view** is a function from state to HTML. It receives the state, the typed intent names
`i`, and the context `{ props, read }`, and returns an `html` template. It has no other inputs
and no side effects, so the same state always renders the same markup, on the server and in the
browser.

```ts
// src/profile.ts
import { define, html } from '@gyral/core';

export interface State {
  readonly editing: boolean;
  readonly name: string;
}

export type Msg = { readonly _tag: 'Edit' } | { readonly _tag: 'Save'; readonly name: string };

export const Profile = define<State, Msg>()('my-profile', {
  init: () => ({ editing: false, name: 'Ada' }),
  intent: {
    Edit: () => ({ _tag: 'Edit' }),
    Save: ({ formData }) => {
      const name = formData?.get('name');
      return typeof name === 'string' ? { _tag: 'Save', name } : undefined;
    },
  },
  update: {
    Edit: (s) => ({ ...s, editing: true }),
    Save: (_s, m) => ({ editing: false, name: m.name }),
  },
  view: (s, i) => html`
    <h2>${s.name}</h2>
    ${
      s.editing &&
      html`<form data-intent=${i.Save}>
        <label for="name">Name</label>
        <input id="name" name="name" autocomplete="name" value=${s.name} required />
        <button>Save</button>
      </form>`
    }
    <button type="button" data-intent=${i.Edit} ?hidden=${s.editing}>Edit name</button>
  `,
});
```

## Templates

Everything a view needs comes from `@gyral/core`: `html`, `svg`, `css`, `nothing`, `each`,
`keyed`, `raw` and `defineHook`. Gyral renders with its own small view layer, built for this one job: no virtual
DOM, no runtime dependencies. A template is prepared once per call site. After that a render
only compares each `${…}` with the value it wrote last time and touches the DOM where they
differ.

| Binding                     | Sets                                                                     |
| --------------------------- | ------------------------------------------------------------------------ |
| `${value}`                  | Text content (escaped), a nested template, a list, or nothing            |
| `attr=${value}`             | An attribute; `null`, `undefined` and `nothing` remove it                |
| `class="card ${s.kind}"`    | An attribute built from several pieces (quote it)                        |
| `?attr=${bool}`             | A boolean attribute, present or absent                                   |
| `.prop=${value}`            | A property: data for a child Gyral component, such as objects and arrays |
| `<input ${hook(…)}>`        | An [element hook](#element-hooks) on that element                        |
| `<textarea>${v}</textarea>` | The textarea's value (see [Form state](#form-state))                     |

Boolean attributes (`selected`, `checked`, `disabled`, `open`, `required`, `hidden`'s siblings
and the rest of HTML's list) take `?attr=${bool}`. Writing `selected=${bool}` would render
`selected="false"`, which the browser reads as selected, so it's a template error with the fix
in the message.

In a text position, `false`, `null`, `undefined` and `nothing` render nothing, so
``${s.open && html`…`}`` works. Classes and inline styles are plain strings:
`class=${s.done ? 'done' : ''}`, `style="--w: ${s.width}px"` (under a strict Content Security
Policy, see [inline styles](https://gyral.dev/docs/styling/#inline-styles-under-a-strict-csp)). Inline `<svg>`
works inside `html`, so icons and charts need nothing special; an SVG fragment that is a
template of its own uses [`svg`](#svg-fragments). Property bindings carry data, never
functions: events are [intents](#no-event-handlers), and behaviour on an element is a
[hook](#element-hooks).

Whitespace is normalized once per template, the same way on the server and in the browser:
indentation between block-level tags disappears, and a run of whitespace between inline
elements becomes one space. `<pre>` and `<textarea>` keep theirs. Exact whitespace belongs in
`<pre>` or in a value.

## SVG fragments

Write a whole graphic, `<svg>` included, in `html`. When part of it is a template of its own, a
mark shown only in some states or one shape per list item, write that part with `svg`:

```ts
// src/status-strip.ts
import { define, each, html, nothing, svg } from '@gyral/core';

export interface Service {
  readonly id: number;
  readonly status: 'up' | 'down' | undefined;
  readonly name: string;
}

// Fragments are plain functions that return svg templates.
const mark = (status: 'up' | 'down') =>
  status === 'up'
    ? svg`<circle cx="5" cy="5" r="3" />`
    : svg`<rect x="2" y="2" width="6" height="6" />`;

// A list row: it reads only its service, so it stays pure.
const tile = (service: Service) => svg`<g transform="translate(${(service.id - 1) * 12} 0)">
  ${service.status === undefined ? nothing : mark(service.status)}
  <text x="1" y="13">${service.name}</text>
</g>`;

export const StatusStrip = define<{ readonly services: readonly Service[] }, never>()(
  'my-status-strip',
  {
    init: () => ({ services: [{ id: 1, status: 'up', name: 'API' }] }),
    intent: {},
    update: {},
    view: (s) =>
      html`<svg viewBox="0 0 ${s.services.length * 12} 14" role="img" aria-label="Service status">
        ${each(s.services, (service) => service.id, tile)}
      </svg>`,
  },
);
```

An `svg` template is `html` for SVG content:

- **Its top level is SVG**, as if it stood inside an `<svg>`: `<path />` and `<g>` are SVG
  elements, self-closing tags are fine, and camelCase names such as `clipPath` and `viewBox`
  keep their case.
- **It renders only inside SVG content**: in a hole of an `<svg>` or of another SVG element. At
  a view's root or inside an HTML element, the browser's parser would build HTML elements from
  the server's markup, so it is an error in development, on the server and in the browser.
- **HTML at its top level is a template error.** HTML inside a graphic goes in a
  `<foreignObject>`, written with `html`.
- Bind `href=${…}`, not `xlink:href=${…}`: SVG 2's plain `href` is the one a binding can set.
  Static `xlink:href="#a"` is fine.

Only apps that use `svg` carry its code, about 0.2 KB minified.

## No event handlers

There is no `@click=${…}` binding, and a template that tries one doesn't compile. Views name an
[intent](https://gyral.dev/docs/intent/) with `data-intent=${i.Edit}` and let the intent layer read the event.
Everything a view needs to express, such as "this button means Edit, for item 42", fits in
markup: the intent name and the button's `value`.

## Checked before it runs

Templates are static, so their mistakes can be found before anyone loads the page. One set of
rules runs in three places, with the same messages:

- **`vite build`**, through `gyralVitePreset()`: every template is checked and precompiled, and a
  mistake fails the build with a code frame. Precompiled templates also leave the code that
  prepares templates at runtime out of your bundle. With the optional `parse5` package
  installed, the compiler also compares each template with what a full HTML parser builds.
- **The development runtime** (the dev server and tests) checks each template the first time it
  renders and throws with the same message (a production bundle built without the preset
  leaves out one check, rule 15 on component tag names, to stay small), naming where the template is written:
  `at src/cart.ts:12:5`. Under Vite the preset gives the exact file, line and column; elsewhere
  they come from the stack trace. Hydration mismatches name it too.
- **ESLint**, in your editor, with `@gyral/core/eslint`:

```js
// eslint.config.js
import gyral from '@gyral/core/eslint';

export default [
  // …your other configs (typescript-eslint, …)
  { files: ['src/**/*.ts'], ...gyral.configs.recommended },
];
```

The rules catch what would otherwise break quietly: an event binding, a `.value=` on a form
control, a self-closing `<my-el />` (HTML ignores the slash, so the element swallows what
follows it), an unquoted `class=a${b}`, markup the browser would repair (a `<tr>` directly in a
`<table>`, a `<div>` inside a `<p>`), an HTML element such as `<button>` inside an `<svg>` (it
would become an unknown SVG element that renders nothing), a bound `xlink:href=${…}`, a
`${…}` inside `<script>` or `<style>`, a list row that reads the view's variables, and a JSX-style `<SignupForm>` where the component's tag `<signup-form>` belongs. Each
message says what to write instead.

The ESLint config also reports a function written in a hole (`${() => …}`), which is never
right in a view, and warns, with `gyral/unused-intent`, about an intent parser that no template
in the module names with `data-intent`: a renamed intent or dead code. That rule is static, so
intents rendered only in some states count as used, and it skips components whose intent names
may be used in another module.

In development, Gyral also warns once when a property binding gets a function: `.onclick=${fn}`
on a built-in element (use `data-intent`), or a function prop on a Gyral component (props are
data, and they travel to the browser in hydration seeds). Other custom elements don't warn,
since a third-party widget's API may take a callback.

## Use the right element

Views are where accessibility is decided, and semantic HTML gets you most of it for free:

- A `<button>` for actions, an `<a href>` for navigation, a `<form>` for anything submitted.
- A `<label for>` for every control, `<output>` for computed values, `<fieldset>` and
  `<legend>` for groups.
- Landmarks (`<header>`, `<main>`, `<nav>`, `<search>`) and a sensible heading order.
- Native `<dialog>`, `popover` and `<details>` instead of hand-built widgets.

Forms with a real `action` and `method` keep working before JavaScript loads. See
[Forms](https://gyral.dev/docs/forms/).

## Lists

Render a list with `each(items, key, row, pick?)`. The key ties each row, and any child
component in it, to its item, so reordering moves elements instead of rewriting them.

A row re-renders only when its item or its `pick` result changes, and is skipped otherwise.
That makes long lists cheap, and it has one rule: **a row reads only its arguments and
module-level values.** Name intents with a module-level `intentsOf<typeof Component>()`, the
same names the view gets as `i`, and pass anything else from the view, such as the selection,
through `pick`. Write the row's return type (`: TemplateResult`) and use the view's own `i`, so
the row and the component don't infer each other's types:

```ts
// src/todos.ts
import { define, each, html, intentsOf, type TemplateResult } from '@gyral/core';

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

export interface State {
  readonly todos: readonly Todo[];
  readonly selected: number;
}

export type Msg =
  | { readonly _tag: 'Toggle'; readonly id: number }
  | { readonly _tag: 'Select'; readonly id: number };

// The intent names as a module constant, so rows can use them and stay pure.
const i = intentsOf<typeof Todos>();

// A row: reads only its item, what `pick` returned, and module constants.
const Row = (todo: Todo, selected: boolean): TemplateResult =>
  html`<li class=${selected ? 'selected' : ''}>
    <label>
      <input type="checkbox" value=${todo.id} ?checked=${todo.done} data-intent=${i.Toggle} />
      ${todo.text}
    </label>
    <button type="button" value=${todo.id} data-intent=${i.Select}>Select</button>
  </li>`;

const idOf = (value: string | undefined): number | undefined => {
  const id = Number(value);
  return Number.isInteger(id) ? id : undefined;
};

export const Todos = define<State, Msg>()('my-todos', {
  init: () => ({ todos: [{ id: 1, text: 'Write docs', done: false }], selected: 1 }),
  intent: {
    Toggle: ({ value }) => {
      const id = idOf(value);
      return id === undefined ? undefined : { _tag: 'Toggle', id };
    },
    Select: ({ value }) => {
      const id = idOf(value);
      return id === undefined ? undefined : { _tag: 'Select', id };
    },
  },
  update: {
    Toggle: (s, m) => ({
      ...s,
      todos: s.todos.map((t) => (t.id === m.id ? { ...t, done: !t.done } : t)),
    }),
    Select: (s, m) => ({ ...s, selected: m.id }),
  },
  view: (s) => html`
    <ul aria-label="Todos">
      ${each(
        s.todos,
        (todo) => todo.id,
        Row,
        (todo) => todo.id === s.selected,
      )}
    </ul>
  `,
});
```

When the selection moves, `pick` runs for every row (one comparison each), and only the two
rows whose answer changed render again. `pick` results are compared one level deep, so returning
a small tuple or object is fine.

- Keys are unique strings or numbers. A duplicate key is an error in development.
- The ESLint rule `gyral/each-row-purity` names any variable a row reads from the view and
  tells you to move it into `pick`.
- To get a fresh element when an id changes, use `keyed(s.run.id, Run(s.run))`: when the key
  changes, the old elements (and any component state in them) are discarded and new ones
  created. To restart a CSS animation, a hook is lighter: see
  [Replaying a CSS animation](#replaying-a-css-animation).

A whole list with add, delete and filters is in the
[todo list recipe](https://gyral.dev/docs/recipes/#a-todo-list-with-filters). Rows carry their item's id
(`value=${todo.id}`), never their position: with a filter on, a position points at the wrong
item ([why](https://gyral.dev/docs/recipes/#toggling-an-item-in-a-filtered-list-changes-the-wrong-item)).

### .map or each?

Plain arrays render too, by position: ``${s.tags.map((t) => html`<li>${t}</li>`)}``. Choose
by what the list does:

- **`.map`** for short lists whose items don't move: a few options, a breadcrumb, table headers.
  Its rows may read anything in the view's scope, since every row runs on every render. Keep
  them cheap, and sort or filter once above the template, not inside the row.
- **`each`** for lists that are long, change often or reorder: search results, an inbox, kanban
  columns. A moved item keeps its element, with its focus, input state and animations, and a
  row renders again only when its item or `pick` result changes. That second point is why
  `each` rows must be pure, and why `gyral/each-row-purity` checks only `each` rows.

### Moving items between lists

A task that moves from one kanban column to another leaves one `each` list and joins another,
so it is a new element, and the browser can't animate the move by itself. A FLIP hook can
("first, last, invert, play"): it remembers where each key was last seen and, when its element
appears somewhere else, plays the move with the Web Animations API.

```ts
// src/board.ts
import { define, defineHook, each, html, intentsOf, type TemplateResult } from '@gyral/core';

/** Where each key was last seen, in page coordinates. */
const seen = new Map<string, { readonly x: number; readonly y: number }>();

/** Animates the element from where `key` was last seen to where it is now. */
export const flip = defineHook<[key: string, slot: number]>({
  client: (el, [key]) => {
    const box = el.getBoundingClientRect();
    const now = { x: box.left + scrollX, y: box.top + scrollY };
    const before = seen.get(key);
    seen.set(key, now);
    if (before === undefined || matchMedia('(prefers-reduced-motion: reduce)').matches) return;
    const dx = before.x - now.x;
    const dy = before.y - now.y;
    if (dx === 0 && dy === 0) return;
    el.animate([{ transform: `translate(${dx}px, ${dy}px)` }, { transform: 'none' }], {
      duration: 200,
      easing: 'ease-out',
    });
  },
});

export interface Task {
  readonly id: string;
  readonly label: string;
}

export interface State {
  readonly todo: readonly Task[];
  readonly done: readonly Task[];
}

export type Msg = { readonly _tag: 'Move'; readonly id: string };

const i = intentsOf<typeof Board>();

const TaskCard = (t: Task, slot: number): TemplateResult =>
  html`<li ${flip(t.id, slot)}>
    <button type="button" value=${t.id} data-intent=${i.Move}>${t.label}</button>
  </li>`;

const column = (label: string, tasks: readonly Task[]) =>
  html`<section>
    <h2>${label}</h2>
    <ul>
      ${each(
        tasks,
        (t) => t.id,
        TaskCard,
        (t) => tasks.indexOf(t),
      )}
    </ul>
  </section>`;

export const Board = define<State, Msg>()('my-board', {
  init: () => ({
    todo: [
      { id: 'a', label: 'Write the release notes' },
      { id: 'b', label: 'Update the screenshots' },
    ],
    done: [],
  }),
  intent: { Move: ({ value }) => (value ? { _tag: 'Move', id: value } : undefined) },
  update: {
    Move: (s, { id }) => {
      const task = [...s.todo, ...s.done].find((t) => t.id === id);
      if (task === undefined) return s;
      return s.todo.includes(task)
        ? { todo: s.todo.filter((t) => t !== task), done: [...s.done, task] }
        : { done: s.done.filter((t) => t !== task), todo: [...s.todo, task] };
    },
  },
  view: (s) => html`${column('To do', s.todo)} ${column('Done', s.done)}`,
});
```

- **The hook gets the item's slot** (`pick` returns its index), so it also runs when a task
  shifts inside its column. A hook runs only when its arguments change: for the new element in
  the other column, and for tasks whose slot changed. Tasks that move because the layout changed
  around them, after a resize, aren't animated.
- **`seen` keeps the keys of deleted tasks.** Clear it when the board loads new data.
- **A View Transition doesn't replace the hook here.** No browser captures a
  `view-transition-name` set inside a shadow root, and components use shadow DOM by default, so
  rows named that way don't morph. [`viewTransition`](#view-transitions) with a per-row
  `view-transition-name` works only in a `shadow: false` component. In shadow DOM, the FLIP hook
  above is the way to animate moves between lists.

## Form state

Each piece of form state has one spelling, and it means the same on the server and in the
browser:

| Control                 | Write                                        |
| ----------------------- | -------------------------------------------- |
| Text-like `<input>`     | `value=${s.text}`                            |
| Checkbox or radio       | `?checked=${s.on}`                           |
| Indeterminate checkbox  | `?indeterminate=${s.some}`                   |
| `<option>`              | `?selected=${s.size === 'm'}`                |
| `<details>`, `<dialog>` | `?open=${s.open}`                            |
| `<textarea>`            | `<textarea name="note">${s.note}</textarea>` |

A binding writes the control only when the model's value for it changes. Then the model wins,
even after the user has edited the control (the view compares with what the control shows now
and writes only if they differ). A render for any other reason, such as another field's
message or a reducer that refused the edit, leaves what the user typed or toggled alone. On the
server the bindings write the attribute, so the page is right before JavaScript loads, and
hydration keeps what the user typed before scripts ran until the model's value changes.

To put a control back after a refused edit, change the model: clamp or normalize to a value
that differs from the one rendered last, or re-create the form with a key. Keep a counter in
the state, bump it on reset, and render `keyed(s.formKey, fields(s))`: the new key brings fresh
elements with the model's values. `form.reset()` is no substitute; it restores the first values, not the model's.

Never bind form state as a property (`.value=`, `.checked=`): the server can't write a
property, so the page would arrive empty. The compiler rejects it. A checkbox's `value` and a
`<button value>` are submitted values, not state, so they're plain attributes.

## Dialogs and popovers

A modal dialog opens with a method call, not an attribute, so Gyral gives it a binding of its
own. `?modal=${s.open}` on a `<dialog>` calls `showModal()` when the value turns true and
`close()` when it turns false; `?popover-open=${b}` does the same for an element with a
`popover` attribute (`showPopover()`, `hidePopover()`). The browser returns focus to the opener
when a modal closes. Escape and form `method="dialog"` close the dialog on their own, so listen
for that with an intent and keep the model in step:

Native opening runs after the element is inserted and its children render, before focus
commands. Conditional views, keyed replacements and initially open components follow the
same order. An opening action is cancelled if its element is removed before commit. If native
opening triggers a focus intent, Gyral renders that intent's new state before running focus
commands or resolving `settled()`.

```ts
// src/confirm-delete.ts
import { define, html } from '@gyral/core';

export type Msg = { readonly _tag: 'Ask' } | { readonly _tag: 'Closed' };

export const ConfirmDelete = define<{ readonly open: boolean }, Msg>()('my-confirm-delete', {
  init: () => ({ open: false }),
  intent: { Ask: true, Closed: true },
  update: {
    Ask: () => ({ open: true }),
    Closed: () => ({ open: false }),
  },
  view: (s, i) => html`
    <button type="button" data-intent=${i.Ask}>Delete…</button>
    <dialog ?modal=${s.open} data-intent=${i.Closed} data-intent-on="close">
      <form method="dialog">
        <p>Delete this task?</p>
        <button value="cancel">Cancel</button>
        <button value="delete">Delete</button>
      </form>
    </dialog>
  `,
});
```

On the server neither binding writes anything; a dialog that should start open opens when the
component hydrates. Use `?open` only for a non-modal `<dialog>` or `<details>`.

## Element hooks

A hook is a small behaviour attached to the element it sits on, written inside the start tag.
Core ships one, **`invalid(errors)`**, which mirrors model errors into native validity
(`setCustomValidity` and `aria-invalid`); see [Forms](https://gyral.dev/docs/forms/). Others are a few lines
each, such as capturing a pointer for [press-and-hold](https://gyral.dev/docs/intent/#press-and-hold).

Write your own with `defineHook`. `client(el, args, prev)` runs after the render whenever the
arguments change (`prev` is `undefined` the first time). An optional `server(args)` returns
attributes for the server-rendered start tag, so the page is right before scripts run. A hook
acts only on its own element, and listeners it adds there go away with the element, so most
hooks need no teardown:

```ts
// src/steps.ts
import { define, defineHook, html } from '@gyral/core';

/** Marks the current step, and scrolls it into view when it becomes current. */
export const currentStep = defineHook<[active: boolean]>({
  // The server writes the attribute into the start tag, so it's there before scripts run.
  server: ([active]) => (active ? { 'aria-current': 'step' } : {}),
  client: (el, [active], prev) => {
    if (active) el.setAttribute('aria-current', 'step');
    else el.removeAttribute('aria-current');
    if (active && prev !== undefined && !prev[0]) el.scrollIntoView({ block: 'nearest' });
  },
});

export interface State {
  readonly current: number;
}

export type Msg = { readonly _tag: 'Next' };

export const Steps = define<State, Msg>()('my-steps', {
  init: () => ({ current: 0 }),
  intent: { Next: () => ({ _tag: 'Next' }) },
  update: { Next: (s) => ({ current: (s.current + 1) % 3 }) },
  view: (s, i) => html`
    <ol>
      <li ${currentStep(s.current === 0)}>Choose</li>
      <li ${currentStep(s.current === 1)}>Pay</li>
      <li ${currentStep(s.current === 2)}>Done</li>
    </ol>
    <button type="button" data-intent=${i.Next}>Next step</button>
  `,
});
```

Hooks run after the whole render, children before parents, so a parent's hook can measure the
children that just rendered. A hook runs again when its arguments change; pass
`update: 'always'` to `defineHook` for one that runs after every render of its component, such
as a hook that keeps a scroll position anchored while a list grows.

### Custom properties

To hand a value to CSS, bind a custom property in a `style` attribute and let the stylesheet
use it, with a fallback:

```ts
// src/upload-progress.ts
import { css, define, html, prop, type Stateless } from '@gyral/core';

export interface Props {
  readonly sent: number;
  readonly total: number;
}

export const UploadProgress = define<Stateless, never, Props>()('my-upload-progress', {
  props: { sent: prop.number({ default: 0 }), total: prop.number({ default: 1 }) },
  intent: {},
  update: {},
  view: (_s, _i, { props }) => html`
    <div class="bar" style="--fill: ${props.sent / props.total}"></div>
    <p>${props.sent} of ${props.total} files</p>
  `,
  styles: css`
    .bar {
      block-size: 0.5rem;
      background: linear-gradient(to right, currentColor calc(var(--fill, 0) * 100%), #0000 0);
    }
  `,
});
```

Gyral writes `style` bindings through the CSSOM, so they work under a Content Security Policy
without `'unsafe-inline'`. In server-rendered markup such a policy blocks the attribute until the
component hydrates, which is why the stylesheet keeps a default, `var(--fill, 0)`. [Inline styles
under a strict CSP](https://gyral.dev/docs/styling/#inline-styles-under-a-strict-csp) has the details.

A `style` binding owns the whole attribute. For the rare element whose inline style a hook
writes too, let a hook set only the properties it names:

```ts
// src/css-vars.ts
import { defineHook } from '@gyral/core';

/** Sets the named custom properties, leaving the element's other inline styles alone. */
export const cssVars = defineHook<[vars: Readonly<Record<`--${string}`, string>>]>({
  client: (el, [vars]) => {
    if (!(el instanceof HTMLElement)) return;
    for (const [name, value] of Object.entries(vars)) el.style.setProperty(name, value);
  },
});
```

### Replaying a CSS animation

A CSS animation runs once, when its element appears. A "flash on change", such as an unread
badge that pulses when a message arrives or a field that shakes on a rejected value, has to
replay it. Count the replays in state, and restart the element's animations with the Web
Animations API when the count changes:

```ts
// src/inbox-badge.ts
import { css, define, defineHook, html } from '@gyral/core';

/** Restarts the element's CSS animations whenever `count` changes, not on the first render. */
export const replay = defineHook<[count: number]>({
  client: (el, [count], prev) => {
    if (prev === undefined || prev[0] === count) return;
    for (const animation of el.getAnimations()) {
      animation.cancel();
      animation.play();
    }
  },
});

export interface State {
  readonly unread: number;
  readonly pulses: number;
}

export type Msg = { readonly _tag: 'Arrived' };

export const InboxBadge = define<State, Msg>()('my-inbox-badge', {
  init: () => ({ unread: 0, pulses: 0 }),
  intent: { Arrived: () => ({ _tag: 'Arrived' }) },
  update: { Arrived: (s) => ({ unread: s.unread + 1, pulses: s.pulses + 1 }) },
  view: (s, i) => html`
    <output class="badge" ${replay(s.pulses)}>${s.unread}</output>
    <button type="button" data-intent=${i.Arrived}>Simulate a message</button>
  `,
  styles: css`
    .badge {
      animation: pulse 300ms ease-out;
    }
    @keyframes pulse {
      50% {
        scale: 1.3;
      }
    }
    @media (prefers-reduced-motion: reduce) {
      .badge {
        animation: none;
      }
    }
  `,
});
```

`getAnimations()` covers the CSS animations and transitions running on the element; pass
`{ subtree: true }` to include its descendants. The count lives in state because the model
decides when something deserves attention, and a count, unlike a boolean, changes every time.
Without a hook, `keyed(s.pulses, Badge(s))` replays by replacing the element, at the cost of a
new node (and its focus, if it had any).

## Widgets with a lifecycle

Something with setup and teardown, such as a WebGL stage, a chart or map library, an observer or
a connection, has a native home: **a custom element of its own**. Give it one property for its
input, keep its state inside, set up in `connectedCallback` and tear down in
`disconnectedCallback`. The browser then tells it about every connect, disconnect and move, the
view stays a description of data, and the widget can be tested on its own:

```ts
// src/scene-editor.ts
import { define, html } from '@gyral/core';

interface Scene {
  readonly cubes: number;
}

/** The widget: one property in, its own lifecycle. */
class StageElement extends HTMLElement {
  #scene: Scene = { cubes: 0 };
  #frame = 0;

  set view(scene: Scene) {
    this.#scene = scene;
    this.#schedule();
  }

  connectedCallback(): void {
    this.#schedule(); // set up the renderer, canvas and observers here
  }

  disconnectedCallback(): void {
    cancelAnimationFrame(this.#frame); // dispose the renderer and listeners here
  }

  #schedule(): void {
    cancelAnimationFrame(this.#frame);
    this.#frame = requestAnimationFrame(() => {
      this.textContent = `${String(this.#scene.cubes)} cubes`;
    });
  }
}
customElements.define('my-stage', StageElement);

interface State {
  readonly scene: Scene;
}

type Msg = { readonly _tag: 'Add' };

export const SceneEditor = define<State, Msg>()('my-scene-editor', {
  init: () => ({ scene: { cubes: 1 } }),
  intent: { Add: () => ({ _tag: 'Add' }) },
  update: { Add: (s) => ({ scene: { cubes: s.scene.cubes + 1 } }) },
  view: (s, i) => html`
    <my-stage .view=${s.scene}></my-stage>
    <button type="button" data-intent=${i.Add}>Add a cube</button>
  `,
});
```

The widget reports back with events: it dispatches
`new CustomEvent(OUTPUT_EVENT, { detail: { _tag: 'Picked' }, bubbles: true })` on itself, and the
parent parses that like a [child component's output](https://gyral.dev/docs/components/#outputs-and-other-code).
When the widget has a model of its own, make it a Gyral component (`prop.value` for its input,
`outputs<Out>()` for its events).

For a **small imperative behaviour** on an element of the view, such as a timer, a
`ResizeObserver` or a third-party enhancer on one input, a hook with a teardown is lighter:
`defineHook` takes `dispose(el, args)` next to `client`.

```ts
// src/flash.ts
import { defineHook } from '@gyral/core';

const timers = new WeakMap<Element, ReturnType<typeof setTimeout>>();

/** Highlights the element for a moment whenever `value` changes. */
export const flash = defineHook<[value: unknown]>({
  client: (el, _args, prev) => {
    if (prev === undefined) return; // not on the first render
    el.classList.add('flash');
    clearTimeout(timers.get(el));
    timers.set(
      el,
      setTimeout(() => {
        el.classList.remove('flash');
      }, 600),
    );
  },
  dispose: (el) => {
    clearTimeout(timers.get(el));
  },
});
```

- `dispose` runs when Gyral removes the element (its part cleared, its template replaced, its
  list row removed), when the position stops holding the hook, and when the component
  disconnects. It never runs for moves: rows reordered in a list, or a component moved with
  `moveBefore()`.
- After a component disconnects and reconnects, `client` runs again with `prev` undefined.
- The teardown tracking is bundled only when some hook has a `dispose`, so apps whose hooks
  need none don't pay for it.

## Trusted markup with raw()

`raw(markup)` renders a string as HTML: Markdown you converted at build time, highlighted code,
a JSON-LD script. Use it only for markup your own code produced, never for user input. It
belongs mostly on the server: in a component that renders in the browser, every change parses
the string again, and development mode warns about it. This site renders every docs page with
`raw()` inside a server-only template.

## Focus is a command

Moving focus is a side effect, so it comes from `update`, not the view. `focus(selector)`
focuses the first match in the component once the update has rendered, so it can target an
element the same update creates:

```ts
// src/pager.ts
import { define, focus, html } from '@gyral/core';

export interface State {
  readonly page: number;
}

export type Msg = { readonly _tag: 'Next' };

export const Pager = define<State, Msg>()('my-pager', {
  init: () => ({ page: 1 }),
  intent: { Next: () => ({ _tag: 'Next' }) },
  update: {
    // Move focus to the new page's heading, as a screen reader user would expect.
    Next: (s) => [{ page: s.page + 1 }, [focus('h2', { preventScroll: true })]],
  },
  view: (s, i) => html`
    <h2 tabindex="-1">Page ${s.page}</h2>
    <button type="button" data-intent=${i.Next}>Next page</button>
  `,
});
```

Headings aren't focusable by default, hence `tabindex="-1"`.

### Focusing what a later render brings

`focus()` runs after the render its update caused. When the target only appears later, such as
the first result once a search answers, pass `wait: true`: the request stays pending until a
render of the component produces the target. A newer `focus()` from the component replaces it,
and after one second it gives up with the usual warning. `settled()` doesn't wait for it.

```ts
// src/result-search.ts
import { command, define, defineDriver, focus, html } from '@gyral/core';

interface Result {
  readonly id: string;
  readonly title: string;
}
export interface State {
  readonly query: string;
  readonly results: readonly Result[];
}
export type Msg =
  | { readonly _tag: 'Search'; readonly query: string }
  | { readonly _tag: 'Found'; readonly results: readonly Result[] };

const search = defineDriver<string, readonly Result[]>({
  name: 'search',
  run: async (query, { signal }) => {
    const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal });
    return (await response.json()) as readonly Result[];
  },
});

export const ResultSearch = define<State, Msg>()('my-result-search', {
  init: () => ({ query: '', results: [] }),
  intent: {
    Search: ({ formData }) => ({ _tag: 'Search', query: String(formData?.get('q') ?? '') }),
  },
  update: {
    // The first result exists only after `Found` renders: the focus waits for it.
    Search: (s, m) => [
      { ...s, query: m.query },
      [
        command(search, m.query, { onSuccess: (results): Msg => ({ _tag: 'Found', results }) }),
        focus('#results li:first-child a', { wait: true }),
      ],
    ],
    Found: (s, m) => ({ ...s, results: m.results }),
  },
  view: (s, i) => html`
    <form data-intent=${i.Search}>
      <input name="q" aria-label="Search" value=${s.query} />
      <button>Search</button>
    </form>
    <ul id="results">
      ${s.results.map((r) => html`<li><a href=${`/items/${r.id}`}>${r.title}</a></li>`)}
    </ul>
  `,
});
```

### Focusing into a child component

`focus()` looks inside the component's own root, so it can't reach an element in a child's
shadow root. Give the child `shadow: { delegatesFocus: true }` and focus the child itself:
focusing the host then focuses its first focusable element.

```ts
// src/name-field.ts
import { define, html, type Stateless } from '@gyral/core';

/** Focusing <my-name-field> focuses its input. */
export const NameField = define<Stateless, never>()('my-name-field', {
  shadow: { delegatesFocus: true },
  intent: {},
  update: {},
  view: () => html`<label>Name <input name="name" autocomplete="name" /></label>`,
});
```

```ts
// src/contact-form.ts
import { define, focus, html, type Stateless } from '@gyral/core';
import './name-field.js';

export type Msg = { readonly _tag: 'Edit' };

export const ContactForm = define<Stateless, Msg>()('my-contact-form', {
  intent: { Edit: () => ({ _tag: 'Edit' }) },
  update: { Edit: (s) => [s, [focus('my-name-field')]] },
  view: (_s, i) => html`
    <button type="button" data-intent=${i.Edit}>Edit name</button>
    <my-name-field></my-name-field>
  `,
});
```

The same delegation works for `el.focus()` from page script and for a click on a part of the
child that can't take focus, and `:focus` matches the host while focus is inside it. The server
writes `shadowrootdelegatesfocus` on the declarative shadow root, so a server-rendered child
delegates focus before and after hydration.

### Keeping focus across renders

Focus stays only as long as the focused element does. When a render removes it, the browser
moves focus to the page body. Render focusable rows with a keyed `each`, so a row moves instead
of being created again, and when the focused item really goes away, such as a deleted row,
return a `focus()` command for its neighbour or for the list.

## Calling a method on an element

Some elements are driven by methods: a `<video>` plays, a third-party chart resets, a canvas
widget takes a command. `call(selector, method, ...args)` from `@gyral/core` is a command like
`focus()`: after the render, it finds the element in the component's own tree and calls the
method. Arguments must be plain data (they're checked in development), so the command stays a
value you can test with `callsIn(commands)` from `@gyral/testing`:

```ts
// src/clip.ts
import { call, define, html } from '@gyral/core';

export type Msg = { readonly _tag: 'Replay' };

export const Clip = define<object, Msg>()('my-clip', {
  init: () => ({}),
  intent: { Replay: true },
  update: { Replay: (s) => [s, [call('video', 'play')]] },
  view: (_s, i) => html`
    <video src="/intro.webm" muted playsinline></video>
    <button type="button" data-intent=${i.Replay}>Replay</button>
  `,
});
```

A missing element or method, or a method that throws, is reported through the
[error channel](https://gyral.dev/docs/error-handling/).

## View transitions

Return `true` from the optional `viewTransition(prev, next, msg)` spec field to render that
change inside a [View Transition](https://developer.mozilla.org/docs/Web/API/View_Transition_API):
a route change, a list that reorders. Gyral skips it where the browser has no support or the
visitor asked for reduced motion, and the animation itself is CSS. Browsers don't capture a
`view-transition-name` set inside a shadow root, so naming single items (rows that should morph
to their new place) needs a `shadow: false` component; the host element itself can carry a name.

## When the DOM updates

Reducers run as soon as a message arrives; the DOM updates in a microtask, once for all the
messages that arrived together, parents before children. Element hooks then run, children
before parents. In a test, `await settled()` waits
until every component has rendered and messages have stopped arriving. See
[Testing](https://gyral.dev/docs/testing/).

## Pure means repeatable

Because a view only reads its arguments, the server can render it, the browser can hydrate the
same markup without changes, and a test can render a state and inspect it. If a view needs the
time, a random number or a measurement, put it in state through a
[command](https://gyral.dev/docs/effects/) first.

---

# Styling and themes

> Style Gyral components with Shadow DOM, cascade layers, custom properties and custom states, and make a whole site themeable from CSS alone.

Source: https://gyral.dev/docs/styling/

Gyral adds nothing to CSS. Components are custom elements, so you style them with the platform:
Shadow DOM for encapsulation, custom properties for theming, cascade layers for order, and
custom states for reacting to the model.

## Styles in define()

`styles` holds the component's shadow-root CSS:

```ts
// src/tag.ts
import { css, define, html, prop, type Stateless } from '@gyral/core';

export const Tag = define<Stateless, never, { readonly label: string }>()('my-tag', {
  props: { label: prop.string({ required: true }) },
  intent: {},
  update: {},
  view: (_s, _i, { props }) => html`<span part="label">${props.label}</span>`,
  styles: css`
    @layer component {
      :host {
        display: inline-block;
      }
      span {
        padding-inline: 0.5em;
        border-radius: var(--tag-radius, 1em);
        background: var(--tag-bg, color-mix(in oklch, currentColor 12%, transparent));
      }
    }
  `,
});
```

`styles` accepts a `css` template, a plain CSS string (such as
`import base from './base.css?inline'`) or an array of them, nested freely. Strings let one
stylesheet module serve both the document and shadow roots. Either way, it must be your own
trusted CSS, never user input.

A `${…}` inside `css` inserts a string or number as written, and another `css` value as its
text, so constants and shared pieces compose:

```ts
// src/letters-styles.ts
import { css } from '@gyral/core';

export const TRANSITION_MS = 600;

const tokens = css`
  :host {
    --accent: oklch(55% 0.18 260);
  }
`;

export const lettersStyles = css`
  ${tokens}
  @layer component {
    li {
      color: var(--accent);
      transition: font-size ${TRANSITION_MS}ms ease-out;
    }
  }
`;
```

Each `css` value becomes one shared `CSSStyleSheet` in the browser, adopted by every shadow root
that uses it, so a thousand instances cost one sheet.

Styles in a shadow root don't leak out, and page styles don't leak in. Rendered on the server,
they travel inside the component's Declarative Shadow DOM as one `<style>` element, so they
apply before any JavaScript runs. When the component hydrates, Gyral swaps that element for the
shared sheet in the same step, so nothing flashes. A strict Content Security Policy doesn't need
`'unsafe-inline'` for them: `renderPage({ csp })` and `contentSecurityPolicy()` from `@gyral/ssr`
list each component's `<style>` by its hash (see [Server rendering](https://gyral.dev/docs/server-rendering/#content-security-policy)).

## Theming with custom properties

Custom properties inherit through shadow boundaries. That makes them the theming API of a
component: read a `--tag-bg` with a sensible default, and let the page set it.

```css
/* app.css */
@layer tokens {
  :root {
    color-scheme: light dark;
    --tag-bg: light-dark(oklch(94% 0.03 250), oklch(32% 0.05 250));
    --tag-radius: 0.25rem;
  }
}
```

Document the custom properties a component reads, and treat renaming one as a breaking change.
For pieces a theme may want to restyle completely, expose them as parts (`part="label"`) so the
page can write `my-tag::part(label) { … }`.

## Inline styles under a strict CSP

Some values don't come from a fixed set: a width the user dragged, a colour they picked. Bind
those as custom properties in a `style` attribute, a plain binding like any other, and let the
stylesheet use them:

```ts
// src/split-view.ts
import { css, define, html, prop, type Stateless } from '@gyral/core';

export interface Props {
  /** The sidebar width the user chose, in pixels. */
  readonly sidebar: number;
  readonly compact: boolean;
}

export const SplitView = define<Stateless, never, Props>()('my-split-view', {
  props: { sidebar: prop.number({ required: true }), compact: prop.boolean() },
  intent: {},
  update: {},
  view: (_s, _i, { props }) => html`
    <div
      class="split"
      data-density=${props.compact ? 'compact' : 'comfortable'}
      style="--sidebar: ${props.sidebar}px"
    >
      <aside><slot name="aside"></slot></aside>
      <div><slot></slot></div>
    </div>
  `,
  styles: css`
    .split {
      display: flex;
      gap: 1.5rem;
    }
    .split[data-density='compact'] {
      gap: 0.5rem;
    }
    aside {
      flex: none;
      inline-size: var(--sidebar, 16rem);
    }
  `,
});
```

A Content Security Policy without `'unsafe-inline'` blocks `style` attributes in HTML and
`setAttribute('style', …)`, but not styles set from script through the CSSOM. Here is what
that means for Gyral:

- **Client renders and updates always apply.** Gyral writes `style` bindings, and static
  `style="…"` attributes in templates, through the CSSOM (`el.style.cssText`), so a component
  rendered or updated in the browser needs no `'unsafe-inline'`.
- **Server HTML waits for hydration.** The server writes `style` as an attribute, so under a
  strict policy the first paint goes without it. When the component hydrates, Gyral applies the
  same value through the CSSOM. On a page that never hydrates, it stays blocked.

So plan the first paint around it. Values from a known set belong in the stylesheet, selected
by a class or a data attribute such as `data-density` above: they apply from the first paint,
with no inline style at all. Continuous values go in custom properties with a fallback in the
stylesheet, such as `inline-size: var(--sidebar, 16rem)`: the first paint uses the fallback,
and the user's width arrives with hydration. A page rendered per request can also allow its own
style attributes by hash, with `renderPage({ csp: { styleAttributes: 'hash' } })`
([Server rendering](https://gyral.dev/docs/server-rendering/#content-security-policy)), so they paint before
hydration.

## Custom states

To style by what the model says, mirror boolean facts onto the element's custom states with
`states`. CSS then reads them with `:state()`, inside and outside the component:

```ts
// src/upload.ts
import { css, define, html } from '@gyral/core';

export interface State {
  readonly phase: 'idle' | 'uploading' | 'failed';
}

export type Msg = { readonly _tag: 'Retry' };

export const Upload = define<State, Msg>()('my-upload', {
  init: () => ({ phase: 'idle' }),
  intent: { Retry: () => ({ _tag: 'Retry' }) },
  update: { Retry: () => ({ phase: 'uploading' }) },
  states: (s) => ({ busy: s.phase === 'uploading', failed: s.phase === 'failed' }),
  view: (s, i) => html`
    <p aria-busy=${s.phase === 'uploading'}>${s.phase}</p>
    <button type="button" data-intent=${i.Retry}>Retry</button>
  `,
  styles: css`
    :host(:state(failed)) p {
      color: var(--danger, crimson);
    }
  `,
});
```

From the page: `my-upload:state(busy) { opacity: 0.6; }`. No classes to keep in sync, and the
model stays the single source of truth. Custom states are for styling; accessibility state still
belongs in ARIA attributes such as `aria-busy`, as above. They are applied in the browser only.

## Cascade layers

Put every stylesheet in a layer, and declare the order once:

```css
@layer reset, tokens, base, components, theme;
```

Later layers win regardless of specificity, so a theme never has to out-specify a component.
Gyral's examples and the [gyral-shop](https://github.com/gyraljs/gyral-shop) put component CSS
in `@layer component` (or `components`) and leave the last layer for themes.

## Light-DOM components

Some components are pages, not widgets: a product listing with its `<h1>`, a docs article. For
those, `shadow: false` renders the view as the element's own children:

```ts
// src/article-page.ts
import { define, html, prop, type Stateless } from '@gyral/core';

export const ArticlePage = define<Stateless, never, { readonly heading: string }>()(
  'my-article-page',
  {
    shadow: false,
    props: { heading: prop.string({ required: true }) },
    intent: {},
    update: {},
    view: (_s, _i, { props }) => html`
      <article>
        <h1>${props.heading}</h1>
      </article>
    `,
  },
);
```

- Document CSS applies directly, so the page's stylesheet and theme can lay it out.
- On the server it renders as plain HTML, with no `<template shadowrootmode>`, which every
  crawler and reader mode understands.
- It has no `styles` and no `<slot>`s: it owns all its children. Don't write children inside
  its tag; pass data as props (the server throws on children it would have to drop). Scope its
  CSS with `@scope (my-article-page) { … }` or by tag name.
- Intent isolation still holds: a light component's intents stop at the next Gyral component
  inside it.

Keep widgets (buttons, dialogs, form controls) in Shadow DOM, and use light DOM for page
structure.

## A whole site as a theme

Put those together and a site's look can live entirely in CSS, the way the
[CSS Zen Garden](https://csszengarden.com) did it. gyral-shop's theme contract is a worked
example:

1. **Markup is semantic and theme-neutral.** Elements are chosen for meaning, never for looks.
2. **Stable hooks.** Pages carry `data-region="listing"`, components `data-component="price"`,
   and regions and cards declare container names. Hooks are documented, and renaming one is a
   breaking change.
3. **Tokens.** Every colour, font, radius, spacing and motion value is a custom property, set
   for light and dark with `light-dark()`. A check in the build rejects literal colours outside
   token files.
4. **Light DOM for page structure, Shadow DOM for widgets.** Themes can re-lay out pages with
   grid areas, container queries and `:has()`, and restyle widgets through tokens and parts.
5. **Themes are stylesheets** in `@layer theme`. The server renders the chosen theme's
   `<link>`, so there's no flash of the wrong theme.

The shop switches between four themes this way, from a dense marketplace to an airy boutique,
without changing any markup. See them on the [home page](https://gyral.dev/#showcase).

---

# Forms

> A complete validated form to copy, then the browser's own checks or one Standard Schema for client and server. Works with or without JavaScript.

Source: https://gyral.dev/docs/forms/

Gyral forms are real `<form>` elements, and a submit is an intent like any other. Start from
the complete example below: one component with everything a validated form needs, built on the
browser's own checks, with no extra packages. Copy it and change the fields; you don't need
another page to make it work.

## Complete example: a validated form

A signup form with a name, an email, a password and a checkbox the user must tick. On submit it
shows every error next to its field, announces how many fields to fix, and moves focus to the
first invalid one. Fixing a field clears its error; a valid submit announces a welcome.

```ts
// src/account-form.ts
import { define, focus, html } from '@gyral/core';

/** The fields, in the order they appear: the first one with an error gets focus. */
export const FIELDS = ['name', 'email', 'password', 'consent'] as const;
export type Field = (typeof FIELDS)[number];

/** One message per field; `''` means no error. */
export type Errors = Readonly<Record<Field, string>>;

export const NO_ERRORS: Errors = { name: '', email: '', password: '', consent: '' };

export interface State {
  readonly errors: Errors;
  /** What the live region announces after a rejected submit; `''` otherwise. */
  readonly summary: string;
  /** The clean values after a successful signup. */
  readonly account: { readonly name: string; readonly email: string } | undefined;
}

export type Msg =
  | { readonly _tag: 'Rejected'; readonly errors: Errors }
  | { readonly _tag: 'SignedUp'; readonly name: string; readonly email: string }
  | { readonly _tag: 'Checked'; readonly field: Field; readonly error: string };

const isField = (name: string): name is Field => FIELDS.some((f) => f === name);

/**
 * Your message for a field's first problem, from the browser's own checks (`validity`), or
 * `''` when the field is fine. The constraints in the markup (`required`, `type="email"`,
 * `minlength`) still decide what is wrong; `novalidate` only stops the browser from
 * blocking the submit and showing its own bubble.
 */
export function problemWith(input: HTMLInputElement): string {
  const { validity } = input;
  // A checkbox is missing when unchecked. `required` accepts "   ", so blank text is missing too.
  const missing =
    input.type === 'checkbox' ? !input.checked : validity.valueMissing || input.value.trim() === '';
  switch (input.name) {
    case 'name':
      return missing ? 'Enter your name.' : '';
    case 'email':
      if (missing) return 'Enter your email address.';
      return validity.typeMismatch ? 'Enter an email address like ada@example.com.' : '';
    case 'password':
      if (missing) return 'Enter a password.';
      // `tooShort` is set only for typed values; the length check also covers a pre-filled one.
      return validity.tooShort || input.value.length < input.minLength
        ? 'Use at least 8 characters.'
        : '';
    case 'consent':
      return missing ? 'Accept the privacy policy to continue.' : '';
    default:
      return '';
  }
}

/** What the status region announces after a successful signup. */
const welcome = (account: State['account']): string =>
  account === undefined ? '' : `Welcome, ${account.name}! We’ll write to ${account.email}.`;

/** Reads a submitted form: every field's error, or the clean values. */
function submission(form: Element, data: FormData | undefined): Msg | undefined {
  if (!(form instanceof HTMLFormElement) || data === undefined) return undefined;
  const errors: Record<Field, string> = { ...NO_ERRORS };
  for (const field of FIELDS) {
    const input = form.elements.namedItem(field);
    if (input instanceof HTMLInputElement) errors[field] = problemWith(input);
  }
  if (FIELDS.some((f) => errors[f] !== '')) return { _tag: 'Rejected', errors };
  const text = (field: Field): string => {
    const value = data.get(field);
    return typeof value === 'string' ? value.trim() : '';
  };
  // The password stays in the form data: never keep it in state.
  return { _tag: 'SignedUp', name: text('name'), email: text('email') };
}

export const AccountForm = define<State, Msg>()('my-account-form', {
  init: () => ({ errors: NO_ERRORS, summary: '', account: undefined }),
  intent: {
    // Not a message tag, so it may return either message.
    Submit: ({ target, formData }) => submission(target, formData),
    // Text fields send it on `input`, the checkbox on `change`.
    Checked: ({ target }) =>
      target instanceof HTMLInputElement && isField(target.name)
        ? { _tag: 'Checked', field: target.name, error: problemWith(target) }
        : undefined,
  },
  update: {
    // Show every error at once, announce how many, and focus the first field that has one.
    Rejected: (s, m) => {
      const count = FIELDS.filter((f) => m.errors[f] !== '').length;
      const first = FIELDS.find((f) => m.errors[f] !== '');
      const summary = `Fix ${String(count)} ${count === 1 ? 'field' : 'fields'} to continue.`;
      const focusFirst = first === undefined ? [] : [focus(`#${first}`)];
      return [{ ...s, errors: m.errors, summary }, focusFirst];
    },
    // In an app, this also returns the command that posts the form.
    SignedUp: (_s, m) => ({
      errors: NO_ERRORS,
      summary: '',
      account: { name: m.name, email: m.email },
    }),
    // While the user types, only a field that already shows an error is checked again,
    // so a message changes or disappears as soon as the value is fixed.
    Checked: (s, m) =>
      s.errors[m.field] === '' ? s : { ...s, errors: { ...s.errors, [m.field]: m.error } },
  },
  // No `value` bindings: what the user typed stays in the fields after a rejected submit.
  view: (s, i) => html`
    <form novalidate data-intent=${i.Submit}>
      <p role="alert">${s.summary}</p>

      <label for="name">Name</label>
      <input
        id="name"
        name="name"
        autocomplete="name"
        required
        aria-invalid=${s.errors.name !== ''}
        aria-describedby="name-error"
        data-intent=${i.Checked}
      />
      <p id="name-error">${s.errors.name}</p>

      <label for="email">Email</label>
      <input
        id="email"
        name="email"
        type="email"
        autocomplete="email"
        required
        aria-invalid=${s.errors.email !== ''}
        aria-describedby="email-error"
        data-intent=${i.Checked}
      />
      <p id="email-error">${s.errors.email}</p>

      <label for="password">Password</label>
      <input
        id="password"
        name="password"
        type="password"
        autocomplete="new-password"
        required
        minlength="8"
        aria-invalid=${s.errors.password !== ''}
        aria-describedby="password-error"
        data-intent=${i.Checked}
      />
      <p id="password-error">${s.errors.password}</p>

      <input
        id="consent"
        name="consent"
        type="checkbox"
        required
        aria-invalid=${s.errors.consent !== ''}
        aria-describedby="consent-error"
        data-intent=${i.Checked}
      />
      <label for="consent">I accept the privacy policy</label>
      <p id="consent-error">${s.errors.consent}</p>

      <button>Create account</button>
    </form>
    <p role="status">${welcome(s.account)}</p>
  `,
});
```

What each part does:

- **`novalidate` on the form, constraints on the fields.** `required`, `type="email"` and
  `minlength` still set each field's `validity`; `novalidate` only stops the browser from
  blocking the submit with its own bubble. Without it, no `submit` event fires and your
  messages never appear.
- **The submit intent is the parser.** `data-intent=${i.Submit}` on the `<form>` runs `Submit`
  on `submit` (and Gyral prevents the page load). `target` is the `<form>`, so
  `target.elements.namedItem('email')` is the email input, and `formData` holds the submitted
  values. `Submit` isn't a message tag, so it may return either message: `Rejected` with every
  field's error, or `SignedUp` with the trimmed values.
- **`problemWith(input)` turns `validity` into your words**: `valueMissing`, `typeMismatch`,
  `tooShort`, and `checked` for the checkbox. It trims first, because `required` accepts a value
  of spaces.
- **Errors are state**: one string per field, `''` for none. The view writes each message in a
  `<p>` next to its field, links it with `aria-describedby` and sets `aria-invalid`.
- **The `role="alert"` paragraph announces the summary.** It is always rendered, empty until a
  submit fails, so screen readers announce the text when it appears. `role="status"` announces
  the welcome the same way, politely.
- **Focus moves to the first invalid field** with a `focus()` command returned from the
  `Rejected` reducer. Commands are data; the runtime moves the focus after rendering.
- **Fixing a field clears its error.** Each control sends `Checked` (text fields on `input`,
  the checkbox on `change`); the reducer updates only a field that already shows an error, so
  nothing turns red while someone is still typing.
- **Values stay in the fields.** The view binds no `value`, so a rejected submit leaves what the
  user typed. Bind `value=${s.name}` only when state must set the text, such as emptying a
  field after a submit.
- **Enter submits**, because the form has a submit button, and a click submits the same way.
- **No password in state.** `SignedUp` carries the name and the email only.

To adapt it, add the field's name to `FIELDS`, give it a `case` in `problemWith`, and render a
labelled control with the same `id` and `name` plus its error `<p>`. To send the form to a
server, keep the raw `FormData` in the message and return a command that posts it, as in
[Submitting to the server](#submitting-to-the-server). The
[signup form recipe](https://gyral.dev/docs/recipes/#a-signup-form-with-native-validation) has the same
component with its tests: the reducers without a browser, and the parser with `mount()`.

There are two ways to validate a form. The example uses the first; add the second when a server
needs the same rules.

- **[Native validation](#native-validation)**, with no extra packages. The browser's
  constraints (`required`, `type="email"`, `minlength`) find what is wrong, and the submit
  parser reads each field's `validity` and returns your messages. It works in any app,
  including a new `basic` one.
- **[One schema for both sides](#one-schema-for-both-sides).** A
  [Standard Schema](https://standardschema.dev) library validates in the browser and on the
  server, the form posts with `@gyral/http`, and the same errors render without JavaScript.

## Native validation

**`required` without `novalidate` hides your errors.** The browser checks constraints before
it fires `submit`. When one fails, it shows its own bubble and fires no `submit` event, so your
parser never runs and your messages never appear. Put `novalidate` on any form that shows its
own errors, and keep the constraints on the fields: they still set `validity`, which the parser
reads, as in the [complete example](#complete-example-a-validated-form).

Each constraint sets one `validity` flag, so the parser can say exactly what is wrong:

| Constraint                       | Flag                                              | Notes                               |
| -------------------------------- | ------------------------------------------------- | ----------------------------------- |
| `required`                       | `valueMissing`                                    | A value of spaces passes: trim it   |
| `required` on a checkbox         | `valueMissing`                                    | Set while it is unchecked           |
| `type="email"`, `type="url"`     | `typeMismatch`                                    | Only for a value that isn't empty   |
| `minlength`, `maxlength`         | `tooShort`, `tooLong`                             | Only after the user edits the value |
| `pattern`                        | `patternMismatch`                                 |                                     |
| `min`, `max`, `step`             | `rangeUnderflow`, `rangeOverflow`, `stepMismatch` | Numbers, dates and times            |
| `type="number"`, unparsable text | `badInput`                                        | The `value` reads as `''`           |

`validity.valid` is `true` when no flag is set, and `form.checkValidity()` asks every field at
once. A message set with `setCustomValidity()`, as the [`invalid()`](#form-and-invalid) hook
does, sets `customError`, so read the specific flags rather than `valid` when you combine them.

`novalidate` in server-rendered markup turns validation off for visitors without JavaScript
too. If your form also posts to a server, render `?novalidate=${s.live}` and set `live` in the
`Hydrated` reducer, as in [Schema messages for everything](#schema-messages-for-everything),
and validate again on the server.

## One schema for both sides

When a server handles the form too, validate it with one schema on both sides. Each layer is
optional; use as many as a form needs:

1. **Native constraints**: `required`, `type="email"`, `minlength`, `pattern`.
2. **A schema-parsed intent**: `form(schema, toMsg)` validates the submission.
3. **Errors in the model**, mirrored into native validity with `invalid()`.
4. **Server checks** as ordinary commands: `submitForm()` posts the form.
5. **No-JavaScript parity**: the server's `formAction()` validates with the same schema and
   renders the same errors.

This path needs `@gyral/http` for the post, `@gyral/ssr` for the server half and a schema
library. Define the form once with any [Standard Schema](https://standardschema.dev) library, such as
Zod, Valibot, ArkType or Effect Schema. Form values arrive as strings; the schema coerces them.

```ts
// src/signup-form.ts
import { defineForm } from '@gyral/core';
import * as v from 'valibot';

export const SignupForm = defineForm(
  v.object({
    email: v.pipe(v.string(), v.trim(), v.email('Enter an email address like ada@example.com.')),
    password: v.pipe(v.string(), v.minLength(8, 'Use at least 8 characters.')),
    invite: v.optional(v.string()),
  }),
  // Never echoed back after a failed submit. Fields named like `password` are secret already.
  { secret: ['invite'] },
);
```

The definition is also what the server uses: `SignupForm.validate(data)` checks a `FormData`
the way `form()` does, and `SignupForm.values(data)` returns the submitted values to re-fill a
form, without its secret fields.

**Secret fields are never echoed.** After a failed submit, the submitted values come back so the
form can be re-filled, except fields listed in `secret` (any posted field name, not only the
schema's) and any field whose name contains `password`, `passcode`, `csrf` or `xsrf`. They're left out of `IntentRejected.values` on both paths and out of
`values()`, and the devtools timeline shows them as `[secret]`. Development builds warn once
about an unlisted field whose name looks secret (`token`, `card`, `cvc`, …).

## form() and invalid()

```ts
// src/signup.ts
import { define, fieldErrors, form, html, invalid } from '@gyral/core';
import { redirectedTo, submitForm } from '@gyral/http';
import { SignupForm } from './signup-form.js';

export interface State {
  readonly email: string;
  readonly errors: Readonly<Record<string, readonly string[]>>;
  readonly busy: boolean;
  readonly done: string | undefined;
}

export type Msg =
  | { readonly _tag: 'Submit'; readonly form: FormData }
  | { readonly _tag: 'Done'; readonly location: string | undefined }
  | { readonly _tag: 'Failed' };

export const Signup = define<State, Msg>()('my-signup', {
  init: () => ({ email: '', errors: {}, busy: false, done: undefined }),
  intent: {
    // Valid in the browser: post the raw FormData so the server parses it like a no-JS post.
    Submit: form(SignupForm, (_data, raw) => ({ _tag: 'Submit', form: raw })),
  },
  update: {
    Submit: (s, m) => [
      { ...s, errors: {}, busy: true },
      [
        submitForm('/signup', m.form, {
          onSuccess: (body): Msg => ({ _tag: 'Done', location: redirectedTo(body) }),
          onFailure: (): Msg => ({ _tag: 'Failed' }),
        }),
      ],
    ],
    Done: (s, m) => ({ ...s, busy: false, done: m.location ?? '/' }),
    Failed: (s) => ({ ...s, busy: false, errors: { '': ['Something went wrong. Try again.'] } }),
    // Browser-side and server-side rejections arrive as the same message.
    IntentRejected: (s, m) => ({
      ...s,
      busy: false,
      email: typeof m.values?.['email'] === 'string' ? m.values['email'] : s.email,
      errors: fieldErrors(m.issues),
    }),
  },
  view: (s, i) => html`
    <form data-intent=${i.Submit} action="/signup" method="post">
      <label for="email">Email</label>
      <input
        id="email"
        name="email"
        type="email"
        autocomplete="email"
        required
        value=${s.email}
        aria-describedby="email-error"
        ${invalid(s.errors['email'])}
      />
      <span id="email-error">${s.errors['email']?.join(' ') ?? ''}</span>

      <label for="password">Password</label>
      <input
        id="password"
        name="password"
        type="password"
        autocomplete="new-password"
        minlength="8"
        required
        aria-describedby="password-error"
        ${invalid(s.errors['password'])}
      />
      <span id="password-error">${s.errors['password']?.join(' ') ?? ''}</span>

      <p role="alert">${s.errors['']?.join(' ') ?? ''}</p>
      <button ?disabled=${s.busy}>Create account</button>
    </form>
  `,
});
```

What happens on submit:

- **The browser checks native constraints first.** If `required` or `type="email"` fails, the
  browser shows its own message and no `submit` event fires, so `form()` doesn't run. Keep
  them: they work without JavaScript and are accessible. To show the schema's messages instead,
  see [Schema messages for everything](#schema-messages-for-everything).
- **`form(schema, toMsg)`** turns the `FormData` into a plain object (repeated names become
  arrays) and validates it. Valid data goes to `toMsg`, which also gets the raw `FormData`.
  Invalid data becomes `IntentRejected`, with one issue per field: `path` matches the field's
  `name`.
- **Errors live in state.** `fieldErrors(issues)` groups them by field. Keep the result in
  state: it is data, so tests can see it.
- **`invalid(errors)`** is an [element hook](https://gyral.dev/docs/views/#element-hooks) that mirrors a field's
  errors into native validity: it calls `setCustomValidity` and sets `aria-invalid`, so
  `:user-invalid` styling, the browser's error bubble and your model agree. It clears the error
  when the user edits the field.
- **The server writes `aria-invalid="true"` too**: the hook has a server half that adds it to the
  rendered start tag, so the no-JavaScript page announces errors. `aria-describedby` points at
  the message, which is plain text in the view.

`field(schema, toMsg)` does the same for a single control. Pair it with
`data-intent-on="input"` to check while the user types.

## Submitting to the server

Some checks only the server can make: the email is taken, the password is wrong. That's why
the `Submit` reducer above posts the submission with `submitForm(url, formData, handlers)` from
`@gyral/http`, once it passed the browser's checks:

- The body is the `FormData` itself, so the server parses it exactly like a no-JS post.
- A `422` answer with an `IntentRejected` body goes to your `IntentRejected` reducer, the same
  one that handles browser-side rejections.
- The CSRF token comes from the `http` driver's headers, set once for the app:
  `makeHttpDriver({ headers: csrfFromMeta('csrf-token') })` ([Effects](https://gyral.dev/docs/effects/)).
  `csrf: { token }` sends a token the app already holds.
- The default concurrency is `exhaust`: a double click doesn't submit twice.
- `redirectedTo(body)` reads the location when the server answered with a redirect.

## The server half

On the server, `formAction(definition, handlers)` from `@gyral/ssr` handles the same route for
both paths:

```ts
// server/app.ts
import { Hono } from 'hono';
import { html, type IntentRejected } from '@gyral/core';
import { formAction, rejectWith, renderPage, seeOther } from '@gyral/ssr';
import { SignupForm } from '../src/signup-form.js';

const taken = new Set(['ada@example.com']);

const signupPage = (rejected: IntentRejected | undefined, status = 200): Response =>
  renderPage(
    {
      title: 'Create an account',
      body: html`<main>
        <h1>Create an account</h1>
        <my-signup .initialMessages=${rejected === undefined ? [] : [rejected]}></my-signup>
      </main>`,
      scripts: ['/src/entry-client.ts'],
    },
    { status },
  );

export const app = new Hono();

app.get('/signup', () => signupPage(undefined));

app.post('/signup', (c) =>
  formAction(SignupForm, {
    intent: 'Submit', // the form's data-intent name
    valid: (data) =>
      taken.has(data.email)
        ? rejectWith([{ path: 'email', message: 'That email is already registered.' }])
        : seeOther('/welcome'),
    invalid: (rejected) => signupPage(rejected, 422),
  })(c.req.raw),
);
```

- **One validator.** `formAction` runs the definition's `validate`, as `form()` does, so a
  submission is rejected with identical issues on either path.
- **One reducer.** On failure, the server renders the component with
  `initialMessages: [rejected]`. The component's own `IntentRejected` reducer builds the error
  state during the server render, and the browser resumes from it.
- **Post/Redirect/Get.** `seeOther(url)` answers `303`, so reloading never resubmits.
- **JSON for the JavaScript path.** When `submitForm` asks for JSON, a redirect becomes
  `{ _tag: 'Redirected', location }` and a rejection a `422` without the submitted values.
  Browser form posts get HTML. Leave `invalid` out and every rejection is that JSON `422`;
  `wantsJson(request)` tells your own routes which kind of request they got.
- **`rejectWith(issues | message)`** rejects a schema-valid submission; a string is a
  form-level message (path `''`).

Never keep passwords in state either: server-rendered state is written into the page.

## Schema messages for everything

Native constraints run before `form()`, so a missing required field shows the browser's wording,
not your schema's. That's usually what you want. If you'd rather show the schema's messages for
everything, keep the constraints in the server-rendered markup and add `novalidate` once the
component is live:

```html
<form data-intent="${i.Submit}" ?novalidate="${s.live}">…</form>
```

with `Hydrated: (s) => ({ ...s, live: true })` in `update`. No-JavaScript visitors still get
native validation, and every JavaScript submit reaches `form()`.

## File uploads

For a custom element that submits a native form value, see
[Custom form controls](https://gyral.dev/docs/form-associated/).

Use a native file input and keep the raw `FormData` from the parsed submit. This sends the
file bytes instead of converting them to JSON:

```ts
// src/photo-upload.ts
import { define, defineForm, form, html } from '@gyral/core';
import { submitForm } from '@gyral/http';
import * as v from 'valibot';

const PhotoForm = defineForm(v.object({ photo: v.instance(File) }));
type State = { readonly status: string };
type Msg =
  | { readonly _tag: 'Submit'; readonly data: FormData }
  | { readonly _tag: 'Uploaded' }
  | { readonly _tag: 'Failed' };

export const PhotoUpload = define<State, Msg>()('photo-upload', {
  init: () => ({ status: 'Choose a photo.' }),
  intent: { Submit: form(PhotoForm, (_data, raw) => ({ _tag: 'Submit', data: raw })) },
  update: {
    Submit: (_s, m) => [
      { status: 'Uploading…' },
      [
        submitForm('/photos', m.data, {
          onSuccess: (): Msg => ({ _tag: 'Uploaded' }),
          onFailure: (): Msg => ({ _tag: 'Failed' }),
        }),
      ],
    ],
    Uploaded: () => ({ status: 'Photo uploaded.' }),
    Failed: () => ({ status: 'Upload failed. Try again.' }),
    IntentRejected: () => ({ status: 'Choose a photo before uploading.' }),
  },
  view: (s, i) => html`
    <form action="/photos" method="post" enctype="multipart/form-data" data-intent=${i.Submit}>
      <label for="photo">Photo</label>
      <input id="photo" name="photo" type="file" accept="image/*" required />
      <button type="submit">Upload</button>
      <output aria-live="polite">${s.status}</output>
    </form>
  `,
});
```

Do not set `content-type` yourself: the browser adds the multipart boundary. `accept` is a
picker hint, not server validation. The server must enforce size, count, content and storage
rules and apply authentication/CSRF checks. The schema above checks only that a file object
exists; add your application's browser checks and validate again on the server. File inputs
cannot be restored from a hydration seed or sticky rejected values; keep files in the submit
boundary, not model state. See [Security](https://gyral.dev/docs/security/#uploaded-files).

---

# Custom form controls

> Make a Gyral component participate in native forms, with reset, disabled state, validity and a server-rendered fallback.

Source: https://gyral.dev/docs/form-associated/

Use `formAssociated` when the custom element itself should submit a native form value under
its `name` attribute. The projection stays pure; Gyral owns the ElementInternals attachment.

```ts
// src/choice-field.ts
import { define, html } from '@gyral/core';

interface State {
  readonly value: string;
  readonly live: boolean;
  readonly disabled: boolean;
}
type Msg = { readonly _tag: 'Edited'; readonly value: string };

export const ChoiceField = define<State, Msg>()('my-choice-field', {
  init: () => ({ value: 'Default', live: false, disabled: false }),
  intent: { Edited: ({ value }) => ({ _tag: 'Edited', value: value ?? '' }) },
  update: {
    Edited: (s, m) => ({ ...s, value: m.value, live: true }),
    FormDisabled: (s, m) => ({ ...s, disabled: m.disabled }),
    FormReset: (s) => ({ ...s, value: 'Default' }),
    FormStateRestore: (s, m) =>
      typeof m.state === 'string' ? { ...s, value: m.state, live: true } : s,
  },
  formAssociated: { value: (s) => (s.live ? s.value : null) },
  shadow: false,
  view: (s, i) => html`
    <label>
      Choice
      <input
        name=${s.live ? undefined : 'choice'}
        value=${s.value}
        ?disabled=${s.disabled}
        data-intent=${i.Edited}
      />
    </label>
  `,
});
```

```html
<form action="/choices" method="post">
  <my-choice-field name="choice"></my-choice-field>
  <button type="submit">Save</button>
  <button type="reset">Reset</button>
</form>
```

The light DOM fallback input participates in the outer form before JavaScript runs. The
custom control returns `null` until an input event captures the live value in the model.
It then submits that value and removes the fallback's `name`, avoiding duplicate entries.
The input remains usable. Switching solely on `Hydrated` can lose a value typed before
hydration; Gyral does not automatically read arbitrary fallback inputs into state.

`value` may return a string, File, FormData or null. An optional `state` projection supplies
a separate restoration value. Keep server-rendered model state JSON-compatible; binary
values belong at the browser boundary.

An optional `validity` projection returns native flags, a message and an anchor selector:

```ts
const validity = (s: { readonly value: string }) =>
  s.value === ''
    ? { flags: { customError: true }, message: 'Enter a choice.', anchor: 'input' }
    : undefined;
```

Returning `undefined` clears validity. Mirror effective disabled state to inner controls.
`FormReset`, `FormDisabled` and `FormStateRestore` reducers are optional; reset does not rerun
`init`. Restoration messages carry `state` and `mode` (`restore` or `autocomplete`). Forms
and the `states` spec share Gyral's single internals attachment.

---

# Effects and drivers

> Reducers return commands, side effects described as data. Drivers run them, with built-in concurrency, retries and cancellation, and answer with messages.

Source: https://gyral.dev/docs/effects/

Reducers can't fetch, wait or write to storage, because they're pure. Instead they return
**commands**: plain objects that describe a side effect and say which message the outcome
becomes. A **driver** runs the command and answers with that message. Effects are data, and
they happen at the edges.

## Commands as data

```ts
// src/user.ts
import { define, html } from '@gyral/core';
import { get, type HttpError } from '@gyral/http';
import * as v from 'valibot';

const User = v.object({ name: v.string(), email: v.string() });

export type State =
  | { readonly _tag: 'Idle' }
  | { readonly _tag: 'Loading' }
  | { readonly _tag: 'Loaded'; readonly name: string; readonly email: string }
  | { readonly _tag: 'Failed'; readonly reason: string };

export type Msg =
  | { readonly _tag: 'Load'; readonly id: number }
  | { readonly _tag: 'Loaded'; readonly name: string; readonly email: string }
  | { readonly _tag: 'Failed'; readonly error: HttpError };

export const UserCard = define<State, Msg>()('my-user-card', {
  init: () => ({ _tag: 'Idle' }),
  intent: { Load: ({ value }) => ({ _tag: 'Load', id: Number(value) }) },
  update: {
    Load: (_s, m) => [
      { _tag: 'Loading' },
      [
        get(`https://jsonplaceholder.typicode.com/users/${String(m.id)}`, {
          schema: User,
          onSuccess: (user): Msg => ({ _tag: 'Loaded', ...user }),
          onFailure: (error): Msg => ({ _tag: 'Failed', error }),
        }),
      ],
    ],
    Loaded: (_s, m) => ({ _tag: 'Loaded', name: m.name, email: m.email }),
    Failed: (_s, m) => ({ _tag: 'Failed', reason: m.error._tag }),
  },
  view: (s, i) => html`
    <button type="button" value="1" data-intent=${i.Load}>Load user 1</button>
    <p aria-live="polite">
      ${s._tag === 'Loaded' ? `${s.name} <${s.email}>` : s._tag === 'Failed' ? `Failed: ${s.reason}` : s._tag}
    </p>
  `,
});
```

`get(url, handlers)` builds a command for the `http` driver. The handlers are pure mappers:

- **`schema`** decodes the response with any Standard Schema, so `onSuccess` receives typed,
  validated data. A response that doesn't match becomes an `HttpDecodeError`.
- **`onSuccess`** turns the decoded body into a message.
- **`onFailure`** turns an error into a message. Errors are tagged data (`HttpStatusError`,
  `HttpNetworkError`, `HttpDecodeError`); nothing is ever thrown into the view. Leave it out and a
  failure goes to the [error channel](https://gyral.dev/docs/error-handling/).

The request and its answer sit next to each other in one reducer, typed end to end, with no
"response category" strings to match up.

## Concurrency lanes

What should happen when the user types again before the last search returned? Gyral answers it
with a policy, not with stream operators. Each command runs in a **lane** (`key`, by default the
driver's name), and the lane has a policy:

| Policy    | In one lane                               | Use for                      |
| --------- | ----------------------------------------- | ---------------------------- |
| `merge`   | run every command concurrently (default)  | independent writes, logging  |
| `switch`  | cancel the one in flight, run the new one | search as you type, debounce |
| `exhaust` | ignore new commands while one runs        | submit buttons, refresh      |
| `queue`   | run one at a time, in order               | ordered saves                |

```ts
// src/search.ts
import type { Command } from '@gyral/core';
import { get } from '@gyral/http';

/** A newer query cancels the request in flight, so results never arrive out of order. */
export const search = <M>(query: string, toMsg: (body: unknown) => M): Command<M> =>
  get(`/api/search?q=${encodeURIComponent(query)}`, {
    key: 'search',
    concurrency: 'switch',
    onSuccess: toMsg,
  });
```

A cancelled command's `AbortSignal` aborts (so `fetch` stops), and its result is never
delivered. When a component is removed from the page, all its commands are cancelled the same
way, one microtask later; moving it cancels nothing.

## Built-in drivers

| Package         | Commands                                                                              |
| --------------- | ------------------------------------------------------------------------------------- |
| `@gyral/http`   | `get(url, handlers)`, `request(req, handlers)`, `submitForm(url, formData, handlers)` |
| `@gyral/time`   | `delay(ms, msg)`, `debounce(ms, msg)`, `every(ms, toMsg)`                             |
| `@gyral/router` | `navigate(url)`, `setHead(head)`, `listen(toMsg)`                                     |

More commands are handled by the component itself rather than a driver: an output (from
`outputs<Out>()`) goes to the [parent](https://gyral.dev/docs/components/#child-components-and-outputs),
`send(store, msg)` writes to a [store](https://gyral.dev/docs/stores/), `focus(selector)` moves
[focus](https://gyral.dev/docs/views/#focus-is-a-command) after the next render, and `call(selector, method)`
[calls a method](https://gyral.dev/docs/views/#calling-a-method-on-an-element) on an element after it.

### Commands that answer nothing

`focus()`, `call()`, an output, `navigate()` and `setHead()` return `Command<never>`: they
produce no message. `never` fits any message type, so they go in any reducer's command list, and in a
helper typed `Command<Msg>`, with no type argument:

```ts
// src/after-save.ts
import { focus, type Command } from '@gyral/core';
import { navigate } from '@gyral/router';

export type Msg = { readonly _tag: 'Saved' } | { readonly _tag: 'Failed' };

/** After a save: back to the list, with focus on its heading. */
export const afterSave = (): readonly Command<Msg>[] => [navigate('/items'), focus('h1')];
```

Your own are the same with no handlers at all: `command(log, text)` is a `Command<never>`. A
failure still reaches the [error channel](https://gyral.dev/docs/error-handling/). With handlers, the message type
comes from what `onSuccess` and `onFailure` return, so explicit type arguments are rarely needed.

Debounce is a delay under `switch`: each keystroke's `debounce(300, msg)` cancels the pending
one. `delay` and `debounce` run on a delay-only driver, so an app that uses only them doesn't
bundle the code for `every`. Randomness is a command too, so models stay pure and tests can fix
the numbers: it's a six-line driver of your own (below).

## Writing a driver

A driver is a plain object with a `name` and a `run` function:

```ts
// src/clipboard.ts
import { command, defineDriver, type Command } from '@gyral/core';

/** Why a copy failed. */
export type CopyError = 'unavailable' | 'denied' | 'failed';

/** Writes text to the clipboard. */
export const clipboard = defineDriver<string, void, CopyError>({
  name: 'clipboard',
  run: (text) => navigator.clipboard.writeText(text),
  concurrency: 'switch',
  toError: (cause) =>
    cause instanceof TypeError
      ? 'unavailable'
      : cause instanceof DOMException && cause.name === 'NotAllowedError'
        ? 'denied'
        : 'failed',
});

export const copyText = <M>(text: string, copied: M, failed: (error: CopyError) => M): Command<M> =>
  command(clipboard, text, { onSuccess: () => copied, onFailure: failed });
```

- `run(input, { signal, emit })` returns the output or a promise of it. Abort work when `signal`
  aborts.
- `toError` turns whatever was thrown into the driver's typed error, which `onFailure` receives.
- `concurrency` is the default policy for the driver's commands; a command can override it.
- Retries aren't a driver option: wrap the driver where you choose it (next section).
- `defineDriver` only helps TypeScript infer the input, output and error types. Wrap the driver
  in typed command helpers like `copyText`, as the built-in packages do.

Nothing should run at import time: create resources when a command first runs, so modules are
safe to import on a server.

Randomness, for example:

```ts
// src/random.ts
import { command, defineDriver, type Command } from '@gyral/core';

const random = defineDriver<{ readonly min: number; readonly max: number }, number>({
  name: 'random',
  run: ({ min, max }) => min + Math.floor(Math.random() * (max - min + 1)),
});

/** A whole number from `min` to `max`; tests substitute the `random` driver to fix it. */
export const randomInt = <M>(min: number, max: number, toMsg: (n: number) => M): Command<M> =>
  command(random, { min, max }, { onSuccess: toMsg });
```

### Drivers the app provides

A driver with no implementation of its own, such as a connection your app opens, a session or a
service only the entry point can build, is a **token**: `defineDriver<I, O, E>('session')`.
Commands built from it are fully typed, and it runs whatever an ancestor provides under that
name. If nothing does, the command fails with an error naming the driver and the component, so
there is no placeholder to write and no import order to get right:

```ts
// src/session.ts
import { command, defineDriver, type Command } from '@gyral/core';

export interface Move {
  readonly from: string;
  readonly to: string;
}

/** Provided once by the app: provideDrivers(document.body, { session: makeSession(url) }). */
export const session = defineDriver<Move, { readonly accepted: boolean }, string>('session');

export const sendMove = <M>(move: Move, answered: (accepted: boolean) => M): Command<M> =>
  command(session, move, { onSuccess: (r) => answered(r.accepted) });
```

### Retries

`retry(driver, { times, delayMs?, backoff?, jitter?, retryIf? })` from `@gyral/core` returns the
same driver, under the same name, with failures tried again after the delay (`'fixed'` or
`'exponential'`). `jitter: true` waits a random time between 0 and that delay, so many clients
don't retry in step. `retryIf(error)` decides which failures to retry; it receives the
driver's typed error (its `toError`, else the thrown value), and by default every failure is
retried. A cancellation (the command switched away, the component removed) ends it at once and
is never retried. Wrap the driver where you choose it, at app setup, in an element's `drivers`
or in a test, and apps that never retry don't bundle the code.

For `@gyral/http`, `makeHttpDriver({ timeoutMs })` gives each attempt a deadline: a slower
attempt fails with `HttpTimeoutError` (`url`, `timeoutMs`), and the retry starts a fresh one.
`retryableHttpError` retries only what a second try can fix: network errors, timeouts, 408, 429
and 5xx. It doesn't read `Retry-After`.

```ts
// src/main.ts
import { provideDrivers, retry } from '@gyral/core';
import { makeHttpDriver, retryableHttpError } from '@gyral/http';

provideDrivers(document.body, {
  http: retry(makeHttpDriver({ baseUrl: '/api', timeoutMs: 8_000 }), {
    times: 2,
    delayMs: 300,
    backoff: 'exponential',
    jitter: true,
    retryIf: retryableHttpError,
  }),
});
```

`HttpError` is a union, so a `switch` that handles every case needs one for timeouts:

```ts
// src/errors.ts
import type { HttpError } from '@gyral/http';

export const describeError = (e: HttpError): string => {
  switch (e._tag) {
    case 'HttpStatusError':
      return `The server answered ${String(e.status)}.`;
    case 'HttpNetworkError':
      return 'You seem to be offline.';
    case 'HttpTimeoutError':
      return 'The server took too long to answer.';
    case 'HttpDecodeError':
      return 'The server sent something unexpected.';
  }
};
```

### Telling a refused request from no change

When a server (or a shared session) can refuse what the user asked for, don't infer the refusal
from a snapshot that didn't change: "same data" can mean refused, not yet processed, or a move
that changed nothing. Make the refusal a message of its own. A request with a reply maps the
refusal to its own variant through the command's `onFailure`; a feed that answers out of band
carries the request's id, so the component can tell its own refusal from someone else's update:

```ts
// src/moves.ts
import { command, defineDriver, type Command } from '@gyral/core';

interface Move {
  readonly id: string;
  readonly cell: number;
}
type Refusal = { readonly reason: string };

type Msg =
  | { readonly _tag: 'Accepted'; readonly id: string }
  | { readonly _tag: 'Refused'; readonly id: string; readonly reason: string };

/** The server answers 200 or a 409 with `{ reason }`; `toError` turns the 409 into a Refusal. */
const moves = defineDriver<Move, void, Refusal>({
  name: 'moves',
  run: async (move, { signal }) => {
    const res = await fetch('/api/moves', { method: 'POST', body: JSON.stringify(move), signal });
    if (!res.ok) throw (await res.json()) as Refusal;
  },
  toError: (cause) =>
    typeof cause === 'object' && cause !== null && 'reason' in cause
      ? { reason: String(cause.reason) }
      : { reason: 'unavailable' },
});

export const propose = (move: Move): Command<Msg> =>
  command(moves, move, {
    onSuccess: (): Msg => ({ _tag: 'Accepted', id: move.id }),
    onFailure: (refusal): Msg => ({ _tag: 'Refused', id: move.id, reason: refusal.reason }),
  });
```

The `Refused` reducer can then undo an optimistic change and show the reason. For form
submissions, `IntentRejected` is already this message ([Forms](https://gyral.dev/docs/forms/)).

### A copy button

With the driver above, a "Copy link" button is a message, a command and two answers:

```ts
// src/copy-link.ts
import { define, html, prop } from '@gyral/core';
import { copyText, type CopyError } from './clipboard.js';

export interface State {
  readonly status: 'idle' | 'copied' | CopyError;
}

export type Msg =
  | { readonly _tag: 'Copy' }
  | { readonly _tag: 'Copied' }
  | { readonly _tag: 'CopyFailed'; readonly error: CopyError };

const STATUS: Readonly<Record<State['status'], string>> = {
  idle: '',
  copied: 'Link copied.',
  unavailable: 'Copying needs a secure (https) page. Select the link and copy it instead.',
  denied: 'The browser blocked copying. Select the link and copy it instead.',
  failed: 'Copying failed. Select the link and copy it instead.',
};

export const CopyLink = define<State, Msg, { readonly url: string }>()('my-copy-link', {
  props: { url: prop.string({ required: true }) },
  init: () => ({ status: 'idle' }),
  intent: { Copy: () => ({ _tag: 'Copy' }) },
  update: {
    Copy: (s, _m, { props }) => [
      s,
      [copyText<Msg>(props.url, { _tag: 'Copied' }, (error) => ({ _tag: 'CopyFailed', error }))],
    ],
    Copied: () => ({ status: 'copied' }),
    CopyFailed: (_s, m) => ({ status: m.error }),
  },
  view: (s, i, { props }) => html`
    <label for="link">Link</label>
    <input id="link" readonly value=${props.url} />
    <button type="button" data-intent=${i.Copy}>Copy link</button>
    <p role="status">${STATUS[s.status]}</p>
  `,
});
```

- **`navigator.clipboard` exists only in a secure context**: https://, or localhost. Elsewhere
  reading `writeText` throws a `TypeError`, which `toError` turns into `unavailable`.
- **Browsers write only during a user activation.** Return the command from the reducer of the
  click's message, as above: with a synchronous parser, it starts while the click is still
  being handled. Started later, the browser rejects it with `NotAllowedError`, `denied` here.
- **Tests never touch the real clipboard**: they substitute the driver by name,
  `el.drivers = { clipboard: fakeDriver('clipboard') }` ([Testing](https://gyral.dev/docs/testing/#fake-drivers-and-commands)).

## Streaming results with emit

A driver can deliver more than one result: `emit(output)` sends a value through the command's
`onSuccess` while the command keeps running. Routers, timers, sockets and observers work this
way. A streaming `run` usually returns a promise that never resolves, and stops when `signal`
aborts:

```ts
// src/online.ts
import { command, defineDriver, type Command } from '@gyral/core';

/** Streams `navigator.onLine` now and on every change, until the component disconnects. */
export const online = defineDriver<void, boolean>({
  name: 'online',
  run: (_input, { signal, emit }) =>
    new Promise<boolean>(() => {
      const report = (): void => {
        emit(navigator.onLine);
      };
      report();
      window.addEventListener('online', report, { signal });
      window.addEventListener('offline', report, { signal });
    }),
});

export const watchOnline = <M>(toMsg: (online: boolean) => M): Command<M> =>
  command(online, undefined, { onSuccess: toMsg, concurrency: 'switch' });
```

List a stream in the component's [`subscriptions`](https://gyral.dev/docs/update/#subscriptions), and it runs
while the component is on the page. For a source Gyral doesn't own, such as signals, a Redux-style store or a socket, `subscription()` from `@gyral/core` writes
this plumbing for you: see [State Gyral doesn't own](https://gyral.dev/docs/outside-state/).

## Substituting drivers

Commands carry their driver, so most apps need no wiring. To substitute one, for a test fake
or a configured instance, Gyral looks drivers up **by name**, in this order:

1. the element's own `el.drivers`;
2. the nearest driver provider above it: a `<gyral-drivers>` element or
   `provideDrivers(element, drivers)`;
3. the driver object on the command.

For example, give every request on the page default headers, once, at the app's entry:

```ts
// src/entry-client.ts
import { provideDrivers } from '@gyral/core';
import { csrfFromMeta, makeHttpDriver } from '@gyral/http';

provideDrivers(document.body, { http: makeHttpDriver({ headers: csrfFromMeta('csrf-token') }) });
```

`csrfFromMeta` reads `<meta name="csrf-token">` when each request runs, so components never read
the DOM for it. The driver's headers are the one place a CSRF token from a `<meta>` is
configured. Development builds warn once when a
`POST`, `PUT`, `PATCH` or `DELETE` goes out without the token while the page has a CSRF
`<meta>`. [Testing](https://gyral.dev/docs/testing/) uses the same lookup to swap in fakes.

## On the server

Commands never run during a server render: there is no interpreter, no timer and no network.
Do async work in the route handler and pass results as props. After hydration, the browser
starts `init`'s commands and the component's subscriptions, so `listen()` begins exactly where
the server left off. See [Server rendering](https://gyral.dev/docs/server-rendering/).

---

# Error handling

> How Gyral reports each failure once, lets a parent catch a child's failure, shows a component's fallback and keeps a server-rendered page going.

Source: https://gyral.dev/docs/error-handling/

Code fails: a reducer reads a field that isn't there, a view meets data it didn't expect, a
driver's server is down. Gyral catches every failure in a component, wraps it in a
`GyralError` and sends it through **one channel**, so nothing escapes into the page as an
uncaught exception and nothing is only logged.

Expected failures are different: a request that can fail should say what its failure becomes.
Give its command an `onFailure` that maps the error to a message, and handle that message in
`update` like any other ([Effects and drivers](https://gyral.dev/docs/effects/)). The channel on this page is for
the failures you didn't plan for.

## One channel

A `GyralError` carries `component` (the host's tag), `phase` (where it failed), `msg` (the
message tag, intent name or driver) and `cause` (what was thrown). In order:

1. **Devtools** shows an `error` row in the timeline (development).
2. **A parent can catch it.** A bubbling, composed, cancelable `ErrorEvent('error')` is
   dispatched on the failing component. An ancestor that listens for it is a **boundary**; it
   claims the failure with `preventDefault()`.
3. **The component's own fallback runs.** Its `error(failure, state)` view renders when `init`
   or the view threw; its optional `Errored` reducer receives failed updates, parsers and
   commands.
4. **Unless a parent claimed it, it is reported** with
   [`reportError()`](https://developer.mozilla.org/docs/Web/API/reportError): `window`'s `error`
   event and your monitoring see it, once.

| Phase       | What threw                                                                 | What happens                                                                |
| ----------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `init`      | `init`                                                                     | No state: `error(failure, undefined)` renders, or the component stays empty |
| `update`    | a reducer                                                                  | Nothing changes: the state is kept and its commands don't run; `Errored`    |
| `view`      | the view                                                                   | `error(failure, state)` renders, or the previous DOM stays                  |
| `parse`     | an intent parser (throws or rejects)                                       | No message; `Errored`                                                       |
| `command`   | an `onSuccess`/`onFailure` mapper, or a driver failure without `onFailure` | No message; `Errored`                                                       |
| `hook`      | an element hook                                                            | Reported; the other hooks of that render still run                          |
| `store`     | a store reducer or a subscriber                                            | The store is unchanged / the other subscribers are still notified           |
| `subscribe` | a subscription's unsubscribe                                               | Reported; the command still stops                                           |

`el.send()` never throws to its caller, and a failure inside `error` or `Errored` is reported
once, never looped. `Errored` is a framework message name, like `PropsChanged`.

## A component's own fallback

`error(failure, state)` renders instead of the view when `init` (then `state` is `undefined`)
or the view throws. `Errored` lets the component switch to an error state, or reset:

```ts
// src/order-list.ts
import { command, define, defineDriver, html, type GyralError } from '@gyral/core';

interface Order {
  readonly id: string;
  readonly total: number;
}
type State =
  | { readonly _tag: 'Ready'; readonly orders: readonly Order[] }
  | { readonly _tag: 'Broken'; readonly reason: string };
type Msg =
  { readonly _tag: 'Refresh' } | { readonly _tag: 'Loaded'; readonly orders: readonly Order[] };

const orders = defineDriver<undefined, readonly Order[]>({
  name: 'orders',
  run: async (_input, { signal }) => {
    const response = await fetch('/api/orders', { signal });
    return (await response.json()) as readonly Order[];
  },
});
const refresh = () =>
  command(orders, undefined, { onSuccess: (list): Msg => ({ _tag: 'Loaded', orders: list }) });

export const OrderList = define<State, Msg>()('order-list', {
  init: () => [{ _tag: 'Ready', orders: [] }, [refresh()]],
  intent: { Refresh: () => ({ _tag: 'Refresh' }) },
  update: {
    Refresh: (s) => [s, [refresh()]],
    Loaded: (_s, m) => ({ _tag: 'Ready', orders: m.orders }),
    // Any failed update, parse or command of this component. The driver failing lands here
    // too, because this command has no onFailure.
    Errored: (_s, m) => ({ _tag: 'Broken', reason: m.error.phase }),
  },
  view: (s, i) =>
    s._tag === 'Broken'
      ? html`<p role="alert">Orders are unavailable (${s.reason}).</p>
          <button type="button" data-intent=${i.Refresh}>Try again</button>`
      : html`<ul>
          ${s.orders.map((o) => html`<li>${o.id}: ${o.total}</li>`)}
        </ul>`,
  error: (failure: GyralError) =>
    html`<p role="alert">Orders failed to show (${failure.phase}).</p>`,
});
```

## A parent boundary

A parent catches a child's failure with the intents it already has: listen for `error` on the
child, read the `GyralError` from the event, and call `preventDefault()` to claim it. A claimed
failure isn't reported, so report it yourself if you still want it in your telemetry. To retry,
re-mount the child (render it in a different template, or give it a new key in `each()`): its
`init` runs again.

```ts
// src/dashboard.ts
import { define, html, type GyralError } from '@gyral/core';

interface State {
  readonly attempt: number;
  readonly failed: boolean;
}
type Msg = { readonly _tag: 'WidgetFailed' } | { readonly _tag: 'Retry' };

export const Dashboard = define<State, Msg>()('my-dashboard', {
  init: () => ({ attempt: 0, failed: false }),
  intent: {
    WidgetFailed: ({ event }) => {
      const failure = (event as ErrorEvent).error as GyralError;
      event.preventDefault(); // claimed: this boundary handles it, the page doesn't
      console.info('the chart failed in', failure.phase);
      return { _tag: 'WidgetFailed' };
    },
    Retry: () => ({ _tag: 'Retry' }),
  },
  update: {
    WidgetFailed: (s) => ({ ...s, failed: true }),
    Retry: (s) => ({ attempt: s.attempt + 1, failed: false }),
  },
  view: (s, i) =>
    s.failed
      ? html`<p role="alert">The chart is unavailable.</p>
          <button type="button" data-intent=${i.Retry}>Retry</button>`
      : s.attempt % 2 === 0
        ? html`<div>
            <sales-chart data-intent=${i.WidgetFailed} data-intent-on="error"></sales-chart>
          </div>`
        : html`<p>
            <sales-chart data-intent=${i.WidgetFailed} data-intent-on="error"></sales-chart>
          </p>`,
});
```

The event stops at the document, so `window` hears an unclaimed failure only once, through
`reportError`.

## Monitoring

Every unclaimed failure reaches `window` once. Listen there; `event.error` is the `GyralError`:

```ts
// src/telemetry.ts
import { GyralError } from '@gyral/core';

window.addEventListener('error', (event) => {
  if (!(event.error instanceof GyralError)) return;
  const { component, phase, msg, cause } = event.error;
  navigator.sendBeacon(
    '/telemetry',
    JSON.stringify({ component, phase, msg, cause: String(cause) }),
  );
});
```

Production builds report the same errors with short messages; the codes are explained on the
[error codes](https://gyral.dev/errors/) page. For your own tooling, the same table (code, group, message,
arguments, link) ships with the package as `@gyral/core/errors.json`:

```ts
import table from '@gyral/core/errors.json' with { type: 'json' };
```

## On the server

A component whose `init` or view throws during [server rendering](https://gyral.dev/docs/server-rendering/)
renders its `error` view (or nothing), marked `data-gyral-error` and without a seed. The rest of
the page renders, and the browser starts that component fresh. `renderPage`'s `onError` hears
each failure (default `console.error`). With `onError: 'throw'`, `renderPage` renders the page
to a string first and throws before any byte is sent, so the route can answer with its error
page:

```ts
// src/server/orders-page.ts
import { html, type GyralError } from '@gyral/core';
import { renderPage } from '@gyral/ssr';

declare const report: (error: GyralError) => void;
const body = html`<order-list></order-list>`;

// One failing component shouldn't take the page down: it shows its fallback.
export const ordersPage = (): Response =>
  renderPage({ title: 'Orders', body, onError: (error) => report(error) });

// This page is all or nothing: answer 500 with an error page instead.
export function checkoutPage(): Response {
  try {
    return renderPage({ title: 'Checkout', body, onError: 'throw' });
  } catch {
    return new Response('Something went wrong', { status: 500 });
  }
}
```

Data loading happens before `renderPage`, so the route handler already owns the error page for
its own failures.

## In tests

`reportError` counts as an uncaught error, and Vitest fails a test run on one. That's what you
want for failures you didn't plan. When a test makes a component fail on purpose, collect the
failures with `collectErrors()` from `@gyral/testing` and assert on them:

```ts
// src/order-list.browser.test.ts
import { settled } from '@gyral/core';
import { collectErrors, fakeDriver } from '@gyral/testing';
import { afterEach, expect, it } from 'vitest';
import { OrderList } from './order-list.js';

let collected: ReturnType<typeof collectErrors> | undefined;
afterEach(() => collected?.stop());

it('shows the error state when the orders fail to load', async () => {
  collected = collectErrors();
  const el = new OrderList();
  el.drivers = {
    orders: fakeDriver('orders', () => {
      throw new Error('down');
    }),
  };
  document.body.append(el);
  await settled();
  expect(collected.errors.map((e) => e.phase)).toEqual(['command']);
  expect(el.shadowRoot?.textContent).toContain('unavailable');
});
```

In a model test, `step()` accepts `Errored`, so you can test that reducer without a DOM.

## Debugging a failure

Start with the production diagnostic code, for example `Gyral G0010`. The
[diagnostics reference](https://gyral.dev/errors/) expands it into the cause and a suggested fix. A development
build includes the explanation; the [devtools panel](https://gyral.dev/docs/devtools/) shows the message,
previous/next state, component and command lane around the failure. Inspect the underlying
`GyralError.cause` without putting private user data into shared logs.

Distinguish three outcomes:

- A parser returning `undefined` ignores an event; no message reaches the reducer.
- A schema failure in `form()` or `field()` produces `IntentRejected`, which belongs in your
  validation UI. It is expected invalid input, not a thrown defect.
- A parser, reducer, view, hook or command mapper throwing uses the error channel described
  above. A planned driver failure with `onFailure` instead becomes its typed message.

On the server, `onError(error)` observes component failures. Without a throwing policy, a
failed component can render its fallback while the page continues. `onError: 'throw'` makes
the render fail before returning the response; chunked output cannot change an HTTP status
after bytes have been sent. See [Server rendering](https://gyral.dev/docs/server-rendering/).

For a hydration mismatch, reproduce with the production build and the exact server/client
assets. Check stale HTML, unseeded current time, locale differences, invalid parser-repaired
markup, and third-party changes before scripts arrive. Use `mountSsr()` and `hydrated()` to
exercise real server markup; they report mounting/hydration problems. Keep a small failing
test before changing the implementation. See [Testing](https://gyral.dev/docs/testing/),
[Security](https://gyral.dev/docs/security/) and [Versioning](https://gyral.dev/docs/versioning/).

---

# Browser storage

> Typed localStorage and IndexedDB drivers: persist values, watch settings, query records and run atomic transactions.

Source: https://gyral.dev/docs/browser-storage/

Storage is a driver effect. Keep reads/writes out of reducers, init and views. The optional
`@gyral/core/storage` entry adds no storage code to apps that do not import it. Factories and
imports are safe on the server; browser access starts only when commands run.

## localStorage

```ts
// src/theme-storage.ts
import { command, define, html } from '@gyral/core';
import { makeLocalStorageDriver, type StorageError, type StorageOutput } from '@gyral/core/storage';
import * as v from 'valibot';

const settings = makeLocalStorageDriver(v.object({ theme: v.string() }), { prefix: 'app:' });
interface State {
  readonly theme: string;
  readonly error?: StorageError;
}
type Msg =
  | { readonly _tag: 'Stored'; readonly result: StorageOutput<{ theme: string }> }
  | { readonly _tag: 'Failed'; readonly error: StorageError }
  | { readonly _tag: 'Dark' };

export const Theme = define<State, Msg>()('my-storage-theme', {
  init: () => ({ theme: 'light' }),
  subscriptions: () => [
    command(
      settings,
      { _tag: 'Watch', key: 'settings' },
      {
        key: 'settings-watch',
        onSuccess: (result) => ({ _tag: 'Stored', result }),
        onFailure: (error) => ({ _tag: 'Failed', error }),
      },
    ),
  ],
  intent: { Dark: true },
  update: {
    Stored: (s, m) =>
      m.result._tag === 'StorageChanged' && m.result.entry.found
        ? { theme: m.result.entry.value.theme }
        : s,
    Failed: (s, m) => ({ ...s, error: m.error }),
    Dark: (s) => [
      s,
      [
        command(
          settings,
          {
            _tag: 'Write',
            key: 'settings',
            value: { theme: 'dark' },
          },
          { key: 'settings-write', onFailure: (error) => ({ _tag: 'Failed', error }) },
        ),
      ],
    ],
  },
  view: (s, i) =>
    html`<p>${s.theme}</p>
      <button type="button" data-intent=${i.Dark}>Dark theme</button>`,
});
```

`Read { key }` returns `StorageValue` with `entry: { found: false }` or
`{ found: true, value }`. `Write { key, value }`, `Remove { key }` and `Clear` return
completion tags. Clear removes only the configured prefix (default empty: all localStorage).
Watch emits an initial snapshot, then changes from driver writes (`source: 'driver'`) and
native events in other tabs (`'tab'`). Direct same-tab localStorage writes are not observed.
Removal/clear emit absence. A malformed Watch value emits `StorageDecodeFailed` and leaves
the watch running; Read rejects with `StorageDecodeError`. Access/quota/security failures
go through `StorageAccessError` and command `onFailure`. Handle both watch output variants.

The Standard Schema decodes parsed JSON, including async validation. If it transforms the
input, configure `encode(value)` to reconstruct its JSON input shape. No transactions or
cross-tab atomicity are promised. Use distinct command keys for watches and writes. Abort
removes listeners and suppresses late decoder results. Tests use `fakeDriver(settings)`
with `el.drivers = { localStorage: fake }`, or an isolated `storage: () => storageObject`.

Initial watches belong in `subscriptions`: the server's seed hydrates first, then browser
storage updates the model. Keep server-rendered state JSON-compatible.

## IndexedDB

Use the separate `@gyral/core/indexeddb` entry for structured records, object stores,
indexes, migrations and atomic transaction batches. It uses the same command and fake-driver
conventions, with native IndexedDB semantics:

```ts
// src/contacts-storage.ts
import { command, type Command } from '@gyral/core';
import {
  makeIndexedDBDriver,
  type IndexedDBError,
  type IndexedDBOutput,
} from '@gyral/core/indexeddb';
import * as v from 'valibot';

const stores = { contacts: v.object({ id: v.string(), name: v.string() }) };
type Contact = v.InferOutput<typeof stores.contacts>;
const contacts = makeIndexedDBDriver(stores, {
  database: 'address-book',
  version: 1,
  upgrade: (db, oldVersion) => {
    if (oldVersion < 1) {
      const store = db.createObjectStore('contacts', { keyPath: 'id' });
      store.createIndex('name', 'name');
    }
  },
});
type Msg =
  | { readonly _tag: 'Database'; readonly result: IndexedDBOutput<typeof stores> }
  | { readonly _tag: 'Failed'; readonly error: IndexedDBError };
const handlers = {
  onSuccess: (result: IndexedDBOutput<typeof stores>): Msg => ({ _tag: 'Database', result }),
  onFailure: (error: IndexedDBError): Msg => ({ _tag: 'Failed', error }),
};
export const readContact = (id: string): Command<Msg> =>
  command(contacts, { _tag: 'Read', store: 'contacts', key: id }, handlers);
export const saveContacts = (values: readonly Contact[]): Command<Msg> =>
  command(
    contacts,
    {
      _tag: 'Transaction',
      operations: values.map(
        (value) =>
          ({
            _tag: 'Put',
            store: 'contacts',
            value,
          }) as const,
      ),
    },
    { ...handlers, concurrency: 'queue' },
  );
export const findContacts = (name: string): Command<Msg> =>
  command(
    contacts,
    {
      _tag: 'Query',
      store: 'contacts',
      index: 'name',
      range: { _tag: 'Only', key: name },
      limit: 20,
    },
    handlers,
  );
```

`Read` returns `Record` with a found/absent entry. `Put` returns its actual primary key
(optional input key, or the store's inline/auto-increment key); `Delete` returns `Deleted`.
`Query` returns `Records` with primary keys and decoded values. Queries require a positive
integer limit, allow `direction` (`next`, `prev`, `nextunique`, `prevunique`), and optional
range data: Only/Lower/Upper with `key`, or Bound with `lower`/`upper`. Bounds accept `open`,
`lowerOpen` and `upperOpen` as appropriate. Store names/record values are typed; index names
are strings defined by the application migration and checked by the browser.

A nonempty Transaction batch queues all requests synchronously across its stores and
returns `Committed { results }` in operation order after the native transaction completes.
Read-only batches use readonly transactions; batches containing Put/Delete use readwrite.
A failure aborts the whole batch. Stored Read/Query values decode after commit, including
async schemas; a decode failure carries `committed: true`, so earlier batch writes remain.
An optional `encode(store, value)` reconstructs a transforming schema's stored input shape.

The version and synchronous `upgrade(db, oldVersion, newVersion, transaction)` callback
belong to the application. Queue migration requests before returning; never await. A blocked
upgrade rejects with `IndexedDBBlockedError`, aborts any abandoned late upgrade and closes
any late connection. Retry explicitly once older connections close. Migration/access/native
transaction failures use `IndexedDBAccessError`; invalid query limits/empty batches use
`IndexedDBInputError`; invalid persisted records use `IndexedDBDecodeError`.

Abort attempts rollback and suppresses late output; it cannot undo an already committed
transaction. Connections close after each native transaction, before async decoding, and
on versionchange. No resources open on import/factory creation. Start browser reads after
the first render (init commands or subscriptions), and keep SSR model state JSON-compatible.
Tests substitute `fakeDriver(contacts)` by name (`indexeddb` by default). No storage watches
or automatic cross-tab synchronization are promised for this driver.

---

# Network streams

> Native EventSource and WebSocket drivers: receive validated streams, send messages and handle connection lifecycles.

Source: https://gyral.dev/docs/network-streams/

Optional `@gyral/http/sse` and `@gyral/http/websocket` entries use browser-native transports.
They are separate from the fetch entry, add no runtime dependencies, and open no resources
on import or factory creation. Use normal commands, declarative subscriptions and fake
substitution by driver name. Feeds start after the first render, preserving SSR seeds.

## Server-sent events

```ts
// src/server-count.ts
import { command, define, html } from '@gyral/core';
import {
  makeEventSourceDriver,
  type EventSourceError,
  type EventSourceOutput,
} from '@gyral/http/sse';
import * as v from 'valibot';

const schema = v.object({ count: v.number() });
const feed = makeEventSourceDriver(schema, { events: ['count'], withCredentials: false });
type Msg =
  | { readonly _tag: 'Feed'; readonly value: EventSourceOutput<v.InferOutput<typeof schema>> }
  | { readonly _tag: 'Failed'; readonly error: EventSourceError };
interface State {
  readonly count: number;
  readonly status: string;
}
export const Counter = define<State, Msg>()('my-server-count', {
  init: () => ({ count: 0, status: 'connecting' }),
  subscriptions: () => [
    command(
      feed,
      { url: '/events' },
      {
        onSuccess: (value) => ({ _tag: 'Feed', value }),
        onFailure: (error) => ({ _tag: 'Failed', error }),
      },
    ),
  ],
  update: {
    Feed: (s, m) => {
      switch (m.value._tag) {
        case 'EventSourceMessage':
          return { ...s, count: m.value.data.count };
        case 'EventSourceState':
          return { ...s, status: m.value.state };
        case 'EventSourceDecodeFailed':
          return { ...s, status: 'invalid event' };
      }
    },
    Failed: (s) => ({ ...s, status: 'closed' }),
  },
  view: (s) =>
    html`<output>${s.count}</output>
      <p role="status">${s.status}</p>`,
});
```

The driver always observes `message` and adds configured named events (no wildcard native
listener). `EventSourceMessage` preserves `eventType` and `lastEventId`; empty IDs are valid.
Default parsing is JSON followed by Standard Schema validation. Use `parse(text)` for another
text format. Async decoders preserve arrival order. Bad JSON/schema data emits
`EventSourceDecodeFailed { issues, eventType, lastEventId }` without ending the connection.

Native EventSource owns GET requests, cookie credentials, reconnection, server `retry:`
timing and Last-Event-ID. `withCredentials` configures cross-origin credentials; same-origin
cookies follow native behavior. CONNECTING errors report connecting state and keep the same
source. Terminal CLOSED errors report closed state and reject with `EventSourceError` through
`onFailure`; detailed HTTP status/body are unavailable. The driver adds no second retry loop.
Abort removes listeners, closes the source and suppresses pending decoded results.

Headers, POST streams and fetch-based transports are outside this driver. Event IDs do not
guarantee exactly-once delivery or replay; handle deduplication/resynchronization in your
protocol. Tests use `fakeDriver(feed)` with `el.drivers = { sse: fake }` (or the configured
name) and `fake.emitNext(...)` to deliver events/states.

## WebSocket

```ts
// src/native-chat.ts
import { command, define, html, retry } from '@gyral/core';
import {
  makeWebSocketDriver,
  type WebSocketError,
  type WebSocketOutput,
} from '@gyral/http/websocket';
import * as v from 'valibot';

const schema = v.object({ text: v.string() });
const raw = makeWebSocketDriver(schema, {
  encode: (value: { text: string }) => JSON.stringify(value),
});
const socket = retry(raw, {
  times: 3,
  delayMs: 500,
  backoff: 'exponential',
  jitter: true,
  retryIf: (error) => error._tag === 'WebSocketClosedError' && error.code === 1006,
});
interface State {
  readonly live: boolean;
  readonly text: string;
  readonly status: string;
}
type Msg =
  | { readonly _tag: 'Socket'; readonly value: WebSocketOutput<v.InferOutput<typeof schema>> }
  | { readonly _tag: 'Failed'; readonly error: WebSocketError }
  | { readonly _tag: 'Send'; readonly text: string }
  | { readonly _tag: 'Stop' };
const handlers = {
  onSuccess: (value: WebSocketOutput<v.InferOutput<typeof schema>>): Msg => ({
    _tag: 'Socket',
    value,
  }),
  onFailure: (error: WebSocketError): Msg => ({ _tag: 'Failed', error }),
};
export const Chat = define<State, Msg>()('my-native-chat', {
  init: () => ({ live: true, text: '', status: 'connecting' }),
  subscriptions: (s) =>
    s.live
      ? [
          command(
            socket,
            {
              _tag: 'Connect',
              connection: 'room',
              url: 'wss://example.test/chat',
            },
            { ...handlers, key: 'room-connect' },
          ),
        ]
      : [],
  intent: { Send: ({ value }) => ({ _tag: 'Send', text: value ?? '' }), Stop: true },
  update: {
    Send: (s, m) => [
      s,
      [
        command(
          socket,
          {
            _tag: 'Send',
            connection: 'room',
            value: { text: m.text },
          },
          { ...handlers, key: 'room-send' },
        ),
      ],
    ],
    Stop: (s) => [
      s,
      [
        command(
          socket,
          {
            _tag: 'Close',
            connection: 'room',
            code: 1000,
          },
          { ...handlers, key: 'room-close' },
        ),
      ],
    ],
    Failed: (s, m) => ({ ...s, live: false, status: m.error._tag }),
    Socket: (s, m) => {
      switch (m.value._tag) {
        case 'WebSocketMessage':
          return { ...s, text: m.value.data.text };
        case 'WebSocketState':
          return { ...s, status: m.value.state };
        case 'WebSocketDecodeFailed':
          return { ...s, status: 'invalid message' };
        case 'WebSocketClosed':
          return m.value.requested || (m.value.code === 1000 && m.value.wasClean)
            ? { ...s, live: false, status: 'closed' }
            : { ...s, status: 'reconnecting' };
        case 'WebSocketSent':
          return s; // enqueued, awaiting application acknowledgement
        case 'WebSocketCloseRequested':
          return s;
      }
    },
  },
  view: (s, i) =>
    html`<p>${s.text}</p>
      <p role="status">${s.status}</p>
      <button type="button" value="Hello" data-intent=${i.Send}>Send hello</button>
      <button type="button" data-intent=${i.Stop}>Close connection</button>`,
});
```

Each factory owns sockets by explicit connection ID. Only one active Connect owns an ID;
duplicates reject. Send/Close use the same socket; another factory has separate ownership.
Choose unique IDs when providing one driver to multiple components and distinct command keys
for Connect, Send and Close. A shared connection should have one subscribing owner; fan its
messages out through application state instead of issuing duplicate Connect commands.

Default incoming parse is JSON text followed by Standard Schema; binary messages are
ArrayBuffers (`binaryType: 'arraybuffer'`). Set synchronous `parse(payload)` for binary/other
text formats. Async schemas preserve message order. Malformed payloads emit
`WebSocketDecodeFailed` without ending the connection. Required `encode(value)` returns a
native string, Blob, ArrayBuffer or ArrayBufferView. Server-rendered model state stays JSON;
binary protocol values belong at the driver boundary or in client-only state.

The outgoing limit defaults to 65,536 bytes. `maxBufferedBytes` must be a nonnegative safe
integer (invalid configuration throws before resources open). Send requires an owned OPEN
socket and native bufferedAmount plus encoded bytes within the limit (UTF-8 for strings).
Failure uses `WebSocketSendError` with reason not-open/buffer-limit/encode/send. A successful
`WebSocketSent` means browser enqueue, not server processing or acknowledgement. No offline
queue or automatic resend exists. Native WebSocket has no inbound backpressure; the outgoing
limit does not bound incoming load.

Clean normal code 1000 closure resolves Connect with `WebSocketClosed`; an explicit Close
(default code 1000) also completes, including application close codes. `requested: true`
identifies that explicit request. Other closures emit `WebSocketClosed`, then reject with
`WebSocketClosedError` retaining code/reason/wasClean and `errored` (native error occurred).
Constructor/duplicate-ID errors use `WebSocketConnectError`; invalid Close requests use
`WebSocketCloseError`. Native errors expose no HTTP details.

Reconnection is opt-in through `retry`. Choose backoff/jitter and a retryIf predicate that
accepts your recoverable connection failures and excludes Send errors. Do not drop the
Connect subscription merely because an abnormal attempt emitted Closed: that aborts the
retry wrapper too. Drop it on requested/normal completion or final onFailure. An ended
subscription stays ended until its lane/input is removed and re-added/changed. Abort never
retries; cleanup removes listeners, releases ownership, closes the socket and suppresses
late events/decoders. Application acknowledgements and resynchronization are protocol data.
Tests use `fakeDriver(raw)` by name (`websocket` by default) for both streams and sends.

---

# Shared state

> Share state between distant components with stores, read like props from the side and written with messages, on the client and per request on the server.

Source: https://gyral.dev/docs/stores/

Props carry state down and outputs carry it up, which covers parents and children. Two
components far apart, like a cart badge in the header and a checkout page, need something else.
That's a **store**: Model-View-Intent without the view. Components read it like props ("props
from the side") and write to it with messages.

## When to use a store

Reach for a store when distant components need the same data and threading it through every
level in between would couple unrelated components. Keep everything else in component state:
a store is shared and global to its scope, so it's harder to reason about than a component's own
model. If the state already lives outside Gyral, in signals, Redux or a socket, keep it there
and read it with a subscription: see [State Gyral doesn't own](https://gyral.dev/docs/outside-state/).

## Defining a store

```ts
// src/cart.ts
import { defineStore } from '@gyral/core';

export interface Line {
  readonly sku: string;
  readonly name: string;
  readonly qty: number;
}

export interface Cart {
  readonly lines: readonly Line[];
}

export type CartMsg =
  | { readonly _tag: 'Add'; readonly sku: string; readonly name: string }
  | { readonly _tag: 'Remove'; readonly sku: string };

export const count = (cart: Cart): number => cart.lines.reduce((n, l) => n + l.qty, 0);

export const cart = defineStore<Cart, CartMsg>('cart', {
  init: () => ({ lines: [] }),
  update: {
    Add: (s, m) =>
      s.lines.some((l) => l.sku === m.sku)
        ? { lines: s.lines.map((l) => (l.sku === m.sku ? { ...l, qty: l.qty + 1 } : l)) }
        : { lines: [...s.lines, { sku: m.sku, name: m.name, qty: 1 }] },
    Remove: (s, m) => ({ lines: s.lines.filter((l) => l.sku !== m.sku) }),
  },
});
```

A store has a unique name, an `init` and pure reducers. Like a component's, its reducers may
return commands, run by the store's own interpreter: persisting the cart to storage, or syncing
it with a server, is a driver the store's `update` uses.

## Reading and sending

```ts
// src/cart-badge.ts
import { changed, define, html, send } from '@gyral/core';
import { cart, count } from './cart.js';

export interface State {
  readonly bumps: number;
}

export type Msg = { readonly _tag: 'Clear' };

export const CartBadge = define<State, Msg>()('my-cart-badge', {
  stores: [cart],
  init: () => ({ bumps: 0 }),
  intent: { Clear: () => ({ _tag: 'Clear' }) },
  update: {
    // Writes are commands, like any other effect.
    Clear: (s, _m, { read }) => [
      s,
      read(cart).lines.map((l) => send(cart, { _tag: 'Remove', sku: l.sku })),
    ],
    // Optional: react to a change in the store.
    StoreChanged: (s, m) => (changed(cart, m) === undefined ? s : { bumps: s.bumps + 1 }),
  },
  states: (s) => ({ bumped: s.bumps % 2 === 1 }),
  view: (_s, i, { read }) => html`
    <a href="/cart">Cart <output aria-live="polite">${count(read(cart))}</output></a>
    <button type="button" data-intent=${i.Clear}>Empty cart</button>
  `,
});
```

- **Declare** the stores a component reads in `stores`. A change to one re-renders the component.
- **Read** with `read(cart)` from the context, in the view and in every reducer. It's typed by
  the store. Reading a store you didn't declare throws an error that names the fix.
- **Write** with `send(cart, msg)`, a command. The store's reducer does the change, so every
  change to shared state is still a message you can see in tests and devtools.
- **React** with the optional `StoreChanged` reducer. `changed(cart, m)` narrows the message to
  that store's new and previous state, or `undefined` when another store changed.

A store's reducer can `send` to another store in the same scope, too.

## Where the instance lives

`defineStore` describes a store; an **instance** holds its state. Which instance a component
gets depends on where it is:

1. `el.stores[name]`, a per-element override (tests, islands);
2. the nearest `<gyral-stores>` element above it, through shadow roots;
3. the page's default instance.

Each page has one cart by default. Wrap a part of the page in `<gyral-stores>` to give it its
own instances, for example an embedded widget that must not share the page's cart.

## Stores on the server

On the server, every request needs its own instance, or one visitor's cart would show up in
another's page. Pass them to the render:

```ts
// server/cart-page.ts
import { html } from '@gyral/core';
import { renderPage } from '@gyral/ssr';
import { cart, type Cart } from '../src/cart.js';

/** Renders the cart page from this visitor's saved cart. */
export const cartPage = (saved: Cart): Response =>
  renderPage({
    title: 'Your cart',
    stores: [cart.instance(saved)],
    body: html`<header><my-cart-badge></my-cart-badge></header>`,
    scripts: ['/src/entry-client.ts'],
  });
```

- Components read the request's instance synchronously while they render. Gyral keeps one
  registry per render, even across the chunks of a response, without `AsyncLocalStorage`, so it works on
  any runtime.
- `renderPage()` writes every store's state once into the document as
  `<script type="application/json" data-gyral-stores>`, escaped for scripts. The browser
  restores it before any component hydrates, so the first client render matches the server's.
- Give `defineStore` a `schema` to check that seed in the browser: an invalid seed is reported
  with every issue path, and the store starts from `init` instead.

## Testing stores

A store's reducers are pure, so `stepStore(store, state, msg)` from `@gyral/testing` runs one
without an instance. `store.instance(initial)` gives a test its own instance, and
`inputsFor(commands, store)` lists the messages a component's reducer sent to a store. See
[Testing](https://gyral.dev/docs/testing/).

---

# State Gyral doesn't own

> Read signals, Redux-style stores, XState actors and WebSocket feeds with subscription(), write to them with plain drivers, and test both.

Source: https://gyral.dev/docs/outside-state/

Sometimes the source of truth lives outside Gyral: a TC39 signals store, a Redux or Zustand
store, an XState actor, a WebSocket feed. Components reach it the way they reach any other
effect, through drivers. **Reading is a subscription**, a streaming driver the component lists
in its `subscriptions`; **writing is a plain command** whose driver calls the source. State that only
Gyral components use belongs in a [store](https://gyral.dev/docs/stores/) instead.

```ts
// src/outside-counter.ts
import { command, define, defineDriver, html, subscription, type Command } from '@gyral/core';

/** What a Redux-style store offers (Redux's own Store type fits as is). */
interface CounterStore {
  getState(): number;
  subscribe(listener: () => void): () => void;
  dispatch(action: { readonly type: 'added'; readonly by: number }): void;
}
declare const counterStore: CounterStore;

/** Reading: the current value now, then every change, until the component goes away. */
const counter = subscription<number>('counter', (emit) => {
  emit(counterStore.getState());
  return counterStore.subscribe(() => {
    emit(counterStore.getState());
  });
});

/** Writing: a plain driver. The change comes back through the subscription. */
const addToCounter = defineDriver<number, void>({
  name: 'counter-add',
  run: (by) => {
    counterStore.dispatch({ type: 'added', by });
  },
});

type Msg = { readonly _tag: 'Counted'; readonly n: number } | { readonly _tag: 'Add' };

const watchCounter = (): Command<Msg> =>
  command(counter, undefined, { onSuccess: (n): Msg => ({ _tag: 'Counted', n }) });

export const OutsideCounter = define<{ readonly n: number }, Msg>()('my-outside-counter', {
  init: () => ({ n: 0 }),
  // Running while the component is on the page; released when it's removed.
  subscriptions: () => [watchCounter()],
  intent: { Add: true },
  update: {
    Counted: (_s, m) => ({ n: m.n }),
    // A write answers nothing: the new value comes back through the subscription.
    Add: (s) => [s, [command(addToCounter, 1)]],
  },
  view: (s, i) => html`
    <p>Count: <output>${s.n}</output></p>
    <button type="button" data-intent=${i.Add}>Add one</button>
  `,
});
```

## subscription()

`subscription(name, subscribe, options?)` from `@gyral/core` builds a
[streaming driver](https://gyral.dev/docs/effects/#streaming-results-with-emit) for a source Gyral doesn't own:

- **`subscribe(emit, { input, signal, fail })`** starts listening, may `emit` the current value
  at once, and returns how to stop: a function, or an object with `unsubscribe()` (RxJS,
  XState's `actor.subscribe(…)`).
- **Each value goes through the command's `onSuccess`**, like any streaming driver's.
- **The source is released for you**, once, when the command is switched away, when the
  component is removed from the page, and after `fail(error)`. Values emitted after that are
  ignored. Moving the component doesn't release it (see
  [Moves and reconnects](#moves-and-reconnects)).
- **List it in `subscriptions(state, props)`**: Gyral starts it, restarts it when its input
  changes, and stops it when the list no longer has it ([Subscriptions](https://gyral.dev/docs/update/#subscriptions)).
  Give each input its own `key` when one component keeps several, such as one per chat room.
- **`fail(error)` ends it with an error.** `onFailure` gets it (through the driver's `toError`
  if given), after any retries: wrap the subscription in `retry(…)`, which subscribes again, for a socket
  that reconnects. A
  `subscribe` that throws fails the same way.
- **Writes are plain commands**, like `addToCounter` above. The change comes back through the
  subscription, not through the write's `onSuccess`.

For many values per frame (market data, sensors) into a view that takes real work to render,
list the message in the component's `renderOnFrame`, so it renders once per animation frame.

## Moves and reconnects

Keyed-list libraries and plain DOM code move an element by removing it and inserting it again
(`appendChild`, `insertBefore`) in the same task. Gyral treats that as a move, so a component's
subscriptions, timers and requests keep running:

- **A move** (removed and inserted again in one task, including before the first render):
  nothing stops.
- **A real removal**: one microtask after the element leaves the page, its commands stop and
  every subscription is released.
- **Attached again after a real removal**: `subscriptions(state, props)` runs again, so
  everything it lists starts from the current state. Nothing else is needed.

```ts
// src/unread-badge.ts
import { command, define, html, subscription } from '@gyral/core';

declare const unread: { get(): number; subscribe(listener: () => void): () => void };

const unreadSource = subscription<number>('unread', (emit) => {
  emit(unread.get());
  return unread.subscribe(() => emit(unread.get()));
});

type Msg = { readonly _tag: 'Count'; readonly n: number };

export const UnreadBadge = define<number, Msg>()('unread-badge', {
  init: () => 0,
  // Moved: keeps running. Removed: released. Attached again: subscribed again.
  subscriptions: () => [
    command(unreadSource, undefined, { onSuccess: (n): Msg => ({ _tag: 'Count', n }) }),
  ],
  update: { Count: (_n, m) => m.n },
  view: (n) => html`<span class="badge">${n}</span>`,
});
```

`moveBefore()` keeps everything too, without even the disconnect.

## A store per page, provided by name

When each page, or each test, creates its own store, build the commands with a driver that
explains what's missing, and provide the real one above the components by name. Drivers are
[looked up by name](https://gyral.dev/docs/effects/#substituting-drivers), nearest first:

```ts
// src/table.ts
import { provideDrivers, subscription } from '@gyral/core';

export interface Table {
  readonly moves: number;
}

interface TableStore {
  getState(): Table;
  subscribe(listener: () => void): () => void;
}

/** Commands are built with this one; it fails with a clear error until a page provides one. */
export const unboundTable = subscription<Table>('table', () => {
  throw new Error('No table: call provideTable(element, store) on an ancestor.');
});

/** Gives every component under `element` this page's store; returns how to undo it. */
export const provideTable = (element: Element, store: TableStore): (() => void) =>
  provideDrivers(element, {
    table: subscription<Table>('table', (emit) => {
      emit(store.getState());
      return store.subscribe(() => {
        emit(store.getState());
      });
    }),
  });
```

## TC39 signals

When an app keeps its state in signals, a subscription can stream it into components. This
recipe uses the [`signal-polyfill`](https://github.com/proposal-signals/signal-polyfill)
package. A `Watcher`'s notification may not read signals, so it re-arms and reads in a
microtask:

```ts
import { Signal } from 'signal-polyfill';
import { subscription } from '@gyral/core';

/** Streams read() now and after every change to the signals it reads. */
export const watchSignals = <T>(name: string, read: () => T) =>
  subscription<T>(name, (emit, { signal }) => {
    const current = new Signal.Computed(read);
    const watcher = new Signal.subtle.Watcher(() => {
      queueMicrotask(() => {
        if (signal.aborted) return;
        watcher.watch(); // re-arm
        emit(current.get());
      });
    });
    watcher.watch(current);
    emit(current.get());
    return () => watcher.unwatch(current);
  });

// const board = watchSignals('board', () => ({ tasks: store.tasks.get(), filter: store.filter.get() }));
```

Have `read` return plain data, a snapshot object, not the signals themselves.

## A WebSocket feed

```ts
// src/feed.ts
import { command, retry, subscription, type Command } from '@gyral/core';

/** Text messages from `url` until the component goes away; reconnects twice on failure. */
export const feed = retry(
  subscription<string, string>('feed', (emit, { input: url, fail }) => {
    const socket = new WebSocket(url);
    socket.addEventListener('message', (e: MessageEvent<unknown>) => {
      if (typeof e.data === 'string') emit(e.data);
    });
    socket.addEventListener('close', (e) => {
      if (!e.wasClean) fail(new Error(`${url} closed (${String(e.code)})`));
    });
    return () => {
      socket.close();
    };
  }),
  { times: 2, delayMs: 1000, backoff: 'exponential' },
);

export const listenTo = <M>(url: string, toMsg: (line: string) => M): Command<M> =>
  command(feed, url, { onSuccess: toMsg, key: `feed:${url}` });
```

To send on the same socket, keep the connection in one module and give it a plain driver for
writes (`run: (text) => { socket.send(text); }`).

## Testing

- **Use the real source**: create the store in the test, provide its driver by name
  (`provideDrivers(container, { table: … })` from `@gyral/core`, `mount(Component, { drivers })` from `@gyral/testing`, or `el.drivers`), change the
  store, then `await settled()`. `settled()` doesn't wait for a subscription to end (it never
  does), but it waits for values already on their way, such as a store that notifies in a
  microtask or a watcher that re-arms in one. No `await Promise.resolve()` loops.
- **Or fake it**: `fakeDriver('counter')` records the subscription, and `emitNext(value)` pushes
  a value through it.
- **Releasing takes one microtask**: after `el.remove(); await Promise.resolve();`, a real
  subscription's unsubscribe has run and a fake's `calls[0].signal.aborted` is `true` (see
  [Testing](https://gyral.dev/docs/testing/#fake-drivers-and-commands)). To test a move, `append` the element
  somewhere else in the same task and check that the signal is still not aborted.

---

# Routing

> Typed route tables that work on the server and in the browser, navigation as commands, and the current URL streamed into your model.

Source: https://gyral.dev/docs/routing/

`@gyral/router` keeps routing inside the loop. The route is model state, derived from the URL;
navigating is a command; and every URL change arrives as a message. The route table is pure, so
the server matches requests with the same table.

```sh
npm install @gyral/router
```

## Route tables

```ts
// src/routes.ts
import { routes } from '@gyral/router';

export const app = routes({
  home: '/',
  user: '/users/:id',
  settings: '/settings',
});
```

- `app.match('/users/7/')` returns `{ name: 'user', params: { id: '7' }, path: '/users/7' }`, or
  `undefined`. The result is a union discriminated by `name`, and `params` is typed from the
  pattern. `path` is the route's canonical path, `href(name, params)`: see
  [One URL per page](#one-url-per-page).
- `app.href('user', { id: 'a b' })` builds `/users/a%20b`.
- Patterns support literal segments, required `:params`, optional `:params?` and trailing
  `:path*` captures, with the same behavior in URLPattern and Gyral's fallback. One trailing slash is ignored, an empty
  segment (`/users//7`) never matches, params are decoded, and the first match in table order
  wins.
- Matching never touches `window`, so it's safe on a server.

### Optional segments and catch-all routes

```ts
// src/content-routes.ts
import { routes } from '@gyral/router';

export const contentRoutes = routes({
  product: '/products/:id?',
  docs: '/docs/:path*',
  notFound: '/:path*',
});

export const products = contentRoutes.href('product', {}); // /products
export const guide = contentRoutes.href('docs', { path: ['guide', 'a/b'] });
// /docs/guide/a%2Fb: an encoded slash stays in one captured segment.
```

An omitted optional parameter is absent from `params`. A catch-all always returns a readonly
array, including `[]` when it captures no segments. Catch-all segments must be last, and the
first matching route wins: put the not-found route last and explicitly return HTTP 404 from
your server when it matches. Selecting that route alone does not change the response status.

`href` rejects missing required parameters, empty or dot segments, and ambiguous optional
omissions. For `/:first?/:second?`, `{ second: 'x' }` would match as `{ first: 'x' }`; use a
literal separator instead. Bare wildcards, regexes and groups are outside the route grammar.

## Listening to navigation

```ts
// src/shell.ts
import { define, focus, html, type Head } from '@gyral/core';
import { listen, setHead, type RouteLocation, type RouteMatch } from '@gyral/router';
import { app } from './routes.js';

const ORIGIN = 'https://example.com';

type Route = RouteMatch<typeof app.table> | undefined;

export interface State {
  readonly route: Route;
}

export type Msg = { readonly _tag: 'Routed'; readonly location: RouteLocation };

/** One pure function names every page, so the server can render the same <title>. */
export const pageTitle = (route: Route): string =>
  route === undefined
    ? 'Not found'
    : route.name === 'user'
      ? `User ${route.params.id}`
      : route.name;

/** The page's head, used by the server's renderPage() and by setHead() after a navigation. */
export const pageHead = (route: Route): Head => ({
  title: `${pageTitle(route)} · Example`,
  description: 'Users and settings.',
  ...(route === undefined
    ? { robots: 'noindex' }
    : { canonical: new URL(route.path, ORIGIN).href }),
});

export const Shell = define<State, Msg>()('my-shell', {
  // The page itself, so its content is light DOM and it captures same-origin link clicks.
  shadow: false,
  init: () => ({ route: undefined }),
  // Every location, for as long as the shell is on the page.
  subscriptions: () => [listen((location): Msg => ({ _tag: 'Routed', location }))],
  update: {
    Routed: (_s, m) => {
      const route = app.match(m.location.href);
      const head = setHead(pageHead(route));
      // After a navigation (not on the page load), move focus to the new page's heading.
      return [{ route }, m.location.seq === 0 ? [head] : [head, focus('main h1')]];
    },
  },
  view: (s) => html`
    <nav aria-label="Main">
      <a href=${app.href('home', {})}>Home</a>
      <a href=${app.href('user', { id: '7' })}>User 7</a>
      <a href=${app.href('settings', {})}>Settings</a>
    </nav>
    <main><h1 tabindex="-1">${pageTitle(s.route)}</h1></main>
  `,
});
```

`listen(toMsg)` is a long-running command, listed in the component's
[`subscriptions`](https://gyral.dev/docs/update/#subscriptions). It delivers the current location at once, then
every change (link clicks, `navigate()`, back and forward), while the component is on the page.
Link capture is the router's own option: the app's entry provides the router once,
`provideDrivers(document.body, { router: makeRouter({ captureLinks: true }) })`.
Each location carries a `seq`, which counts the URL changes the router has seen: `0` is the URL
the page loaded with. The view is a pure function of the route in state.

## Navigating

Navigation is a command, returned from a reducer like any other:

| Command                   | Does                                                                                                       |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `navigate(url, options?)` | Push a history entry (`replace: true` replaces it; `scroll`, `focusReset`: [see below](#scroll-and-focus)) |
| `setHead(head)`           | Make the document's head match a `Head` ([see below](#the-head))                                           |

For a Back or Forward button, send the router a traversal: `command(router, { _tag: 'Traverse',
delta: -1 })`, with `router` from `@gyral/router`.

```ts
// src/save.ts
import type { Command } from '@gyral/core';
import { navigate } from '@gyral/router';
import { app } from './routes.js';

/** After saving, go to the user's page without adding a history entry. */
export const afterSave = (id: string): Command<never> =>
  navigate(app.href('user', { id }), { replace: true });
```

The router uses the Navigation API where the browser has it and the History API elsewhere, so
both behave the same. Browsers with the Navigation API never download the History API code.

## Scroll and focus

After a navigation, the router does what the browser does for a page load, once the new page
has rendered:

- **Scroll**: to the `#fragment` target, or to the top, after a push. Back and forward restore
  the position the page was left at.
- **Focus**: to the first `[autofocus]` element, or back to the start of the page, so the next
  Tab starts at the top of the new page instead of on a link that's gone.

A replace leaves both alone, because apps replace the entry to keep the URL in step with what
the user is doing ([Updating the query](#updating-the-query)); pass `scroll: true` or
`focusReset: true` to opt in. Both happen with or without the Navigation API. The browser looks
for a fragment's target in the document only, so render targets in light DOM: page-level
components with `shadow: false`, like the shell above.

Focus at the start of the page tells a screen reader user little about where they landed. Move it to
the new page's heading instead, as the shell does: `focus('main h1')` from the `Routed` reducer,
with `tabindex="-1"` on the heading so it can take focus. Skip it for the first location
(`location.seq === 0`), which is the page load, not a navigation. Focus that your app moves during a
navigation wins: the router doesn't reset it. If the heading appears only after data loads, focus it
from the message that brings the data.

To manage scroll or focus yourself, turn either off for one navigation, with
`navigate(url, { scroll: false, focusReset: false })`, or for every navigation the router
starts, link clicks and back and forward included, with
`makeRouter({ scroll: false, focusReset: false })`. Memory history ignores both.

## Updating the query

A search box or a set of filters often keeps its state in the query string, so the URL can be
shared and survives a reload. Update the query with `navigate` too, not with
`history.replaceState`, which the router never sees: its location, and every `listen()`, would
be one step behind. Replace the entry, so each keystroke doesn't add one. A replace leaves
scroll and focus where they are:

```ts
// src/product-filters.ts
import { define, html } from '@gyral/core';
import { listen, navigate, type RouteLocation } from '@gyral/router';

export interface State {
  readonly query: string;
}

export type Msg =
  | { readonly _tag: 'Routed'; readonly location: RouteLocation }
  | { readonly _tag: 'Typed'; readonly query: string };

export const ProductFilters = define<State, Msg>()('my-product-filters', {
  init: () => ({ query: '' }),
  subscriptions: () => [listen((location): Msg => ({ _tag: 'Routed', location }))],
  intent: { Typed: ({ value }) => ({ _tag: 'Typed', query: value ?? '' }) },
  update: {
    // The URL is the source of truth: a shared link or back and forward set the box.
    Routed: (_s, m) => ({ query: new URLSearchParams(m.location.search).get('q') ?? '' }),
    Typed: (_s, m) => [
      { query: m.query },
      [navigate(`?q=${encodeURIComponent(m.query)}`, { replace: true })],
    ],
  },
  view: (s, i) => html`
    <search>
      <label for="q">Filter products</label>
      <input id="q" type="search" value=${s.query} data-intent=${i.Typed} />
    </search>
  `,
});
```

The page stays where it is and focus stays in the box while the user types. A relative URL such
as `?q=…` keeps the current path.

## Links

Links stay plain `<a href>` elements. They work before JavaScript loads, open in new tabs, and
are what crawlers follow.

Link capture is **opt-in**: `makeRouter({ captureLinks: true })` turns same-origin clicks into
in-app navigations, and only while some component is listening. That's right for an app that
owns the whole page. In a multi-page, server-rendered site where only one component routes, leave
it off, so ordinary links keep loading pages.

Captured clicks skip modified clicks (new tab), `target` other than `_self`, `download`,
`rel="external"`, other origins and same-page `#hash` links. Anchors inside shadow roots work.
`linkRoot: element` limits capture to one part of the page.

## The head

A page's head is one value, a `Head` from `@gyral/core`: `title`, `description`, `canonical`,
`robots`, `meta` (Open Graph and other name/property tags), `links` (alternates, icons),
`jsonLd`, `lang` and `dir`. Compute it with a pure function, `pageHead` above, and use it twice:

- **On the server**, spread it into `renderPage()`, which writes each entry once,
  right after `<title>`, marked `data-gyral-head`.
- **In the browser**, return `setHead(pageHead(route))` from the `Routed` reducer. It changes
  only the elements it manages: entries the new head drops are removed, and head markup you
  wrote yourself is left alone. The first `Routed` after hydration finds the server's head and
  changes nothing.

So a client navigation leaves exactly the head a page load would, and the two can't disagree.
Titles that depend on data, such as a product's name, come from state the same way. The page
owns its head: components don't add to it, because the server writes the head before any
component renders.

- **`canonical` is absolute**: build it from `match().path` and your origin
  ([One URL per page](#one-url-per-page)).
- **Stylesheets, preloads and the charset aren't head entries.** They belong to `renderPage()`'s own
  options (`stylesheets`, `modulepreload`, `headScripts`) or `extraHead`, because changing them on navigation
  would unstyle the page or refetch modules. Development builds reject them in a `Head`.
- **JSON-LD** is data, not script, so `script-src` doesn't apply to it. Under an enforced
  Trusted Types policy, `setHead` leaves JSON-LD as the server wrote it and warns once.

## Server-side routes

On the server, match the request with the same table, choose the status, and render:

```ts
// server/app.ts
import { Hono } from 'hono';
import { html } from '@gyral/core';
import { renderPage } from '@gyral/ssr';
import { app as routes } from '../src/routes.js';
import { pageHead } from '../src/shell.js';

export const server = new Hono();

server.get('*', (c) => {
  const url = new URL(c.req.url);
  const route = routes.match(url);
  // One URL per page: /users/7/ redirects to /users/7.
  if (route && route.path !== url.pathname) {
    return Response.redirect(new URL(route.path + url.search, url), 301);
  }
  return renderPage(
    {
      ...pageHead(route),
      body: html`<my-shell></my-shell>`,
      scripts: ['/src/entry-client.ts'],
    },
    { status: route === undefined ? 404 : 200 },
  );
});
```

### One URL per page

The router ignores a trailing slash, so `/users/7` and `/users/7/` match the same route. A page
that answers at two URLs splits its links and its search ranking, and caches store it twice.
`match()` returns the route's canonical `path` (also the canonical spelling of
percent-escapes), so the server redirects every other spelling to it, as above, and keeps the
query string. `path` is a fixed point: matching it gives the same route and the same `path`.

### The first render

The server doesn't run `listen()` (commands never run on the server), so the shell above is
server-rendered with no route and gets one only after hydration, when `listen()` delivers the
URL. Pass the request path as a prop and start from it in `init` if the first render must show
the route, as Gyral's [isomorphic example](https://gyral.dev/examples/#isomorphic) does: then `listen()` delivers
the same URL and nothing changes.

## Memory history

`makeRouter({ history: 'memory', initial: '/settings' })` keeps history in memory: push, replace,
back and forward work, and the real URL and title are never touched. Use it in tests, and on
servers. `driver.snapshot()` returns the router's `{ href, head, length }` for assertions, `head`
being the last `setHead()` value.

---

# Rendering modes

> Choose how each page renders - in the browser only, once at build time, or on every request - and mix all three in one app.

Source: https://gyral.dev/docs/rendering-modes/

A Gyral component is the same code wherever it renders. What changes is **when** its HTML is
made, and that is a choice you make per page, not per app:

| Mode            | HTML is made                  | Needs at runtime        | Use it for                                 |
| --------------- | ----------------------------- | ----------------------- | ------------------------------------------ |
| **Client**      | in the browser, by JavaScript | any static file host    | widgets inside an existing page, admin UIs |
| **Static**      | once, at build time           | any static file host    | home, docs, marketing, blog posts          |
| **Per request** | on the server, for each visit | a server (Node, Bun, …) | carts, accounts, search results, forms     |

The static and per-request modes produce the **same HTML**: a static page is a per-request page
rendered ahead of time. Both work before any JavaScript loads and hydrate in place when it does,
so you can move a page from one mode to the other without touching its components.

## Mixing modes

Most real sites mix them. This website prerenders every page and runs two live components: the
counter on the home page and the search box on the search page. [gyral-shop](https://github.com/gyraljs/gyral-shop) renders product
listings and the cart per request, because they change with every visitor.

Keep the decision next to your routes, so there is one place to read it:

```ts
// src/routes.ts
import { routes } from '@gyral/router';
import type { RenderMode } from '@gyral/ssr/static';

export const site = routes({ home: '/', about: '/about', account: '/account' });

/** How each route renders in production. */
export const modes = {
  home: 'ssg',
  about: 'ssg',
  account: 'ssr',
} as const satisfies Record<'home' | 'about' | 'account', RenderMode>;

/** Every route rendered at build time, for the prerender step. */
export const staticPaths = (): string[] =>
  (Object.keys(modes) as (keyof typeof modes)[])
    .filter((name) => modes[name] === 'ssg')
    .map((name) => site.href(name, {}));
```

`RenderMode` names them the way the rest of the ecosystem does: `ssg` (static), `ssr` (per
request) and `csr` (client). Gyral's
[isomorphic example](https://github.com/gyraljs/gyral/tree/v0.3.6/examples/isomorphic) uses
exactly this table.

## Client-only builds

An app that no server renders can tell the build so, and leave the hydration code out of its
bundle:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { gyralVitePreset } from '@gyral/core/vite';

export default defineConfig({
  ...gyralVitePreset({ clientOnly: true }),
});
```

With `clientOnly: true` the browser bundle carries no hydration code: no seed reading and no
hydration chunk, and when your app has no other `import()`, Vite's preload helper goes too. The
fallback for [invoker commands](https://gyral.dev/docs/intent/#invoker-commands) stays only when a module may make
a component listen for `command` intents ([what the build reads](#what-the-build-reads)).
Measured on Gyral's examples (gzip, 0.3.6):

| App         | Default: first load | Default: all chunks | `clientOnly: true` |
| ----------- | ------------------- | ------------------- | ------------------ |
| hello-world | 9.58 KiB            | 12.03 KiB           | 8.49 KiB           |

"First load" is what a page downloads before any lazy `import()`; in these examples a
client-only build has nothing lazy left, so its first load is all of it.

Use it for apps that load their components with a `<script type="module">` into pages no Gyral
server wrote: widgets in an existing site, admin tools, single-page apps. Leave it off as soon
as any page is server-rendered or prerendered, including islands, and spread the same preset
into your Vitest config so tests build the way the app does. With plugins of your own, spread
the preset and add them: `plugins: [...preset.plugins, mine()]`.

If server-rendered markup reaches a client-only build anyway, nothing breaks twice: each
component drops the server's seed and DOM and renders fresh from its attributes, so a view is
never doubled. Development warns once and names `clientOnly`; production renders fresh
silently. The server's work is wasted, though, so treat that warning as a configuration bug.

### Starting from create-gyral

`create-gyral`'s `basic` template is client-only from the start: its `vite.config.ts` sets
`gyralVitePreset({ clientOnly: true })`, and its `vitest.config.ts` reuses that config, so tests
build the way the app does. A new app is about 8.5 KiB gzip, in one file. Keep the option while
every page renders in the browser. Delete `clientOnly: true` as soon as any page is rendered on
a server or prerendered, for example when you add `@gyral/ssr`: with it on, those components
can't hydrate and render again from scratch. The `ssr` template builds without it.

### What the build reads

To decide what a bundle needs, the build reads the code that can affect your components, not
your whole dependency tree:

- **Which modules**: your own source (everything outside `node_modules`, workspace and linked
  packages included), and installed packages that are Gyral packages or list a `@gyral/*`
  package in `dependencies`, `peerDependencies` or `optionalDependencies`, directly or through
  their own dependencies, such as a design system built on Gyral. Any other package can't
  define a component or write its spec, so it isn't read.
- **What counts**: the parsed source, not its text, so comments and type-only code never count.
  The invoker fallback stays when a module's markup has `command` in a `data-intent-on` list
  (`data-intent-on="command"`), a `data-intent-command` attribute or a bound `data-intent-on`,
  when it has the string `'command'` on its own (a `setAttribute('data-intent-on', 'command')`), or when it uses `raw` imported from `@gyral/core` (under any alias, or
  through a module that re-exports it), whose markup is only known at run time. A function of
  another package that happens to be called `raw` doesn't count.

Every build with the preset, client-only or not, uses the same scan for the features a spec
field turns on: view transitions, the frame lane, custom states, form association,
subscriptions and the error fallback are bundled only when a module names `viewTransition`,
`renderOnFrame`, `states`, `formAssociated`, `subscriptions`, `error` or `Errored` in code.
Write these field names literally: a name built at run time isn't seen, and the component then
renders without that feature (development builds warn). A package that writes these fields for
your components must depend on Gyral to be read: if it doesn't, declare `@gyral/core` as a peer
dependency in its `package.json`.

This site server-renders its pages and hydrates two islands, so it builds without the option.

## Where to go next

- **Client only**: write components as in [Getting started](https://gyral.dev/docs/getting-started/) and load
  them with a `<script type="module">`. No server code at all, and a
  [client-only build](#client-only-builds) to match.
- **Static**: [Static sites and prerendering](https://gyral.dev/docs/static-sites/).
- **Per request**: [Server rendering](https://gyral.dev/docs/server-rendering/).
- **Shipping it**: [Deploying](https://gyral.dev/docs/deploying/) covers static hosts, Node, Bun and edge
  runtimes.
- **A Rust backend**: [Rust servers](https://gyral.dev/docs/rust-servers/) covers each mode with Rust as the
  web server.
- **Less JavaScript on each page**: [Code-splitting and lazy loading](https://gyral.dev/docs/code-splitting/).

---

# Server rendering

> Render pages on the server with Declarative Shadow DOM, hydrate them in place, keep a strict CSP, and ship a production build.

Source: https://gyral.dev/docs/server-rendering/

`@gyral/ssr` renders Gyral components on the server, so a page is readable, and its links and
forms work, before any JavaScript loads. In the browser, each component **hydrates in place**: it
takes over the server's DOM and resumes from the server's state instead of rendering again.

```sh
npm install @gyral/core @gyral/ssr
```

That's all. `@gyral/ssr` renders pages, responses and CSP headers. It needs no DOM shim and no Node-only APIs, so the same code
runs in Node, Deno, Bun and Cloudflare Workers.

## renderPage()

The examples on this page render the counter from [Getting started](https://gyral.dev/docs/getting-started/):

```ts
// src/counter.ts
import { define, html } from '@gyral/core';

export type Msg = { readonly _tag: 'Increment' } | { readonly _tag: 'Decrement' };

export const Counter = define<{ readonly count: number }, Msg>()('my-counter', {
  init: () => ({ count: 0 }),
  intent: { Increment: true, Decrement: true },
  update: {
    Increment: (s) => ({ count: s.count + 1 }),
    Decrement: (s) => ({ count: s.count - 1 }),
  },
  view: (s, i) => html`
    <button type="button" data-intent=${i.Decrement}>Decrement</button>
    <output aria-live="polite">${s.count}</output>
    <button type="button" data-intent=${i.Increment}>Increment</button>
  `,
});
```

A route handler renders it inside a page:

```ts
// server/app.ts
import { Hono } from 'hono';
import { html } from '@gyral/core';
import { renderPage, type ComponentAssets } from '@gyral/ssr';
import '../src/counter.js'; // registers <my-counter> so the server can render it

/** `components` comes from the dev server or the production build (below); tests leave it out. */
export const createApp = (components?: ComponentAssets) =>
  new Hono().get('/', () =>
    renderPage({
      title: 'Counter',
      description: 'A counter rendered on the server and hydrated in the browser.',
      canonical: 'https://example.com/',
      links: [{ rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }],
      body: html`<main>
        <h1>Counter</h1>
        <my-counter></my-counter>
      </main>`,
      ...(components === undefined ? {} : { components }),
    }),
  );
```

- **`renderPage(options, init?)`** returns a web `Response` whose body is pulled in chunks from
  a synchronous render, one component boundary per pull. Load data before you call it: nothing
  is awaited mid-page, and there is no suspense streaming. The status and headers are final
  before the first byte, so a 404 is a real 404. Hono, Deno, Bun, Cloudflare Workers or a
  service worker can serve it.
- **Its body is a stream** (`renderPage(o).body`). For a string, such as a page written to a file,
  read it: `await renderPage(o).text()`.
- **The head fields** (`title`, `description`, `canonical`, `robots`, `meta`, `links`,
  `jsonLd`, `lang`, `dir`) are a `Head` from `@gyral/core`, the same value the router's
  `setHead()` applies after a client navigation ([Routing](https://gyral.dev/docs/routing/#the-head)). The
  server writes each entry once, marked `data-gyral-head`.
- **`body`** and **`extraHead`** are ordinary `html` templates from `@gyral/core`, the same tag
  your components use. `extraHead` is for head markup the head model doesn't manage, such as
  preconnect hints. Meta and link entries in the head model take `media`, `sizes`, `type` and
  the other standard attributes, so a pair of `theme-color` tags is plain head data. The shell itself is never hydrated; the components inside it
  are.
- **`styles`** takes your global CSS as text and writes it into `<style>` elements, escaped so
  it can't close the element early. Trusted CSS only.
- **`stylesheets`** takes stylesheet URLs and writes a `<link rel="stylesheet">` for each, before
  the inline `styles`. In production these are the hashed CSS files Vite builds from your client
  entry (see [Static sites](https://gyral.dev/docs/static-sites/#a-static-build)).
- **`headScripts`** takes inline scripts that must run before any stylesheet, such as a theme
  script that sets `data-theme` before the first paint. `renderPage` adds their hashes to
  `script-src`, so a strict CSP allows them.
- **`stores`** passes this request's [store](https://gyral.dev/docs/stores/) instances.
- **`csp`** sets a `Content-Security-Policy` header (see
  [below](#content-security-policy)).

Importing a component's module is all the server needs: outside the browser, `define()` records
the spec, and the renderer renders it wherever its tag appears. A shadow component renders into
Declarative Shadow DOM, a `<template shadowrootmode="open">` the browser turns into a real
shadow root while parsing, with its CSS in one `<style>`. A light component (`shadow: false`)
renders as plain children.

## What runs on the server

Rendering is synchronous: the server runs `init(props)` and the view, and nothing else.

- **Commands never run.** There's no interpreter, no timer and no network on the server.
- **Do async work in the route handler** and pass the results as props:
  `` html`<my-product .product=${await loadProduct(id)}></my-product>` ``. A `Promise` anywhere
  in a view is an error.
- **`initialMessages`** run through `update` before the server render, for example to show a
  rejected form's errors (see [Forms](https://gyral.dev/docs/forms/#the-server-half)).

To avoid fetching again in the browser what the server already loaded, make the fetch depend on
the props in `init`: `init: (p) => p.product ? [{ … }] : [{ … }, [load()]]`. Both sides make the
same decision.

The renderer yields a chunk at every component boundary, and it is fast: a 1,000-row table
renders to a string in about 0.2 ms on Node 24 (1.3 ms including encoding).

## Loading components in the browser

Turn on `components` in the Vite preset and pass the `components` your server gets to
`renderPage`. Each page then loads exactly the components it rendered (their modules,
preloaded, and a small loader), and a page that rendered none loads no JavaScript at all. There
is no client entry to write and no per-page list of islands:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { gyralVitePreset } from '@gyral/core/vite';

export default defineConfig({
  ...gyralVitePreset({ components: true }), // finds every define()'d tag under src/
  build: { outDir: 'dist/client', emptyOutDir: true },
});
```

The server still imports the components it renders. The loader finds the tags in the page and,
as it defines components, the tags rendered in their shadow roots too, at any depth, so a
component inside another component's shadow DOM loads without its parent importing it. A
rendered tag that no client module defines is a development warning, so a missing island can't
fail silently. For app-wide setup in the browser (providing drivers to the page), keep a small
client entry and pass it in `scripts` next to `components`.

The preset finds components written as `export const X = define<…>()('my-tag', …)`. It reads
code only: a `define()` inside a comment, a string, template text or a regular
expression doesn't count, so a code sample in a doc comment or a test fixture defines no tag. A
component created through a helper of your own (one that calls `define()` with a tag it was
given) is invisible to that scan, so list it with its module, relative to the project root:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { gyralVitePreset } from '@gyral/core/vite';

export default defineConfig({
  ...gyralVitePreset({
    components: { modules: { 'member-form': 'src/forms/member.ts' } },
  }),
  build: { outDir: 'dist/client', emptyOutDir: true },
});
```

A component module that the client entry or another component also imports is bundled into that
chunk; it still loads, and its preload is that chunk. The links `renderPage` writes after the body
leave out what the head already links (`modulepreload`, `stylesheets` and `scripts`), so pass
`modulepreload` next to `components` as you get them: no module is linked twice.
In a large app, measure before you switch
from a hand-written loader: each component becomes its own chunk, and the loader carries the
list of their dependencies.

To wait until the page's components are defined and have rendered, await `componentsReady()`
from `@gyral/core`, in a page script or a browser test. It resolves once every rendered tag the
loader knows about is defined and the page has settled; without automatic components it is
`settled()`:

```ts
import { componentsReady } from '@gyral/core';

await componentsReady();
document.querySelector<HTMLElement>('site-search')?.focus();
```

Hydration is built into `@gyral/core`, and module order doesn't matter. When a server-rendered
component connects in the browser, it reads the state the server rendered (each one carries a
`data-gyral-seed` attribute with its state and its property-bound props), walks its template and
the server's DOM side by side, and adopts the existing nodes. Each component does this on its
own, whether its parent has hydrated yet or not. Then, and only then, it starts `init`'s
commands and its subscriptions, so a router's first location or a timer's first tick can never make the first client
render differ from the server's.

The hydration code is its own chunk (about 2.8 KiB gzip), loaded the first time a
server-rendered component connects. Pages without one never fetch it. With `components`,
`renderPage` preloads it on the pages that need it. With a client entry of your own,
`clientAssetsFromManifest()` from `@gyral/ssr/static` reads the entry, its chunks and its hashed
CSS from Vite's manifest, for `renderPage({ scripts, modulepreload, stylesheets })` (see
[Static sites](https://gyral.dev/docs/static-sites/#a-static-build)).

Every client-side instance then gets the `Hydrated` message once. Use it for progressive
enhancement: render the no-JavaScript version on the server and in the first client render, then
switch to the enhanced one.

The seed carries state as JSON, so keep the state and props of server-rendered components, and
seeded store state, JSON-serializable. In development the server warns, with the exact path,
when a value won't survive the trip (a `Date`, a `Map`, `NaN`). Components that only render in
the browser have no seed, so their state may hold other values; plain data still keeps tests,
devtools and a later move to server rendering simple. State that equals `init(props)` isn't written twice. Form controls keep what the user
typed before scripts ran: hydration never overwrites it, and a control is written again only
when the model's value for it changes.

## Mismatches

The server and the browser share one template normalizer, so they agree on every template's
structure. A mismatch means the view rendered something different for the same state: it read
the clock or a random number, or a browser extension edited the page before scripts ran.

- **In development**, hydration fails with a `HydrationMismatch` that names the tag, the
  template's file and line, the DOM path, and what it expected and found. It is reported as a
  `view` failure through the [error channel](https://gyral.dev/docs/error-handling/#one-channel), and the
  component keeps the server's DOM (or shows its `error` view).
  Development output carries `<!--gyral:ID-->` markers, so the browser also checks that each
  template is the one it expects.
- **In production**, the component logs a warning that describes the mismatch and links to
  [its entry on the errors page](https://gyral.dev/errors/#G0062), then renders itself fresh. Only that
  component: the rest of the page stays hydrated.

## Lazy hydration

Not everything needs to be live at load. `hydrate` in the spec makes a component an island:

| `hydrate`     | Hydrates                            |
| ------------- | ----------------------------------- |
| `load`        | as soon as possible (default)       |
| `idle`        | when the browser is idle            |
| `visible`     | when it scrolls into view           |
| `interaction` | on the first pointer or focus on it |

Until then it's plain server HTML: links and forms still work. `interaction` hydrates on
`pointerover`, `pointerdown`, `focusin` or `touchstart`, which arrive before the click, so the
first click still lands. Islands may sit anywhere, also inside other components. Only the island
waits: components inside its view hydrate on their own at load, so make those islands too if they
should wait.

## Light DOM for page content

Page-level components can render into light DOM with `shadow: false`. The server then writes
plain HTML, with no `<template>`, which every crawler and reader mode understands, and document
CSS styles it. See [Styling](https://gyral.dev/docs/styling/#light-dom-components).

## Content-Security-Policy

Seeds are attributes, not scripts, so `script-src 'self'` is enough. A shadow component's styles
arrive as an inline `<style>` in its Declarative Shadow DOM. Pass `csp: { directives }` to
`renderPage` and it sends a `Content-Security-Policy` header that allows each of them by its
SHA-256 hash, so `style-src` needs no `'unsafe-inline'`:

```ts
// server/home.ts
import { html } from '@gyral/core';
import { renderPage } from '@gyral/ssr';
import '../src/counter.js';

const styles = ':root { color-scheme: light dark; }';

export function home(): Response {
  return renderPage({
    title: 'Home',
    styles,
    body: html`<my-counter></my-counter>`,
    scripts: ['/src/entry-client.ts'],
    // Built when the page renders; cached until another component registers.
    csp: {
      directives: { 'default-src': "'self'", 'script-src': "'self'", 'object-src': "'none'" },
    },
  });
}
```

The header is built when the page renders, so it lists every shadow component registered by
then, also those whose modules were imported lazily after startup, plus each entry of the
page's `styles`. `<style>` elements you write in `extraHead` aren't covered: move that CSS into
`styles` or a stylesheet. Linked stylesheets are same-origin, so `style-src 'self'` allows them
without hashes.

`style="…"` attributes in server HTML aren't covered by default: under a strict policy they
apply only once the component hydrates (see
[Styling](https://gyral.dev/docs/styling/#inline-styles-under-a-strict-csp)). To have them paint at once, opt in
with `styleAttributes: 'hash'`:

```ts
// server/upload.ts
import { html } from '@gyral/core';
import { renderPage } from '@gyral/ssr';

export function upload(done: number): Response {
  return renderPage({
    title: 'Upload',
    body: html`<div class="bar" style="--done: ${done}%"></div>`,
    csp: { directives: { 'default-src': "'self'" }, styleAttributes: 'hash' },
  });
}
```

The header then gets `style-src-attr 'unsafe-hashes' 'sha256-…'` for every distinct `style`
value the page wrote: static, bound and element-hook values, but not `raw()` markup. The page
is rendered to a string first, so its body isn't sent in chunks, and each value adds about 54
bytes of header. Development warns above 32 distinct values, and `maxStyleHashes` (default 128)
caps the list; values past it wait for hydration as before. It applies to pages rendered per
request: a prerendered page has no per-page header. If your `style-src-attr` already allows
`'unsafe-inline'`, no hashes are added, since a hash would switch `'unsafe-inline'` off.

### Trusted Types

Gyral parses template HTML and `raw()` markup in the browser through one Trusted Types policy
named `gyral`, created on first use; client-only apps are covered too. Under
`require-trusted-types-for 'script'`, a policy that lists allowed policies must include it:
`'trusted-types': 'gyral'`, plus your own. If the browser refuses the policy, Gyral falls back to
plain strings, which works only while Trusted Types aren't enforced, and development builds warn
once ([G0072](https://gyral.dev/errors/#G0072)). The policy trusts its input as the app's own HTML, so `raw()`
still never takes user input.

### Ahead of time

`contentSecurityPolicy({ directives, styles? })` builds the same value ahead of time, for the
components imported before the call. Use it where no page renders per request: a static site
writes it into the host's headers file at build time (see
[Static sites](https://gyral.dev/docs/static-sites/#headers-and-csp)), as this site does. A server that
shouldn't import every component can read the hashes from a file the build writes, with
`writeComponentStyleManifest` and `componentStyleHashes` (see
[Security](https://gyral.dev/docs/security/#style-hashes-from-the-build)). In development, `renderPage` warns
when a header string it is given lacks a registered component's hash.

## Static generation

Pages that are the same for everyone can be rendered once, at build time, by the same app.
That has its own page: [Static sites and prerendering](https://gyral.dev/docs/static-sites/). To choose between
static, per-request and client-only rendering, see [Rendering modes](https://gyral.dev/docs/rendering-modes/);
to ship either, see [Deploying](https://gyral.dev/docs/deploying/).

## Development server

`gyralDevServer()` from `@gyral/ssr/node` runs Vite in middleware mode, loads your server module
fresh on every request (so edits show up), streams each response, and shows Vite's error overlay
when a render throws:

```ts
// scripts/dev.ts
import { gyralDevServer } from '@gyral/ssr/node';
import type * as App from '../server/app.js';

const dev = await gyralDevServer<typeof App>({
  entry: '/server/app.ts',
  app: (mod, { components }) => mod.createApp(components),
});
console.log(`Listening on ${dev.url}`);
```

`state` keeps a value, such as an in-memory database, across those reloads.

## The request layer

Gyral renders pages; it doesn't route requests. Routing, middleware, cookies and sessions belong
to a fetch router such as [Hono](https://hono.dev) (any router whose handlers return a web
`Response` works), the way Lit and Preact leave them to the app. `@gyral/ssr` covers the parts
that touch Gyral: `formAction` answers a fetch request with JSON and a plain form post with a
redirect or the page (`wantsJson(request)` tells you which one you got), and
`productionServer({ onResponse })` lets you add headers or cookies to every response it sends.
See [Deploying](https://gyral.dev/docs/deploying/) for both.

## Lower level

`renderToString(value)` from `@gyral/ssr` renders a template to a string, and
`styleHashes()` lists the CSP hashes of every registered component's styles, for a policy you
build yourself. Import them only from server code, so client bundles carry no server renderer.
`renderToString` is also what a Rust server calls when it embeds Gyral through `gyral-rs`
([Rust servers](https://gyral.dev/docs/rust-servers/#embedded-rendering-with-gyral-rs)).

## Production checklist

- Spread `gyralVitePreset()` into your Vite config, so templates are checked and precompiled.
- Keep component state and props JSON data.
- Bind form state with `value=${…}`, `?checked=${…}` and `<textarea>${…}</textarea>`, never
  `.value=` or `.checked=`, which the server can't write.
- Load data before rendering; never put a `Promise` in a view.
- Send a CSP with `renderPage({ csp: { directives } })`; you don't need `'unsafe-inline'`.
- Turn on `components`, so each page loads and preloads only the components it rendered, and
  link your hashed CSS with `stylesheets`.
- Test hydration against a production build, not only the dev server. `@gyral/testing`'s
  `mountSsr` and `hydrated` make that a unit test (see [Testing](https://gyral.dev/docs/testing/#ssr-and-hydration-tests)).

---

# Static sites and prerendering

> Render pages to HTML files at build time with @gyral/ssr/static, ship zero JavaScript where nothing is interactive, and host them anywhere.

Source: https://gyral.dev/docs/static-sites/

Pages that are the same for every visitor can be rendered once, when you build, and served as
plain files. You don't need a server at runtime: any static host will do. This website works
this way. Every page is a prerendered HTML file on Cloudflare Pages, and only the pages with a
live component load any JavaScript.

`@gyral/ssr/static` does the rendering. It doesn't have a renderer of its own: it sends a real
`Request` for each path to the same app you would use to [render per
request](https://gyral.dev/docs/server-rendering/), and writes what comes back to disk. So a static page and a
server-rendered page are the same HTML, hydration seeds included.

## A static build

The app renders pages with `renderPage`, as on a server:

```ts
// src/counter.ts
import { define, html } from '@gyral/core';

export type Msg = { readonly _tag: 'Increment' };

export const Counter = define<{ readonly count: number }, Msg>()('my-counter', {
  init: () => ({ count: 0 }),
  intent: { Increment: () => ({ _tag: 'Increment' }) },
  update: { Increment: (s) => ({ count: s.count + 1 }) },
  view: (s, i) => html`
    <output aria-live="polite">${s.count}</output>
    <button type="button" data-intent=${i.Increment}>Increment</button>
  `,
});
```

```ts
// server/create-app.ts
import { Hono } from 'hono';
import { html } from '@gyral/core';
import { renderPage } from '@gyral/ssr';
import '../src/counter.js';

export interface ClientAssets {
  readonly clientEntry: string;
  readonly modulepreload: readonly string[];
  readonly stylesheets: readonly string[];
}

export const createApp = ({ clientEntry, modulepreload, stylesheets }: ClientAssets): Hono => {
  const app = new Hono();
  // A page with a live component loads the client entry, and preloads what it needs...
  app.get('/', () =>
    renderPage({
      title: 'Home',
      body: html`<main>
        <h1>Home</h1>
        <my-counter></my-counter>
      </main>`,
      scripts: [clientEntry],
      modulepreload,
      stylesheets,
    }),
  );
  // ...and a page without one ships no JavaScript at all, only the stylesheet.
  app.get('/about/', () =>
    renderPage({ title: 'About', body: html`<main><h1>About us</h1></main>`, stylesheets }),
  );
  return app;
};
```

After `vite build`, a script renders every path into the same folder:

```ts
// scripts/prerender.ts
import { clientAssetsFromManifest, prerender } from '@gyral/ssr/static';
import { createApp } from '../server/create-app.js';

const client = await clientAssetsFromManifest('dist/.vite/manifest.json', 'src/entry-client.ts');
const pages = await prerender({
  app: createApp({
    clientEntry: client.entry,
    modulepreload: client.modulepreload,
    stylesheets: client.css,
  }),
  paths: ['/', '/about/'],
  outDir: 'dist',
  origin: 'https://example.com',
});
console.log(`prerendered ${String(pages.length)} pages`);
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { gyralVitePreset } from '@gyral/core/vite';

export default defineConfig({
  ...gyralVitePreset(),
  build: {
    outDir: 'dist',
    emptyOutDir: true,
    manifest: true, // clientAssetsFromManifest reads it
    rollupOptions: { input: 'src/entry-client.ts' },
  },
});
```

- **`prerender({ app, paths, outDir, origin })`** writes `/about/` to `dist/about/index.html`.
  A path that doesn't answer `200` fails the build, so an error page can't ship by accident.
- **`origin`** is the URL the requests are made with. Set it to your real site, so absolute
  URLs your pages build from the request (canonical links, Open Graph tags) come out right.
- **`clientAssetsFromManifest(manifestPath, entry)`** reads Vite's manifest and returns the
  hashed URL of your client entry (`entry`, for example `/assets/entry-client-Ab12.js`) and the
  chunks to preload with it (`modulepreload`): the entry itself, its static imports and Gyral's
  hydration chunk.
  `renderPage({ modulepreload })` writes a `<link rel="modulepreload">` for each, so the browser
  fetches them alongside the entry instead of a round trip later. A third argument lists
  modules a page imports lazily, by source path (`['src/routes/product.ts']`); they are
  preloaded too, each with its static imports, and their CSS joins `css`.
- **`css`** lists the content-hashed CSS files Vite built from the stylesheets your client entry
  imports (`import './app.css';`), each after the files of the modules it imports, so the
  cascade is the one you had in development. Link them with `renderPage({ stylesheets })`
  instead of inlining your CSS into every page with `styles`: the browser caches one file across
  pages, and `style-src 'self'` allows it with no hash.
- The client entry (`src/entry-client.ts`) imports your components (`import './counter.js';`),
  and each one hydrates on its own. To have each page load only the components it rendered,
  with no entry to write, see
  [Server rendering](https://gyral.dev/docs/server-rendering/#loading-components-in-the-browser).
- `@gyral/ssr/static` reads and writes files, so it runs in Node at build time. Your pages
  don't need Node: the output is plain files.

Deploy `dist/` to any static host. [Deploying](https://gyral.dev/docs/deploying/#static-hosts) has the settings
for the common ones.

## What ships no JavaScript

A page is only HTML and CSS until you give it `scripts`. Every component on it is still
rendered: each shadow root is written as Declarative Shadow DOM, which the browser turns into a
real shadow root while it parses, styles included. Links and forms work. Nothing hydrates,
because nothing loaded the code to do it.

That makes "should this page have JavaScript?" a per-page decision. On this website the docs
pages have none, and the home page loads one small entry for its counter. To delay even that,
see [lazy hydration](https://gyral.dev/docs/server-rendering/#lazy-hydration) and
[Code-splitting](https://gyral.dev/docs/code-splitting/).

## Headers and CSP

A static host can't compute headers per request, but most read a headers file from the output:
Cloudflare Pages and Netlify read `_headers`. Where a server renders per request,
`renderPage({ csp })` builds the policy as the page renders; here, build it ahead of time with
`contentSecurityPolicy()` from `@gyral/ssr` in the same build step and write it there. Its
`style-src` lists the hash of each component's Declarative Shadow DOM `<style>`, so it needs no
`'unsafe-inline'`:

```ts
// scripts/headers.ts
import { writeFile } from 'node:fs/promises';
import { contentSecurityPolicy } from '@gyral/ssr';
import '../src/counter.js'; // registers the components whose styles get hashed

const csp = await contentSecurityPolicy({
  directives: { 'default-src': "'self'", 'script-src': "'self'", 'object-src': "'none'" },
});
await writeFile('dist/_headers', `/*\n  Content-Security-Policy: ${csp}\n`);
```

The hashes change when a component's CSS changes, so write the file in every build, never by
hand. Linked stylesheets need no hash: `style-src 'self'` allows them. `style="…"` attributes
aren't covered: the policy blocks them in the HTML, and on a page that never hydrates nothing
applies them later (see [Styling](https://gyral.dev/docs/styling/#inline-styles-under-a-strict-csp)). Give the
element a class instead. This site works this way; its code blocks are coloured by classes
rather than the inline styles a highlighter writes by default.

## Mixing static and per-request pages

When some pages must be rendered per request, keep the [Vite manifest layout
Gyral's production server expects](https://gyral.dev/docs/deploying/#node) (`dist/client/` and `dist/static/`)
and let `productionServer` serve both: prerendered files from disk, everything else through
your app. [Rendering modes](https://gyral.dev/docs/rendering-modes/#mixing-modes) shows how to keep the list of
static paths next to your routes.

## Limits

- Paths with parameters (`/products/:id`) are prerendered only if you list them; there's no
  crawling.
- There's no incremental regeneration: rebuild to change a static page.
- Gyral doesn't write a sitemap for you. Generate one from the same path list.

---

# Code-splitting and lazy loading

> Load each component's code only on the pages that use it, delay hydration until it's needed, and see what each page downloads.

Source: https://gyral.dev/docs/code-splitting/

A server-rendered page is already painted before its JavaScript arrives. So the only question
code-splitting has to answer is **when each component becomes interactive**, and the answer
can be "later, and only if it's on this page". There are three tools, from coarse to fine:

1. **Per-page chunks**: load a component's module only on pages that contain it.
2. **Lazy hydration**: load it, but hydrate it when the browser is idle, when it scrolls into
   view or on first interaction.
3. **No JavaScript at all** for pages that have nothing interactive (see
   [Static sites](https://gyral.dev/docs/static-sites/#what-ships-no-javascript)).

## Load components by what's on the page

Custom elements make this simple: the page's HTML says which components it uses. Import the
components every page has in the client entry, and load the rest when their tag appears.

A server-rendered app can let Gyral do this: with `gyralVitePreset({ components: true })` and
`renderPage({ components })`, each page loads exactly the components it rendered, with no client
entry to write (see
[Server rendering](https://gyral.dev/docs/server-rendering/#loading-components-in-the-browser)). The loader
below is the hand-written version, for pages rendered in the browser or when you want to choose
the chunks yourself.

```ts
// src/widgets.ts
import { define, html } from '@gyral/core';

export const Gallery = define<{ readonly index: number }, { readonly _tag: 'Next' }>()(
  'my-gallery',
  {
    init: () => ({ index: 0 }),
    intent: { Next: () => ({ _tag: 'Next' }) },
    update: { Next: (s) => ({ index: s.index + 1 }) },
    view: (s, i) => html`
      <output>Photo ${s.index + 1}</output>
      <button type="button" data-intent=${i.Next}>Next photo</button>
    `,
  },
);
```

```ts
// src/lazy.ts
type Loader = () => Promise<unknown>;

/** Custom element tag → the module that defines it. */
const LOADERS: Readonly<Record<string, Loader>> = {
  'my-gallery': () => import('./widgets.js'),
};

/** Every custom element tag under `root`, including inside declarative shadow roots. */
function tagsIn(root: ParentNode): Set<string> {
  const tags = new Set<string>();
  const visit = (node: ParentNode): void => {
    for (const el of node.querySelectorAll('*')) {
      if (el.localName.includes('-')) tags.add(el.localName);
      if (el.shadowRoot !== null) visit(el.shadowRoot);
    }
  };
  visit(root);
  return tags;
}

/** Loads the module of every lazily defined tag under `root` that isn't defined yet. */
export async function loadComponentsIn(root: ParentNode): Promise<void> {
  const pending = [...tagsIn(root)]
    .filter((tag) => customElements.get(tag) === undefined)
    .flatMap((tag) => LOADERS[tag] ?? []);
  await Promise.all([...new Set(pending)].map((load) => load()));
}
```

```ts
// src/entry-client.ts
import { loadComponentsIn } from './lazy.js';

await loadComponentsIn(document);
```

Each `import()` becomes its own chunk, so a page without a gallery never downloads it. Until
its module loads, a server-rendered `<my-gallery>` is the server's HTML, already showing its
first state; when the module defines the element, it hydrates in place, with no flash.

A page that you know needs a lazy chunk can preload it with the entry instead of finding it
only after the entry has run. `clientAssetsFromManifest(manifestPath, entry, also)` from
`@gyral/ssr/static` reads Vite's build manifest; `also` takes the source paths of those modules
(`['src/widgets.ts']`) and adds them, with their static imports, to `modulepreload`, and their
CSS to `css`. On a server, `productionServer` hands your app an `assets(modules)` that does the
same per page and returns `{ modulepreload, stylesheets }` to spread into `renderPage` (see
[Deploying](https://gyral.dev/docs/deploying/#node)).

[gyral-shop](https://github.com/gyraljs/gyral-shop) used a loader like this until automatic
components replaced it. Its
[`vite.components.ts`](https://github.com/gyraljs/gyral-shop/blob/main/vite.components.ts) now
only names the tags the scan can't see and keeps the admin sections in one chunk.

## Lazy hydration

When a component's code is on the page but it isn't needed yet, set `hydrate` in its spec:

| `hydrate`     | Hydrates                            |
| ------------- | ----------------------------------- |
| `load`        | as soon as possible (default)       |
| `idle`        | when the browser is idle            |
| `visible`     | when it scrolls into view           |
| `interaction` | on the first pointer or focus on it |

A delayed component is plain server HTML until then: its links and forms still work.
`interaction` hydrates on `pointerover`, `pointerdown`, `focusin` or `touchstart`, which arrive
before the click, so the first click still lands. An island may sit anywhere, also inside
another component; components inside a waiting island still hydrate at load, so make them
islands too if they should wait. More in
[Server rendering](https://gyral.dev/docs/server-rendering/#lazy-hydration).

## Module order doesn't matter

Hydration is built into every component, so no import has to run first. When an entry awaits a
lazy import (as above), the bundler may move the modules both chunks share, such as
`@gyral/core`, into a separate chunk that runs before the entry's own code. That's fine: each
component hydrates from its own seed and its own template whenever its element is defined.

Gyral splits itself the same way. Features load with the API that uses them, so an app that
never calls `each`, `raw`, `defineHook`, `command()` or `defineStore()` doesn't bundle their
code, and the hydration code is a chunk of its own (about 2.8 KiB gzip) that only pages with
server-rendered components fetch. Preload it with the entry: `clientAssetsFromManifest()` from
`@gyral/ssr/static` lists it, and `renderPage({ modulepreload })` writes the hints (see
[Static sites](https://gyral.dev/docs/static-sites/#a-static-build)).

## Which chunk holds a module

With `gyralVitePreset({ components: true })`, the client build writes
`.vite/gyral-components.json` next to Vite's manifest. Its `chunks` maps each tag to the chunk
that defines it. `chunkModules` maps every emitted JavaScript chunk to the source
modules in it, as paths relative to the project root:

```json
{
  "chunks": { "my-gallery": "assets/widgets-CQ3fA1x2.js" },
  "chunkModules": {
    "assets/widgets-CQ3fA1x2.js": ["src/gallery-photo.ts", "src/widgets.ts"]
  }
}
```

Vite's manifest only lists modules that start a chunk. When the bundler merges a module into a
shared chunk, `chunkModules` is where to find it. A service worker or offline cache can use it
to decide which chunks a feature needs: walk the static imports for shared code and CSS, and
keep chunks that two features share for both. Paths outside the project root start with
`../`; treat them as names, not as files to open. Worker builds are separate graphs and
aren't listed.

## Measure

Check what each page actually loads, in the browser's network panel, and the chunk sizes
`vite build` prints. Most apps need only two rules:
the shell's components in the entry, everything page-specific behind `import()`.

---

# Deploying

> Ship a Gyral app to a static host, a Node server, Bun, Deno or Cloudflare Workers, with the right cache headers and a strict Content Security Policy.

Source: https://gyral.dev/docs/deploying/

What you deploy depends on how your pages [render](https://gyral.dev/docs/rendering-modes/):

- **Only static and client-rendered pages**: a folder of files. Any static host serves it.
- **Any page rendered per request**: a small server that runs your app, plus the same files.

Either way, the build output is ordinary: HTML, content-hashed JavaScript and CSS, and your
public files. Gyral adds no runtime service of its own. If your server is written in Rust, see
[Rust servers](https://gyral.dev/docs/rust-servers/).

## Static hosts

Build with the layout from [Static sites and prerendering](https://gyral.dev/docs/static-sites/): Vite and the
prerender step both write to `dist/`. Put fixed headers files in `public/`, which Vite copies
into `dist/` as they are, and write the Content Security Policy at build time
([Headers and CSP](https://gyral.dev/docs/static-sites/#headers-and-csp)). On every host the build command is
`npm run build` and the output directory is `dist`; what differs is where response headers (CSP,
caching) go:

| Host             | Response headers                                     |
| ---------------- | ---------------------------------------------------- |
| Cloudflare Pages | a `_headers` file in the output                      |
| Netlify          | a `_headers` file in the output, or `netlify.toml`   |
| Vercel           | `headers` in `vercel.json` (framework preset: Other) |
| GitHub Pages     | not configurable; use a `<meta>` CSP (see below)     |

GitHub Pages builds in a GitHub Actions workflow that uploads `dist` as its Pages artifact.

This website is the worked example: it builds with `pnpm run build` on Cloudflare Pages, with
`NODE_VERSION` set to 24. Its `_headers` file holds the security and cache headers, and the build
adds the Content Security Policy to it.

Hosts that serve `about/index.html` for `/about/` (all four above do) need no rewrite rules.
Set the host's 404 page to your prerendered `404.html` if you render one.

## Node

When some pages render per request, build into two folders and run Gyral's production server.
`npm create gyral@latest my-app -- --template ssr` sets up a project like this one; the files
below are a trimmed-down version.

```ts
// src/counter.ts
import { define, html } from '@gyral/core';

export const Counter = define<{ readonly count: number }, { readonly _tag: 'Increment' }>()(
  'my-counter',
  {
    init: () => ({ count: 0 }),
    intent: { Increment: true },
    update: { Increment: (s) => ({ count: s.count + 1 }) },
    view: (s, i) => html`
      <output aria-live="polite">${s.count}</output>
      <button type="button" data-intent=${i.Increment}>Increment</button>
    `,
  },
);
```

```ts
// server/app.ts
import { Hono } from 'hono';
import { html } from '@gyral/core';
import { renderPage } from '@gyral/ssr';
import type { AppAssets } from '@gyral/ssr/static';
import '../src/counter.js';

/** Paths rendered at build time into dist/static. Everything else renders per request. */
export const staticPaths: readonly string[] = ['/'];

export function createApp({ components, stylesheets }: AppAssets): Hono {
  const app = new Hono();
  app.get('/', () =>
    renderPage({
      title: 'Home',
      body: html`<my-counter></my-counter>`,
      stylesheets,
      // Each page loads and preloads exactly the components it rendered.
      ...(components === undefined ? {} : { components }),
    }),
  );
  app.get('/hello/:name', (c) =>
    renderPage({ title: 'Hello', body: html`<h1>Hello, ${c.req.param('name')}</h1>` }),
  );
  return app;
}
```

```ts
// server/prod.ts
import { createServer } from 'node:http';
import { fileURLToPath } from 'node:url';
import { toNodeListener } from '@gyral/ssr/node';
import { productionServer } from '@gyral/ssr/static';
import { createApp } from './app.js';

const app = await productionServer({
  distDir: fileURLToPath(new URL('../dist', import.meta.url)),
  createApp,
});

// origin: the public origin request URLs are built on (by default, the Host header).
createServer(toNodeListener(app.fetch, { origin: 'https://example.com' })).listen(
  Number(process.env['PORT'] ?? 3000),
);
```

`productionServer({ distDir, createApp })` expects Vite's output in `dist/client/` (with
`build.manifest: true` and `gyralVitePreset({ components: true })`) and prerendered pages in
`dist/static/`. It reads the manifests once and hands `createApp` the `components` for
`renderPage` and the hashed CSS as `stylesheets`. With a client entry of your own instead, it
hands over `clientEntry` and the chunks to preload with it as `modulepreload` (Gyral's hydration
chunk included). A page whose
route module is imported lazily spreads `assets(['src/routes/product.ts'])` (also given to
`createApp`) into `renderPage` instead: it returns `{ modulepreload, stylesheets }` with that
module, its imports and its CSS added. It answers:

| Request                                  | Served from                                 | `cache-control`                       |
| ---------------------------------------- | ------------------------------------------- | ------------------------------------- |
| `GET`/`HEAD /assets/*`                   | `assetsDir` (default `dist/client/assets/`) | `public, max-age=31536000, immutable` |
| `GET`/`HEAD` of a prerendered path       | `staticDir` (default `dist/static/`)        | `public, max-age=0, must-revalidate`  |
| anything else (other `GET`s, every POST) | your app                                    | `no-cache`, unless your app set one   |

Assets carry their `content-type`, `content-length` and `x-content-type-options: nosniff`, and
stay in memory once served (up to a bound; `cache: false` reads them from disk every time). A
malformed URL is a 400. A path that leads outside `assetsDir`, or a missing file, is a 404 with
`cache-control: no-store`, so a CDN never caches a miss while a deploy lands. Pass
`staticDir: false` if nothing is prerendered, so page requests don't look for a file first.
A single `Range` request (`bytes=0-1023`) gets `206 Partial Content` with that slice, so an
imported video or audio file can seek; every asset says `accept-ranges: bytes`. A range past the
end is a 416, and several ranges or a malformed header get the whole file.

Served under a path, with Vite's `base: '/app/'`? Pass the same base to `productionServer`:
`productionServer({ distDir, createApp, base: '/app/' })` puts it in front of the entry,
preload and stylesheet URLs and serves assets at `/app/assets/`. For a static build, pass it to
the manifest helpers as their last argument:
`clientAssetsFromManifest(path, entry, [], { base: '/app/' })`.

After a deploy, tabs opened before it still ask for the old release's chunks. To keep serving
them, point `assetsDir` at a volume that keeps every release's files, or use `assetHandler`
from `@gyral/ssr/static` on its own. It answers under `/assets/` and returns `undefined` for
any other path, so it fits in front of any router:

```ts
// server/assets.ts
import { assetHandler } from '@gyral/ssr/static';

// A volume that keeps the hashed files of every release.
const assets = assetHandler({ dir: '/srv/releases/assets' });

export async function handle(request: Request): Promise<Response> {
  return (await assets(request)) ?? new Response('Not found', { status: 404 });
}
```

`productionServer({ onResponse })` sees every response before it goes out, prerendered files and
assets included, so security headers or a cookie are one function:
`onResponse: (response) => { response.headers.set('x-frame-options', 'DENY'); return response; }`.

`productionServer` returns a plain `{ fetch }`. Mount it on Node's `http` module with
`createServer(toNodeListener(app.fetch, { origin }))` from `@gyral/ssr/node`, as above, or on any
server that takes a fetch handler, or as a route in a larger Hono app. `toNodeListener` streams
request bodies in, writes each chunk of the page only as fast as the client reads it, and aborts
`request.signal` when the client leaves. Set `origin` when your pages build absolute URLs from
the request: otherwise it comes from the `Host` header, which the client chooses.

### The client's address

A `Request` doesn't say who sent it. `toNodeListener` passes the handler a second argument,
`{ incoming, remoteAddress }`: Node's request object and the client's IP address, for rate
limits, logs and audits.

```ts
// server/rate-limit.ts
import { createServer } from 'node:http';
import { toNodeListener } from '@gyral/ssr/node';

const LIMIT = 100;
const hits = new Map<string, number>();

createServer(
  toNodeListener((_request, { remoteAddress }) => {
    const client = remoteAddress ?? 'unknown';
    const count = (hits.get(client) ?? 0) + 1;
    hits.set(client, count);
    return count > LIMIT
      ? new Response('Too many requests', { status: 429, headers: { 'retry-after': '60' } })
      : new Response('ok');
  }),
).listen(3000);
```

- **Behind a proxy or a load balancer, `remoteAddress` is the proxy's address.** The client's is
  in a header such as `X-Forwarded-For`, but anyone can send that header. Read it only when the
  request came from a proxy you run (`remoteAddress` is that proxy's address), and take the
  address your proxy added, the last one in the list, not the first.
- **`remoteAddress` is `undefined` once the connection has closed**, so give it a fallback.
- **A Hono app gets the object as `c.env`**, the shape Hono's own Node adapter passes, so
  `getConnInfo(c)` from `@hono/node-server/conninfo` works with it.

## Bun, Deno and Cloudflare Workers

`renderPage` returns a web-standard `Response` (chunked, from a synchronous render), so
per-request rendering fits any runtime that speaks `fetch`:

```js
// Bun
Bun.serve({ fetch: app.fetch });

// Deno
Deno.serve(app.fetch);

// Cloudflare Workers
export default { fetch: app.fetch };
```

How far each one is tested today:

- **Bun**: `renderPage` with Declarative Shadow DOM output and `contentSecurityPolicy()` were
  checked by hand on Bun 1.3.14 with Gyral 0.3. It isn't part of Gyral's CI.
- **Deno 2.9.6**: the same self-contained SSR bundle passes native stream chunking,
  declarative shadow roots, slotted content, request-store isolation, CSP and cancellation
  checks without a DOM shim or runtime permissions.
- **Cloudflare Workers**: those checks pass in local workerd through Wrangler 4.147.0, with
  compatibility date `2025-01-01` and no `nodejs_compat` flag. This verifies the local runtime;
  deployed bindings, asset hosting and edge behavior still need your application's checks.
- **`@gyral/ssr/static`** (`prerender`, `productionServer`, `assetHandler`) reads and writes
  files with `node:fs`. Use it in Node at build time; on an edge runtime, serve the static files
  from the platform's asset hosting instead. **`@gyral/ssr/node`** is for Node's `http` module
  only; the runtimes above take `app.fetch` directly.

Run the networked `pnpm verify:platforms` in the framework repository to reproduce the Deno
and workerd checks. The
[spike report](https://github.com/gyraljs/gyral/blob/v0.3.6/docs/references/platform-spikes-2026-10-11.md)
describes the tested boundary.

## Cache headers

`productionServer` and `assetHandler` set these for you:

| Response                           | `cache-control`                       |
| ---------------------------------- | ------------------------------------- |
| content-hashed files (`/assets/*`) | `public, max-age=31536000, immutable` |
| prerendered pages                  | `public, max-age=0, must-revalidate`  |
| pages rendered per request         | `no-cache`, unless your app set one   |
| misses and errors                  | `no-store`                            |

Writing your own server, set the header on the `Response`, as `renderPage(options, { headers:
{ 'cache-control': 'no-cache' } })`.

## Content Security Policy

Gyral works under a strict policy:

- **No `'unsafe-eval'`.** This website's components hydrate and run under a policy without it,
  and its build fails on any CSP violation.
- **No inline scripts.** Hydration seeds are `data-gyral-seed` attributes, not script
  elements, and your client entry is a module file.
- **No `'unsafe-inline'` for styles.** Declarative Shadow DOM writes each component's styles as
  a `<style>` element inside its `<template>`, and `renderPage`'s `styles` option writes
  `<style>` in the head. `renderPage({ csp: { directives } })` lists all of them by hash in the
  header it sends, and `contentSecurityPolicy()` from `@gyral/ssr` builds the same value for a
  static headers file (see [Server rendering](https://gyral.dev/docs/server-rendering/#content-security-policy)).

A good starting point, with the hashes appended by Gyral:

```text
Content-Security-Policy: default-src 'self'; script-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; object-src 'none'; style-src 'self' 'sha256-…'
```

This website's policy is the same, plus `font-src` and `connect-src` for its own files and
`'wasm-unsafe-eval'`, which only its search index needs. Linked stylesheets need no hash:
`style-src 'self'` allows them. `style="…"` attributes in server HTML are the one thing the
policy blocks: they apply only once their component hydrates (see
[Styling](https://gyral.dev/docs/styling/#inline-styles-under-a-strict-csp)), so this site's pages have none. On
GitHub Pages, which can't set headers, put the policy in a
`<meta http-equiv="Content-Security-Policy">` element through `renderPage`'s `extraHead` option;
`frame-ancestors` doesn't work there.

## Checklist

- Build for production and test it before deploying: hydration problems can appear only in
  bundled builds. `@gyral/testing`'s `mountSsr` and `hydrated` make that a
  [unit test](https://gyral.dev/docs/testing/#ssr-and-hydration-tests).
- Cache hashed assets for a year and pages not at all (or with revalidation).
- Serve a CSP header: `renderPage({ csp: { directives } })` per request, or
  `contentSecurityPolicy()` written into a static host's headers file. Gyral needs no
  `'unsafe-inline'` and no `'unsafe-eval'`.

---

# Rust servers

> Serve Gyral from a Rust backend with build-time pages, with Askama pages and browser-rendered components, or with embedded server rendering through gyral-rs.

Source: https://gyral.dev/docs/rust-servers/

A Rust backend can serve a Gyral app without a Node server. Rust keeps what it already owns:
routes, sign-in, permissions, data and every write. Gyral owns the components: their HTML, their
behaviour in the browser and, when the server renders them, their hydration.

Two questions decide how the two fit together:

1. **Who writes the document?** Gyral at build time, Rust templates per request, or Gyral per
   request inside the Rust process.
2. **Does each component arrive rendered?** A server-rendered component
   [hydrates in place](https://gyral.dev/docs/server-rendering/): the browser takes over its HTML and state. A
   component that arrives as a bare tag renders for the first time in the browser.

The answers give three paths. Each one runs the same components:

| Path                                                      | Document by     | Components      |
| --------------------------------------------------------- | --------------- | --------------- |
| [Build-time pages](#build-time-pages-and-a-rust-api)      | Gyral, at build | Hydrate         |
| [Rust templates](#rust-templates-with-browser-components) | Askama          | Render in place |
| [Embedded rendering](#embedded-rendering-with-gyral-rs)   | Gyral, in Rust  | Hydrate         |

Only the third path runs JavaScript on the server, and only it needs
[`gyral-rs`](https://github.com/gyraljs/gyral-rs). The first two use Gyral exactly as this
documentation describes it, with Rust as the web server.

The examples on this page use one counter. It takes its starting count as a prop, so Rust can
set it from a template attribute or from render data:

```ts
// src/counter.ts
import { define, html, prop } from '@gyral/core';

export interface Props {
  readonly start: number;
}

export type Msg = { readonly _tag: 'Increment' };

export const Counter = define<{ readonly count: number }, Msg, Props>()('my-counter', {
  props: { start: prop.number({ default: 0 }) },
  init: (props) => ({ count: props.start }),
  intent: { Increment: true },
  update: { Increment: (s) => ({ count: s.count + 1 }) },
  view: (s, i) => html`
    <output aria-live="polite">${s.count}</output>
    <button type="button" data-intent=${i.Increment}>Increment</button>
  `,
});
```

The browser entry is the same on every path. It registers the components; Gyral then
hydrates the ones the server rendered and renders the rest:

```ts
// src/client.ts
import './counter.js';
```

## Build-time pages and a Rust API

Choose this path when a page is the same for every visitor, or when its personal data can load
after the page does. [Prerender the pages](https://gyral.dev/docs/static-sites/) as you would for any static
host. Rust then serves the output folder as files and answers the API routes the components
call, such as `/api/notes`.

Rust needs nothing from Gyral at runtime. Two things carry over from the build:

- **The Content Security Policy.** A static build computes it ahead of time, style hashes
  included ([Headers and CSP](https://gyral.dev/docs/static-sites/#headers-and-csp)). Write it to a file Rust
  reads at startup, and send it with every page.
- **Cache headers.** Content-hashed files under `/assets/` never change, so serve them with a
  long `max-age` and `immutable`. Pages need revalidation
  ([Cache headers](https://gyral.dev/docs/deploying/#cache-headers)).

Serve the pages and the API from one origin, so components call the API with relative URLs and
a policy limited to `'self'` covers them.

## Rust templates with browser components

Choose this path when ordinary HTML can carry a page's main job and its components can wait
for JavaScript. Rust renders the whole document with its own templates, so native forms post
to Rust and work with JavaScript turned off. Gyral adds interactive parts on top.

The template writes each component as a tag with ordinary attributes and readable fallback
content. With [Askama](https://github.com/askama-rs/askama), whose `{{ }}` escapes each value:

```html
<my-counter start="{{ start }}">
  <p>Starting count: {{ start }}. The button appears when JavaScript loads.</p>
</my-counter>

<script
  type="module"
  src="{{ client.path }}"
  integrity="{{ client.integrity }}"
  crossorigin="anonymous"
></script>
```

When the client entry loads, `define()` upgrades the tag, reads `start` from its attribute and
renders the counter into the component's shadow root. The browser stops showing the fallback
then. There is nothing to hydrate: the server sent a tag, not the component's HTML. Each
attribute is parsed and validated like any [prop](https://gyral.dev/docs/components/#builders-and-attributes),
so a bad value falls back to the prop's default.

Build the client with your usual bundler (the example uses esbuild). Rust serves its hashed
files and sends a policy that allows them. Components that render in the browser adopt their
styles as constructed stylesheets, so `style-src 'self'` is enough; style hashes are only for
server-rendered components. Components that read form fields, such as a live preview, observe
the native controls with a [subscription](https://gyral.dev/docs/outside-state/); the form still submits to
Rust.

The [`gyral-rs` Askama example](https://github.com/gyraljs/gyral-rs/tree/main/examples/askama-client-app)
is a complete notes app on this path: Axum routes, CSRF checks, SQLite, redirects after
writes, and a Gyral preview beside each form. It doesn't link the embedded renderer.

## Embedded rendering with gyral-rs

Choose this path when a page that changes per request must arrive with its components already
rendered, and hydrate in the browser. `gyral-rs` runs your app's own Gyral server bundle in an
embedded V8 inside the Rust process. Node builds the bundles; the running server doesn't need
it.

`gyral-rs` is **experimental**. Version 0.4 accepts bundles built with Gyral **0.3.6** exactly,
and its tested target is Linux x86_64 (GNU) with Rust 1.99. Each `gyral-rs` minor accepts one
Gyral release, so check its [changelog](https://github.com/gyraljs/gyral-rs/blob/main/CHANGELOG.md)
before you upgrade Gyral in a Rust-served app.

### The server bundle

The bundle is one script that sets two globals. Rust calls `gyralRender` with a page name and
the JSON props it approved; the function returns the page's HTML:

```ts
// src/server.ts
import { html } from '@gyral/core';
import { renderToString } from '@gyral/ssr';
import './counter.js';

// The build replaces these with the hashed client file and its integrity hash.
declare const __CLIENT_PATH__: string;
declare const __CLIENT_INTEGRITY__: string;

interface RenderInput {
  readonly page: string;
  readonly props: { readonly start: number };
}

declare global {
  var gyralBundleVersion: number;
  var gyralRender: (input: RenderInput) => Promise<string>;
}

globalThis.gyralBundleVersion = 1;
globalThis.gyralRender = ({ page, props }) => {
  if (page !== 'home') throw new Error(`Unknown page: ${page}`);
  return renderToString(
    html`<!doctype html>
      <html lang="en">
        <head>
          <meta charset="utf-8" />
          <meta name="viewport" content="width=device-width, initial-scale=1" />
          <title>Counter</title>
          <script
            type="module"
            src=${__CLIENT_PATH__}
            integrity=${__CLIENT_INTEGRITY__}
            crossorigin="anonymous"
          ></script>
        </head>
        <body>
          <main><my-counter .start=${props.start}></my-counter></main>
        </body>
      </html>`,
    { onError: 'throw' },
  );
};
```

It uses `renderToString`, not [`renderPage`](https://gyral.dev/docs/server-rendering/#renderpage): the embedded
runtime has no Fetch API, so the bundle writes its own document shell and returns a string.
`onError: 'throw'` turns a failing component into a failed render, which Rust answers with an
error page instead of a page with a hole in it.

The runtime is not Node and not a browser. It has no DOM, file system, network or `TextEncoder`,
and Gyral's style hashing needs `TextEncoder`. The
[example's server entry](https://github.com/gyraljs/gyral-rs/blob/main/examples/axum-app/web/server.mjs)
installs a small UTF-8 encoder first; copy it.

### Building the pair

Build the browser and server bundles together, from the same components and the same exact
Gyral version:

- **Browser**: one self-contained ES module from `src/client.ts`, named by its SHA-256 hash.
- **Server**: one IIFE from `src/server.ts` with every import bundled in, `platform: 'neutral'`,
  and the client's path and integrity hash defined into it.
- **Manifest**: `manifest.json` with the bundle ABI (`1`), the Gyral version, both hashes and
  the style hashes from `styleHashes()`.

The renderer loads no modules at runtime, so split chunks and dynamic `import()` are not
supported. The [example's build script](https://github.com/gyraljs/gyral-rs/blob/main/tools/build-example.mjs)
does all three steps with esbuild in about fifty lines.

### The Rust side

Add the crate with its Axum adapter (`cargo add gyral --features axum`). At startup, verify the
three files as one set and start a renderer:

```rust
let artifacts = Arc::new(AppArtifacts::try_new(manifest, server_js, client_js)?);
let policy = DocumentPolicy::try_new(artifacts.manifest())?;
let (renderer, worker) = Renderer::start(artifacts.bundle().clone())?;
```

A handler loads the data, checks access, and renders with only what the browser may see:

```rust
let request = RenderRequest::try_new(PageId::try_from("home".to_owned())?, json!({ "start": 5 }))?;
let response = gyral::axum::render_page(&renderer, request).await.into_response();
policy.apply(response)
```

`DocumentPolicy` sends an enforcing CSP that allows the verified client file and the
manifest's style hashes. Each render runs in a fresh V8 isolate with a deadline and a memory
budget. When the server stops, drain HTTP first, then `worker.shutdown().await` joins the
render threads. The [crate's README](https://crates.io/crates/gyral) and the
[Axum example](https://github.com/gyraljs/gyral-rs/tree/main/examples/axum-app) cover the
details: limits, overload, health checks and the native V8 build.

## Mixing paths

An app can use different paths for different pages. Its marketing pages can be prerendered,
its forms Askama, and its dashboard rendered per request, all served by one Rust process.
Build each path's components from the same source and the same Gyral version.

Within one page, the bundle contract also allows `gyralRender` to return a fragment instead of
a document, which an Askama page could include so that some components hydrate and others
render in the browser. No `gyral-rs` example or test covers this yet. If you try it, the
template has to add what the embedded document adds itself: the client script with its
integrity hash, and a policy with every component's style hashes.

## What Rust must own

Whichever path you choose:

- **Approve every value that reaches Gyral.** Props, attributes and API responses become page
  HTML and, when a component is server-rendered, hydration seeds the browser can read. Never
  put secrets or fields the visitor may not see into them.
- **Send Gyral's HTML unchanged.** Don't rewrite it or write seeds yourself; Gyral escapes
  values and owns the hydration format.
- **Send a complete CSP** that allows the client files and style hashes. See
  [Security](https://gyral.dev/docs/security/) for the policy Gyral needs.
- **Treat writes as final on the server.** A component's request can be cancelled in the browser
  after Rust committed it, so a redraw is never an authorization check.
- **Run only your own bundles.** The embedded renderer's limits bound time and memory; they
  don't make it a sandbox for untrusted JavaScript.

---

# Testing

> Test models without a DOM, components in a real browser with fake drivers and virtual time, and server-rendered pages through hydration.

Source: https://gyral.dev/docs/testing/

Gyral's loop is made of pure functions and data, so most of a component can be tested without a
browser: feed messages to `update`, look at the state and the commands. What's left, rendering
and the platform, you test in a real browser. `@gyral/testing` covers both, and works with any
test runner.

```sh
npm install -D @gyral/testing vitest
```

The examples on this page test this component: a lookup that debounces typing, then asks a
server.

```ts
// src/lookup.ts
import { define, html } from '@gyral/core';
import { get } from '@gyral/http';
import { debounce } from '@gyral/time';
import * as v from 'valibot';

const Result = v.object({ name: v.string() });

export interface State {
  readonly query: string;
  readonly found: string | undefined;
}

export type Msg =
  | { readonly _tag: 'Typed'; readonly query: string }
  | { readonly _tag: 'Search'; readonly query: string }
  | { readonly _tag: 'Found'; readonly query: string; readonly name: string }
  | { readonly _tag: 'Failed' };

export const Lookup = define<State, Msg>()('my-lookup', {
  init: () => ({ query: '', found: undefined }),
  intent: { Typed: ({ value }) => ({ _tag: 'Typed', query: value ?? '' }) },
  update: {
    Typed: (s, m) => [
      { ...s, query: m.query },
      [debounce<Msg>(300, { _tag: 'Search', query: m.query })],
    ],
    Search: (s, m) => [
      s,
      [
        get(`/api/lookup?q=${encodeURIComponent(m.query)}`, {
          schema: Result,
          key: 'lookup',
          concurrency: 'switch',
          onSuccess: (r): Msg => ({ _tag: 'Found', query: m.query, name: r.name }),
          onFailure: (): Msg => ({ _tag: 'Failed' }),
        }),
      ],
    ],
    // A late answer for an old query is ignored.
    Found: (s, m) => (m.query === s.query ? { ...s, found: m.name } : s),
    Failed: (s) => ({ ...s, found: undefined }),
  },
  view: (s, i) => html`
    <label for="q">Name</label>
    <input id="q" value=${s.query} data-intent=${i.Typed} />
    <output for="q">${s.found ?? ''}</output>
  `,
});
```

## step() and run()

`Lookup.spec` is the object passed to `define()`. `step(spec, state, msg)` runs one message
through `update`; `run(spec, messages)` folds several, starting from `init`. Both return the
state and the commands, so a test never has to unpack `[state, commands]` itself.

```ts
// src/lookup.test.ts
import { expect, it } from 'vitest';
import { http } from '@gyral/http';
import { inputsFor, resolve, run, step } from '@gyral/testing';
import { Lookup } from './lookup.js';

it('asks the server for the typed name', () => {
  const searched = step(
    Lookup.spec,
    { query: 'ada', found: undefined },
    { _tag: 'Search', query: 'ada' },
  );
  expect(inputsFor(searched.commands, http).map((r) => r.url)).toEqual(['/api/lookup?q=ada']);

  // Answer the command through its own mapper, then feed the message back.
  const request = searched.commands[0];
  if (request === undefined) throw new Error('expected a request');
  const answer = resolve(request, { name: 'Ada Lovelace' });
  if (answer === undefined) throw new Error('expected a message');
  expect(step(Lookup.spec, searched.state, answer).state.found).toBe('Ada Lovelace');
});

it('ignores answers to an older query', () => {
  const { state } = run(Lookup.spec, [
    { _tag: 'Typed', query: 'ada' },
    { _tag: 'Typed', query: 'grace' },
    { _tag: 'Found', query: 'ada', name: 'Ada Lovelace' },
  ]);
  expect(state).toEqual({ query: 'grace', found: undefined });
});
```

- `inputsFor(commands, driver)` lists the inputs of the commands for one driver, matched by
  name, so the test reads the request that would be sent.
- `outputsIn(commands, Component)` lists what a reducer sent to the parent through
  `outputs<Out>()`, typed
  by the component's output union, and `focusTargetsIn(commands)` lists where it asked focus to
  go (below).
- `resolve(command, output)` and `reject(command, error)` run a command's own mappers, so the
  test checks the exact message the component would receive.
- Framework messages step like any other: `{ _tag: 'PropsChanged', props, prev }`,
  `IntentRejected`, `StoreChanged`, `Hydrated`, `Errored`.
- `step(…, props, stores)` and `run(…, { props, stores, state })` give reducers their context.

These tests run in Node, in milliseconds, and cover most of the behaviour.

Outputs and focus requests are commands too, so a model test checks them the same way. Take a
tag editor that tells its parent about each new tag and puts focus back in its input:

```ts
// src/tag-editor.ts
import { define, focus, html, outputs } from '@gyral/core';

export type TagEditorOutput = { readonly _tag: 'TagAdded'; readonly tag: string };

const emit = outputs<TagEditorOutput>();

export interface State {
  readonly tags: readonly string[];
}

export type Msg = { readonly _tag: 'Add'; readonly tag: string };

export const TagEditor = define<State, Msg, object, TagEditorOutput>()('my-tag-editor', {
  init: () => ({ tags: [] }),
  intent: { Add: ({ value }) => ({ _tag: 'Add', tag: value ?? '' }) },
  update: {
    Add: (s, m) => [
      { tags: [...s.tags, m.tag] },
      [emit({ _tag: 'TagAdded', tag: m.tag }), focus('input', { select: true })],
    ],
  },
  view: (s, i) => html`
    <label for="tag">New tag</label>
    <input id="tag" />
    <button type="button" value="urgent" data-intent=${i.Add}>Add “urgent”</button>
    <output for="tag">${s.tags.join(', ')}</output>
  `,
});
```

```ts
// src/tag-editor.test.ts
import { expect, it } from 'vitest';
import { focusTargetsIn, outputsIn, step } from '@gyral/testing';
import { TagEditor } from './tag-editor.js';

it('tells the parent about the new tag and keeps focus in the input', () => {
  const { commands } = step(TagEditor.spec, { tags: [] }, { _tag: 'Add', tag: 'urgent' });
  expect(outputsIn(commands, TagEditor)).toEqual([{ _tag: 'TagAdded', tag: 'urgent' }]);
  expect(focusTargetsIn(commands)).toEqual([{ selector: 'input', select: true }]);
});
```

Passing the class types the result by its outputs, so a test that expects an output the
component can't send doesn't compile. Without a class, `outputsIn<TagEditorOutput>(commands)`
names the union itself. Read outputs and focus requests through these helpers, not by
filtering on driver names: those are Gyral's internals and may change.

## Views in Node

A view is a pure function of state, so its markup can be tested in Node too. `viewOf(Component,
state, { props, stores })` calls the component's view with the named intents and context it
would get on the page, without mounting it or a DOM shim. Render the result with
`renderToString` from `@gyral/ssr`, passing `{ dev: false }` so the HTML carries no
development markers:

```ts
// src/lookup.view.test.ts
import { expect, it } from 'vitest';
import { renderToString } from '@gyral/ssr';
import { viewOf } from '@gyral/testing';
import { Lookup } from './lookup.js';

it('shows the name it found', async () => {
  const markup = await renderToString(viewOf(Lookup, { query: 'ada', found: 'Ada Lovelace' }), {
    dev: false,
  });
  expect(markup).toContain('<output for="q">Ada Lovelace</output>');
});
```

This tests what the view renders for a state, nothing more. Hooks, focus, native validity and
hydration need the browser tests below.

## Browser tests

For rendering, events and focus, test the real element in a real browser. Gyral's own tests use
[Vitest browser mode](https://vitest.dev/guide/browser/) with Chromium; spread
`gyralVitePreset()` into the browser project's config.

Gyral renders on a schedule: reducers run as soon as a message arrives, and the DOM updates in a
microtask, once for every message that arrived together. **`await settled()`** from
`@gyral/core` waits until every component on the page has rendered its latest state, including
view transitions, focus commands and lazily loaded code, and until messages have stopped
arriving. Await it before you look at the DOM; there's nothing to poll.

- **It waits for chains of messages**: a driver that answers at once, a store that notifies in a
  microtask, a stream that re-arms in one, a reducer that answers with the next command. Each
  message restarts its quiet window, so you need no `await Promise.resolve()` loops before it.
- **It doesn't wait for commands that never end**, such as a store watch or a socket, only for
  the messages they deliver.
- **It never waits for timers or the network.** Answer fake drivers and advance virtual time
  first, then `await settled()`.
- **On a page that loads its components automatically**, await `componentsReady()` instead:
  it first waits until the loader has defined every rendered component, then settles.

Because it waits for the whole chain, a fake that answers at once runs to the end before
`settled()` resolves. To see an in-between state such as "Loading…", use a fake that waits for
the test (`fakeDriver(name)` without `impl`), assert, then answer it with `resolveNext`.

`mount()` from `@gyral/testing` does the setup: it creates the element, sets `drivers`, `stores`
and props before the element connects, appends it, waits for its first render, and removes it
after the test (with Vitest's globals on; otherwise call `dispose()`). Its `$` and `$$` query
the shadow root, and `type()` and `click()` fire real events, then wait for `settled()`.

```ts
// src/lookup.browser.test.ts
import { afterEach, expect, it } from 'vitest';
import { fakeHttp } from '@gyral/http/testing';
import { mount, virtualTime, type VirtualTime } from '@gyral/testing';
import { Lookup } from './lookup.js';

let time: VirtualTime | undefined;
afterEach(() => time?.restore());

it('debounces typing, then shows the answer', async () => {
  time = virtualTime();
  const http = fakeHttp(); // the real http driver over a fake fetch: schemas still decode
  const lookup = await mount(Lookup, { drivers: { http } });

  await lookup.type('input', 'ada');
  await time.advance(299);
  expect(http.requests).toHaveLength(0);
  await time.advance(1);
  expect(http.requests.map((r) => r.url)).toEqual(['/api/lookup?q=ada']);

  http.respondNext({ body: { name: 'Ada Lovelace' } });
  await time.advance(0);
  await lookup.settled();
  expect(lookup.$('output')?.textContent).toBe('Ada Lovelace');
});
```

### What a parser decides

Some decisions happen during the event itself: whether a parser calls `preventDefault()`, or
[declines](https://gyral.dev/docs/intent/#declining-passing-an-event-outward) so an outer intent gets the key. A
model test can't see them, but a browser test can, because parsers run while the event is
dispatched. Dispatch a cancelable event and read `defaultPrevented` as soon as
`dispatchEvent()` returns. Take a listbox that owns the arrow keys of its orientation prop:

```ts
// src/folder-list.ts
import { define, html, prop } from '@gyral/core';

export type Msg = { readonly _tag: 'Step'; readonly by: -1 | 1 };

export const FolderList = define<
  { readonly active: number },
  Msg,
  { readonly orientation: string }
>()('my-folder-list', {
  props: { orientation: prop.string({ default: 'vertical' }) },
  init: () => ({ active: 0 }),
  intent: {
    Step: ({ key, event }, { props }) => {
      const [back, next] =
        props.orientation === 'horizontal' ? ['ArrowLeft', 'ArrowRight'] : ['ArrowUp', 'ArrowDown'];
      const by = key === back ? -1 : key === next ? 1 : 0;
      if (by === 0) return undefined;
      event.preventDefault();
      return { _tag: 'Step', by };
    },
  },
  update: { Step: (s, m) => ({ active: Math.min(1, Math.max(0, s.active + m.by)) }) },
  view: (s, i, { props }) => html`
    <ul
      role="listbox"
      tabindex="0"
      aria-label="Folders"
      aria-orientation=${props.orientation}
      data-intent-keydown=${i.Step}
    >
      <li role="option" aria-selected=${s.active === 0}>Inbox</li>
      <li role="option" aria-selected=${s.active === 1}>Sent</li>
    </ul>
  `,
});
```

```ts
// src/folder-list.browser.test.ts
import { afterEach, expect, it } from 'vitest';
import { settled } from '@gyral/core';
import { FolderList } from './folder-list.js';

afterEach(() => {
  document.body.replaceChildren();
});

/** Presses a key on `target` and returns the event, to read what the parser decided. */
const press = (target: Element, key: string): KeyboardEvent => {
  const event = new KeyboardEvent('keydown', {
    key,
    bubbles: true,
    composed: true,
    cancelable: true,
  });
  target.dispatchEvent(event);
  return event;
};

it('takes only the arrow keys of its orientation', async () => {
  const el = new FolderList();
  el.orientation = 'horizontal';
  document.body.append(el);
  await settled();
  const list = el.shadowRoot?.querySelector('[role="listbox"]');
  if (list == null) throw new Error('missing listbox');

  expect(press(list, 'ArrowDown').defaultPrevented).toBe(false); // left to the page
  expect(press(list, 'ArrowRight').defaultPrevented).toBe(true);
  await settled();
  expect(el.state.active).toBe(1);
});
```

Props reach the parser as they are when the event fires, so setting `el.orientation` before the
key press is enough. Setting a prop to a value [equal to the current
one](https://gyral.dev/docs/components/#when-a-prop-counts-as-changed) changes nothing, though: no render and no
`PropsChanged`. A test that expects either must set a different value.

For the parser's own result, without a DOM, `parse(Component, intent, input, { props, state })`
calls one parser with its `ctx` filled in and returns the message (or `undefined` when it
declines):

```ts
// src/folder-list.node.test.ts
import { expect, it } from 'vitest';
import { parse } from '@gyral/testing';
import { FolderList } from './folder-list.js';

it('steps with the arrows of its orientation', () => {
  const event = new Event('keydown', { cancelable: true });
  const horizontal = { props: { orientation: 'horizontal' } };
  expect(parse(FolderList, 'Step', { key: 'ArrowRight', event }, horizontal)).toEqual({
    _tag: 'Step',
    by: 1,
  });
  expect(parse(FolderList, 'Step', { key: 'ArrowDown', event }, horizontal)).toBeUndefined();
});
```

## Fake drivers and commands

Substitute drivers by name, as the app would ([Effects](https://gyral.dev/docs/effects/#substituting-drivers)):

- **`el.drivers = { http }`** for one element.
- **`provideDrivers(root, drivers)`** from `@gyral/core` for every component under a container,
  including nested components in shadow roots, as the app itself would at its entry. It returns
  a function that removes the overrides.
- **`mount(Component, { drivers })`** for the element a browser test mounts.
- **`fakeDriver(driverOrName, { impl? })`** records every call and waits for the test:
  `resolveNext(output)`, `rejectNext(error)`, `emitNext(value)` for streaming drivers, or
  `calls[i].resolve(…)`. With `impl`, it answers at once. **`fakeDriver(name, run)`** is the
  short form: it answers every call with `run` and records the inputs.
- **`fakeHttp()`** from `@gyral/http/testing` is the real HTTP driver over a controllable
  `fetch`, so response schemas, status errors and JSON parsing behave as in production.
  `respondNext({ status, body })`, `reply(422, problem)` and `failNext()` answer requests.

Drivers go in as they are: any driver, a fake included, fits `el.drivers`, `mount` and
`provideDrivers` with no cast. A driver token (`defineDriver<I, O, E>('name')`, which has no
implementation of its own) is substituted the same way, by its name. When you keep a map of drivers yourself, type it as
`DriverOverrides` from `@gyral/core`. `Record<string, Driver<unknown, unknown>>` looks right but
rejects every driver with a typed input.

```ts
// src/test-drivers.ts
import type { DriverOverrides } from '@gyral/core';
import { fakeHttp } from '@gyral/http/testing';
import { fakeDriver } from '@gyral/testing';

/** What the component copied to the clipboard, for the test to read. */
export const copied: string[] = [];

export const testDrivers: DriverOverrides = {
  http: fakeHttp(),
  clipboard: fakeDriver<string, undefined>('clipboard', (text) => void copied.push(text)),
};
```

Removing an element stops its commands one microtask later, so that a move (removed and
inserted again in the same task) keeps them running. After `el.remove(); await
Promise.resolve();`, every running command's `signal.aborted` is `true`, its `abort` listeners
have run, and no later result is dispatched. Cleanup a driver runs after an `await` (a
`finally` once its promise settles) happens later still; yield again (or
`await clock.advance(0)` under `virtualTime()`) to observe it. To test a component that is
attached again after a real removal, check its subscriptions for that state:
`subscriptionsFor(Component.spec, state, props)` returns the commands it would start.

## Virtual time

`virtualTime()` replaces timers, `Date` and `requestAnimationFrame` with a virtual clock.
`advance(ms)` runs what's due and the promise work in between; `runAll()` runs every pending
timer; `restore()` puts the real clock back. It patches the platform, not Gyral, so it covers
debounces, `every`, driver timeouts and retry delays alike. Advance the clock, then
`await settled()` before you assert on the DOM.

It also works in a Vitest **node** project, where there is no `requestAnimationFrame` to fake,
so driver and polling tests that need no DOM can use it:

```ts
// test/poll.node.test.ts
import { afterEach, beforeEach, expect, it } from 'vitest';
import { virtualTime, type VirtualTime } from '@gyral/testing';

let time: VirtualTime;
beforeEach(() => {
  time = virtualTime();
});
afterEach(() => time.restore());

it('polls every 30 s', async () => {
  const seen: number[] = [];
  const id = setInterval(() => seen.push(Date.now()), 30_000);
  await time.advance(90_000);
  clearInterval(id);
  expect(seen).toHaveLength(3);
});
```

## SSR and hydration tests

A hydration test mounts real server markup in the browser, imports the component modules the
way a page load would, and checks that each component took over the server's DOM instead of
rendering again. The browser can't produce that markup itself (there, `define()` registers
elements rather than server specs), so it comes from Node, in one of two ways.

### Server markup on demand

`renderOnServer` from `@gyral/testing/vitest` is a [Vitest browser
command](https://vitest.dev/api/browser/commands): it runs in Vitest's Node process, loads your
module through the project's Vite server and renders it with Gyral's server renderer. Register
it in the browser project's config:

```ts
// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { gyralVitePreset } from '@gyral/core/vite';
import { renderOnServer } from '@gyral/testing/vitest';

export default defineConfig({
  ...gyralVitePreset(),
  test: {
    // Your browser setup (provider, instances) as usual, plus the command.
    browser: { commands: { renderOnServer } },
  },
});
```

Then a browser test asks for the markup, mounts it, imports the component and waits for it to
hydrate:

```ts
// src/lookup-ssr.browser.test.ts
import { afterEach, describe, expect, it } from 'vitest';
import { commands } from 'vitest/browser';
import { provideDrivers, settled } from '@gyral/core';
import { fakeHttp } from '@gyral/http/testing';
import { hydrated, mountSsr, virtualTime, type MountedSsr, type VirtualTime } from '@gyral/testing';

let page: MountedSsr | undefined;
let time: VirtualTime | undefined;

afterEach(() => {
  time?.restore();
  page?.unmount();
});

// The first call loads the module graph on the server, which can take seconds in a busy run.
describe('the server-rendered lookup', { timeout: 60_000 }, () => {
  it('hydrates in place and answers typing', async () => {
    page = mountSsr(await commands.renderOnServer({ module: './lookup.ts', export: 'Lookup' }));
    const host = page.root.querySelector('my-lookup');
    const input = host?.shadowRoot?.querySelector('input');
    const http = fakeHttp();
    provideDrivers(page.root, { http });

    await import('./lookup.js'); // import after mounting, as a real page load would
    await hydrated(page);
    expect(host?.shadowRoot?.querySelector('input')).toBe(input); // the server's node, adopted

    time = virtualTime();
    if (input == null) throw new Error('missing input');
    input.value = 'ada';
    input.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
    await time.advance(300);
    http.respondNext({ body: { name: 'Ada Lovelace' } });
    await time.advance(0);
    await settled();
    expect(host?.shadowRoot?.querySelector('output')?.textContent).toBe('Ada Lovelace');
  });
});
```

- **`module`** is relative to the test file. **`export`** names a `define()` class (rendered
  with `props`, which must be JSON), a function of `props` that returns a template, an HTML
  string or a `Response` (a whole page from `renderPage`, store seed included), or a template.
- The server keeps modules loaded between calls, like a dev server, so pass what a render needs
  as `props`. Give the tests that make the first call a long timeout, as above.
- If your `tsconfig.json` doesn't include `vitest.config.ts`, add
  `import type {} from '@gyral/testing/vitest';` to the test for the command's types.

### A golden fixture

When the markup needs your whole server (routing, data loading, the page shell), or when you
want markup changes to show up in review, render the page in a Node test and keep the output as
a file:

```ts
// src/lookup-page.node.test.ts
import { expect, it } from 'vitest';
import { html } from '@gyral/core';
import { renderPage } from '@gyral/ssr';
import './lookup.js';

it('renders the lookup page', async () => {
  const response = renderPage({
    title: 'Lookup',
    body: html`<main><my-lookup></my-lookup></main>`,
    scripts: ['/src/entry-client.ts'],
  });
  await expect(await response.text()).toMatchFileSnapshot('./fixtures/lookup-page.html');
});
```

`vitest -u` rewrites the file. The browser test imports it with `?raw`:

```ts
// src/page.browser.test.ts
import { expect, it } from 'vitest';
import { hydrated, mountSsr } from '@gyral/testing';
import pageHtml from './fixtures/lookup-page.html?raw';

it('hydrates the server page in place', async () => {
  const page = mountSsr(pageHtml);
  const before = page.root.querySelector('my-lookup');
  await import('./lookup.js'); // import after mounting, as a real page load would
  await hydrated(page);
  expect(page.root.querySelector('my-lookup')).toBe(before); // same element: no re-render
  page.unmount();
});
```

### mountSsr() and hydrated()

- **`mountSsr(html)`** parses Declarative Shadow DOM, applies only the `<head>` styles, restores
  the store seed and `<meta>` tags, and starts recording console errors.
- **`hydrated(page)`** waits until every component, including nested ones, has hydrated (it
  awaits `settled()`). It fails on a hydration mismatch, on any console error or warning since
  mounting, and on a server-rendered element whose module was never imported. Islands keep
  waiting unless you pass `{ releaseIslands: true }`.
- Render the markup with development output (Vitest does by default) and the browser also
  checks each template's id while hydrating. Run the hydration tests against a production build
  of your components too: production hydration recovers from a mismatch instead of throwing, so
  only a warning shows it.

## Testing stores

`stepStore(store, state, msg)` runs a store reducer, `store.instance(initial)` gives a test its
own instance (`mount(Cart, { stores: { cart: instance } })`), and `inputsFor(commands, store)`
lists the messages a reducer sent to a store.

## Coverage

Keep `gyralVitePreset()` in the tested project and name your sources in Vitest's coverage
settings: `test: { coverage: { provider: 'v8', include: ['src/**/*.ts'] } }`. Install
`@vitest/coverage-v8` at the same version as Vitest.

In development and tests, the preset records where each `html` and `svg` template was written,
so errors can name the file and line. That adds no branches to your coverage report: the counts
are your own code's.

## Accessibility checks for your app

Use a browser accessibility scanner alongside component behavior tests. An app-level helper
can use Playwright and axe directly; `@gyral/testing` does not need to wrap their APIs:

```ts
// test/accessibility.ts
import assert from 'node:assert/strict';
import { AxeBuilder } from '@axe-core/playwright';
import type { Page } from 'playwright';

export async function expectAccessible(page: Page): Promise<void> {
  const result = await new AxeBuilder({ page }).analyze();
  assert.deepEqual(result.violations, []);
}
```

Install `@axe-core/playwright` and `playwright` as development dependencies. Navigate to a
built page, wait for its application-ready condition, then call the helper. Scan meaningful
states such as invalid forms and open dialogs in both color schemes. Axe traverses open
shadow roots; keep those components mounted during the scan, and check that a rule actually ran
on an element inside a shadow root, so a scan of the wrong root can't pass silently. See
[Accessibility](https://gyral.dev/docs/accessibility/) for keyboard, focus and screen-reader checks that an
automated scan cannot replace.

---

# Devtools

> Watch every message, state change and command in your app with an in-page panel that costs nothing in production builds.

Source: https://gyral.dev/docs/devtools/

Gyral's loop is data from end to end: an event becomes a message, a reducer turns it into state
and commands, a driver answers with another message. So a timeline of exactly what happened is
cheap to record. `@gyral/devtools` shows it in a panel inside your page.

```sh
npm install -D @gyral/devtools
```

## Opening the panel

Load it in development only, behind a URL parameter, so production builds never include it:

```ts
// src/devtools.ts
// Add ?devtools to the URL to open the panel. `vite build` replaces import.meta.env.DEV with
// false, so the import below disappears from production bundles.
if (import.meta.env.DEV && new URLSearchParams(location.search).has('devtools')) {
  void import('@gyral/devtools').then(({ mountDevtools }) => {
    mountDevtools({ open: true });
  });
}

export {};
```

Import that module from your client entry. Every Gyral example works this way: add `?devtools`
to an example's URL to open it.

`mountDevtools(options)` returns `{ panel, unmount }`. The options are `open` (start open),
`parent` (where to put the panel; default `document.body`) and `shortcutCode` (the key used with
Alt+Shift to toggle it; default `KeyD`).

## What it shows

- **Timeline.** Every event, newest first: components connecting, disconnecting and
  hydrating, and hydration mismatches; each message with the state before and after; each
  command as it's issued, dropped (`exhaust`), interrupted (`switch`, disconnect), settled with
  the driver's output, or failed with its error; and store messages. Filter by text or by kind.
  The last 500 events are kept.
- **Components.** The live instances, with a preview of each one's current state. Components that
  connected before the panel loaded are listed too.
- **Command lanes.** Each lane's owner, policy, last phase and how many commands are in flight,
  which makes a stuck request or an unexpected `switch` easy to spot.

Toggle the panel with its button or **Alt+Shift+D**. It is itself a Gyral component: a labelled
region with a real heading and keyboard-operable controls, in light and dark.

## Free in production

The instrumentation lives in `@gyral/core`, behind a package-internal import with a
`development` condition. Vite resolves that condition in the dev server and in Vitest, and the
production one in `vite build`, where every call site is guarded by a constant `false`. The
bundler drops the call sites and the module: a production build contains neither the hook nor
its event code.

With other bundlers, set the `development` resolve condition in development builds to get events.
Without it you get the safe default: no events.

## Building your own tools

The panel listens through a small hook. A development build of `@gyral/core` emits each event to
`globalThis.__GYRAL_DEVTOOLS__.emit(event)` when that object exists (`DEVTOOLS_GLOBAL` names
the property, and the `DevEvent` type describes the events). Both come from
`@gyral/core/internal`, which has no stability promise: the event shapes may change in any
release. Without a listener, Gyral returns
before building an event. Event payloads hold live references to elements and state: read them,
never change them.

---

# Using Gyral in other frameworks

> Gyral components are standard custom elements. Use them in plain HTML, React, Vue or Svelte - set their props and listen to their outputs.

Source: https://gyral.dev/docs/other-frameworks/

Every Gyral component is a standard custom element. Anything that can put an element on a page
can use one: plain HTML, a server template, React, Vue, Svelte. That means you can adopt Gyral
one component at a time inside an existing app.

Two things cross the boundary: **props** go in, **outputs** come out.

## The component

This picker takes a label, a maximum and a list of items, and reports which one was picked:

```ts
// src/picker.ts
import { define, each, html, intentsOf, outputs, prop, type TemplateResult } from '@gyral/core';
import * as v from 'valibot';

export type PickerOutput = { readonly _tag: 'Picked'; readonly id: string };

const emit = outputs<PickerOutput>();

type Msg = { readonly _tag: 'Pick'; readonly id: string };

const i = intentsOf<typeof Picker>();
const Item = (id: string): TemplateResult =>
  html`<li><button type="button" value=${id} data-intent=${i.Pick}>${id}</button></li>`;

export interface PickerProps {
  readonly label: string;
  readonly max: number;
  readonly items: readonly string[];
}

export const Picker = define<{ readonly picks: number }, Msg, PickerProps, PickerOutput>()(
  'my-picker',
  {
    props: {
      label: prop.string({ default: 'Pick one' }),
      max: prop.number({ default: 0 }),
      items: prop.value(v.array(v.string()), { default: [] }),
    },
    init: () => ({ picks: 0 }),
    intent: { Pick: ({ value }) => (value ? { _tag: 'Pick', id: value } : undefined) },
    update: {
      Pick: (s, m) => [{ picks: s.picks + 1 }, [emit({ _tag: 'Picked', id: m.id })]],
    },
    view: (_s, _i, { props }) => html`
      <p>${props.label} (up to ${props.max})</p>
      <ul>
        ${each(props.items, (id) => id, Item)}
      </ul>
    `,
  },
);

declare global {
  interface HTMLElementTagNameMap {
    'my-picker': InstanceType<typeof Picker>;
  }
}
```

## Props: attributes or properties

A prop declared with `prop.string`, `prop.number`, `prop.boolean` or `prop.json` can be set
either way:

- as an **attribute**, a string in HTML: `<my-picker label="Choose" max="2">`. Gyral parses it
  with the prop's builder and validates it, so `max` arrives as the number `2`, and `max="lots"`
  is logged and ignored. Attribute names are the kebab-case of the prop name: a `maxItems` prop
  reads `max-items`;
- as a **property**, any JavaScript value: `picker.max = 2`.

A prop declared with `prop.value(schema)`, like `items`, is a property only. Use that for arrays,
objects and anything else that doesn't fit in a string. Props never write attributes back.

## Outputs: the gyral-output event

A component's outputs (what its reducers return through `outputs<Out>()`, `emit` above) are
dispatched from its element as a `gyral-output` event, with the output in `event.detail`.
`@gyral/core` exports the name as `OUTPUT_EVENT`, and the types `OutputEvent<O>` and
`OutputsOf<typeof Component>` to read it. The event **bubbles but isn't composed**: it travels up
the tree the element is in, and stops at the edge of a shadow root. Inside a Gyral app it also stops
at the direct parent whose intent takes it, so a grandparent never hears a grandchild's output.

So listen on the element itself, or on any ancestor in the same tree:

```ts
// src/main.ts
import { OUTPUT_EVENT, type OutputEvent, type OutputsOf } from '@gyral/core';
import './picker.js'; // defines <my-picker>
import type { Picker } from './picker.js';

const picker = document.createElement('my-picker');
picker.setAttribute('label', 'Choose a size');
picker.items = ['S', 'M', 'L'];

picker.addEventListener(OUTPUT_EVENT, (event) => {
  const output = (event as OutputEvent<OutputsOf<typeof Picker>>).detail;
  console.log(`picked ${output.id}`);
});

document.body.append(picker);
```

If you put the element inside another shadow root, listeners outside that shadow root don't
hear it. That is what keeps a Gyral parent's children private, and why the element itself is
the reliable place to listen.

The other direction works too: any custom element talks to a Gyral parent by dispatching
`new CustomEvent(OUTPUT_EVENT, { detail: { _tag: 'Picked', id }, bubbles: true })` on itself.
The parent names it with `data-intent`, as it would a Gyral child, and reads the output from the
parser's `detail`.

These rules are checked: this website's build mounts a component like this one in a plain page
and verifies that attribute props are parsed, property props render, the output reaches the
element and the document, it doesn't leave an enclosing shadow root, and a plain custom element
reaches a Gyral parent with `OUTPUT_EVENT`.

## TypeScript

The `HTMLElementTagNameMap` entry in the component file (above) is what makes
`document.createElement('my-picker')` and `querySelector('my-picker')` return the component's
type, props included. Inside a Gyral app the Vite preset generates these entries; for components
you publish to other apps, write the entry in the component's own file, as above, so it ships in
your package's types.

## React 19

React 19 supports custom elements directly. Per React's documentation, on the client it sets a
prop as a property when the element has a property of that name, and as an attribute
otherwise; during server rendering it writes primitive values as attributes and leaves out
objects and arrays. For outputs, attach the listener yourself:

```tsx
import { useEffect, useRef } from 'react';
import './picker.js';

export function SizePicker({ onPick }: { onPick: (id: string) => void }) {
  const ref = useRef<HTMLElementTagNameMap['my-picker']>(null);
  useEffect(() => {
    const el = ref.current;
    if (el === null) return;
    el.items = ['S', 'M', 'L'];
    const listener = (e: Event) => onPick((e as CustomEvent<{ id: string }>).detail.id);
    el.addEventListener('gyral-output', listener);
    return () => el.removeEventListener('gyral-output', listener);
  }, [onPick]);
  return <my-picker ref={ref} label="Choose a size" />;
}
```

TypeScript needs to know the tag in JSX; declare it in React's `JSX.IntrinsicElements`
(`declare module 'react' { namespace JSX { interface IntrinsicElements { 'my-picker': … } } }`).

The client spike verifies React 19.2.8 assigning array properties, updating them and hearing
`gyral-output` with an exact-case `'ongyral-output'` handler passed to `createElement`.
The `ref` approach above also uses the DOM directly. React server rendering is outside that
check; see the server-rendering boundary below.

## Vue

Tell Vue's compiler which tags are custom elements, so it doesn't look for Vue components with
those names:

```js
// vite.config.js
import vue from '@vitejs/plugin-vue';

export default {
  plugins: [
    vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('my-') } } }),
  ],
};
```

Then bind properties with `.prop` (or `:items` once the element is defined) and listen with
`@gyral-output`:

```vue
<my-picker label="Choose a size" :items.prop="['S', 'M', 'L']" @gyral-output="onPick" />
```

The client spike verifies Vue 3.5.43 with `isCustomElement`, `.prop`, property updates and
`@gyral-output`.

## Svelte

Svelte sets a value as a property when the element defines that property, so import the
component's module before the markup renders. For outputs, listen on the element with
`addEventListener` in an effect, as in the React example. The client spike verifies Svelte
5.57.2 assigning and updating array properties and hearing outputs with an effect listener.

These checks run in real Chromium with `pnpm verify:platforms` in the framework repository. They
install pinned host
packages in a temporary directory, leaving Gyral's runtime dependency graph unchanged. They cover
client mounts, not each host's SSR/hydration integration. The [spike
report](https://github.com/gyraljs/gyral/blob/v0.3.6/docs/references/platform-spikes-2026-10-11.md)
records the results, fixtures and limits.

## Server rendering in another framework

Gyral's server renderer knows nothing about React's or Vue's. Inside another framework's server
render, a Gyral element is written as its tag and attributes only, and renders in the browser
once its module loads. For server-rendered Gyral components, render those pages with
[`@gyral/ssr`](https://gyral.dev/docs/server-rendering/).

---

# Using third-party web components

> Use Web Awesome, Shoelace, Material Web or any other custom element inside a Gyral view - turn its events into intents and style it through parts.

Source: https://gyral.dev/docs/third-party-components/

Component libraries built as custom elements (Web Awesome, Shoelace, Material Web, Spectrum,
or a design system of your own) work inside Gyral views, because to Gyral they're just
elements. You render them in the view, turn their events into intents, and style them through
the hooks they expose.

## Their events as intents

A library element fires its own events, such as `wa-change` or `sl-change`. Put
**`data-intent-on`** on the element to say which event fires its intent. A component listens for
every event its templates name there, so nothing else is needed.

```ts
// src/size-field.ts
import { define, html } from '@gyral/core';

export interface State {
  readonly size: string;
}

export type Msg = { readonly _tag: 'SizeChanged'; readonly size: string };

/** Reads `value` from any element that has one (library inputs usually do). */
const valueOf = (el: Element): string | undefined =>
  'value' in el && typeof el.value === 'string' ? el.value : undefined;

export const SizeField = define<State, Msg>()('my-size-field', {
  init: () => ({ size: 'M' }),
  intent: {
    SizeChanged: ({ target }) => {
      const size = valueOf(target);
      return size === undefined ? undefined : { _tag: 'SizeChanged', size };
    },
  },
  update: { SizeChanged: (_s, m) => ({ size: m.size }) },
  view: (s, i) => html`
    <sl-select
      label="Size"
      .value=${s.size}
      data-intent=${i.SizeChanged}
      data-intent-on="sl-change"
    >
      <sl-option value="S">Small</sl-option>
      <sl-option value="M">Medium</sl-option>
      <sl-option value="L">Large</sl-option>
    </sl-select>
    <p>Size: <output>${s.size}</output></p>
  `,
});
```

**Without `data-intent-on`**, Gyral treats any custom element with a `data-intent` as a child
component and waits for its `gyral-output` event, which a library element never sends. When the
event name would be bound (`data-intent-on=${…}`), write it into the attribute's name instead,
as below, so the component knows to listen for it.

The event can also go in the attribute's name: `data-intent-sl-change=${i.SizeChanged}` does
the same as the pair above, and leaves `data-intent` free for another event on the same element
(see [Intent](https://gyral.dev/docs/intent/#one-element-an-intent-per-event)). Attribute names are lower case,
so this works for event names without capitals. For a name such as `valueChange`, use
`data-intent-on="valueChange"`.

## What the parser gets

- **`target`** is the library element. Read its state from it (`value`, `checked`, …), as the
  example does. The `value` field of the intent input is only filled for native `<input>`,
  `<select>`, `<textarea>` and `<button>` elements.
- **`detail`** is the `detail` of any `CustomEvent`, so a library that sends data that way (a
  map's selected marker, a date picker's range) reaches the parser like a Gyral child's output.
  Its type is `unknown`: check it with a type guard or a schema before you use it.
- **`event`** is the raw event, if you need anything else.

A store finder whose map element dispatches `marker-select`, with the marker as `detail`:

```ts
// src/store-finder.ts
import { define, html } from '@gyral/core';

export interface Marker {
  readonly id: string;
  readonly lat: number;
  readonly lng: number;
}

const isMarker = (u: unknown): u is Marker =>
  typeof u === 'object' &&
  u !== null &&
  'id' in u &&
  typeof u.id === 'string' &&
  'lat' in u &&
  typeof u.lat === 'number' &&
  'lng' in u &&
  typeof u.lng === 'number';

export type Msg = { readonly _tag: 'Select'; readonly marker: Marker };

export const StoreFinder = define<{ readonly selected: string }, Msg>()('my-store-finder', {
  init: () => ({ selected: '' }),
  intent: {
    Select: ({ detail }) => (isMarker(detail) ? { _tag: 'Select', marker: detail } : undefined),
  },
  update: { Select: (_s, m) => ({ selected: m.marker.id }) },
  view: (s, i) => html`
    <geo-map data-intent-marker-select=${i.Select}></geo-map>
    <p>Selected store: <output>${s.selected}</output></p>
  `,
});
```

The element's events must bubble, or be dispatched on the element that carries the intent
attribute, as here.

Keep the parser the place where library specifics live: the message it returns is plain data,
so `update` and your tests never know which library you used.

This website's build checks this path: a Gyral component hosts a non-Gyral custom element,
receives its custom event through `data-intent-on` alone, and reads both `detail` and the
element. A second component receives the same event through a `data-intent-<event>` attribute.

## Styling them

Style a library element from your component's `styles`, with the hooks the library documents:

- **Custom properties** pass through shadow roots, so a library's tokens can be set on the
  element or on `:host`:
  `:host { --sl-input-border-radius-medium: 0; }`.
- **`::part()`** reaches the parts a library exposes:
  `sl-select::part(combobox) { border-color: var(--brand); }`.
- Ordinary selectors style the element itself (its host box), not its insides.

Gyral's own [theming](https://gyral.dev/docs/styling/#theming-with-custom-properties) uses the same two
mechanisms, so one set of design tokens can drive your components and the library's.

## Loading and server rendering

- Load the library in the browser, the way its docs say (usually one import per component, or
  a loader script). Its elements upgrade when their definitions arrive.
- On the server, don't import browser-only libraries. Gyral's server renderer writes a custom
  element that isn't a Gyral component as a plain element, with its attributes and children, so
  `<sl-select>` and its `<sl-option>` children arrive as plain HTML and the library upgrades
  them in the browser. Hydration leaves whatever the library renders inside it alone.
  Property bindings such as `.value=${…}` are applied in the browser only; pass anything the
  first paint needs as an attribute.
- Until the library loads, its elements aren't interactive. For anything that must work
  without JavaScript, such as a form's main fields, use native elements (`<select>`, `<input>`)
  and style them.

## Types

Libraries usually register their tags in `HTMLElementTagNameMap` when you import their types,
which lets `target instanceof` checks and `querySelector` know the element's class. Without
that, read properties defensively, as `valueOf` does above.

---

# Security

> Escape template data, protect form requests, keep secrets out of hydration seeds, and serve Gyral with a strict Content Security Policy.

Source: https://gyral.dev/docs/security/

Render untrusted text through a normal template hole:

```ts
// src/greeting.ts
import { html } from '@gyral/core';

export const greeting = (name: string) => html`<p>Hello, <bdi>${name}</bdi>.</p>`;
```

Gyral writes child strings as text and escapes them in server output. Attribute values are
escaped too. This protects the HTML boundary; it does not decide whether a URL, CSS value,
request or uploaded file is safe for your application.

## Trusted markup and URLs

`raw()` accepts trusted author HTML. It does not sanitize it. Never pass a user's comment,
translation, query parameter or network response to `raw()` without a separately chosen
sanitization policy. Use ordinary template holes for text and explicit elements for rich text.

For links from untrusted data, parse the URL at the boundary and allow only the schemes and
origins your application needs. Escaping `href` cannot make a `javascript:` URL safe. Treat
interpolated CSS, page styles and head scripts as trusted author code too. Follow the
[OWASP XSS prevention guidance](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
when choosing allowed contexts and sanitizers.

## Form requests and CSRF

Authenticate and authorize each state-changing request on the server, and validate the
submitted data there even when the browser already validated it. Browser validation improves
the interface; it is not an authorization boundary.

For a cookie-authenticated app, use your server's CSRF protection. Gyral's HTTP driver can
carry a token supplied in the document:

```ts
// src/api.ts
import { csrfFromMeta, makeHttpDriver } from '@gyral/http';

export const api = makeHttpDriver({ headers: csrfFromMeta('csrf-token') });
```

The server renders the session's token in a `meta` element named `csrf-token` and validates
the `x-csrf-token` request header. A native no-JavaScript form post needs the server's
corresponding hidden-field token mechanism. Restrict this driver to your own trusted API;
do not send a token to arbitrary destinations. `SameSite` cookies are useful defense in
depth, but are not a universal replacement for server CSRF checks. See
[OWASP's CSRF guide](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html).

## Hydration seeds and secrets

SSR sends model state, declared props and store state to the browser so hydration can resume.
Those values are public to anyone who receives the page. Keep credentials, private backend
data and privileged tokens out of them. Use JSON-safe values; functions, DOM nodes and cyclic
objects cannot be faithfully restored. Gyral diagnoses unsafe seed values and escapes JSON
for its HTML context; escaping does not make a secret private.

`defineForm(schema, { secret: [...] })` prevents named fields from being echoed in rejected
form values. Password-like fields are secret by default. This does not redact arbitrary
copies you put in state, application logs or your own error payloads. Return only the
information the browser needs. See [Forms](https://gyral.dev/docs/forms/).

## A strict Content Security Policy

The SSR package can add hashes for component and page styles while preserving your other
directives:

```ts
// server/page.ts
import { html } from '@gyral/core';
import { renderPage } from '@gyral/ssr';

export const response = renderPage({
  title: 'Account',
  body: html`<main><h1>Account</h1></main>`,
  csp: {
    directives: {
      'default-src': "'self'",
      'script-src': "'self'",
      'object-src': "'none'",
      'base-uri': "'none'",
      'frame-ancestors': "'none'",
      'trusted-types': 'gyral',
      'require-trusted-types-for': "'script'",
    },
  },
});
```

Where Trusted Types exist, Gyral parses templates through the policy named `gyral`. That
policy accepts trusted author markup; it is not a sanitizer. Allow its name in your CSP. If
the page refuses the policy, development warns; an enforced HTML sink still rejects the
operation. Support varies by browser; keep CSP's other protections in place.

### Style hashes from the build

`renderPage({ csp })` hashes the styles of the components imported by the server. A server or
proxy that only builds the header, without importing your components, can take the hashes
from the build instead. After the client build (`gyralVitePreset({ components: true })`), and
before `.vite` is deleted, `writeComponentStyleManifest` from `@gyral/ssr/static` imports the
app's component modules in a separate Node process and writes their real `<style>` hashes to a
JSON file:

```ts
// scripts/style-manifest.ts
import { writeComponentStyleManifest } from '@gyral/ssr/static';

await writeComponentStyleManifest({
  root: '.',
  clientDir: 'dist/client',
  outFile: 'dist/server/component-styles.json',
});
```

The file is `{ "schema": 1, "hashes": ["'sha256-…'"] }`. The server passes the hashes as
`componentStyleHashes`, to `contentSecurityPolicy()` or `renderPage({ csp })`:

```ts
// server/csp.ts
import { readFileSync } from 'node:fs';
import { contentSecurityPolicy } from '@gyral/ssr';

const manifest = JSON.parse(readFileSync('dist/server/component-styles.json', 'utf8')) as {
  readonly schema: 1;
  readonly hashes: readonly string[];
};

export const csp = await contentSecurityPolicy({
  componentStyleHashes: manifest.hashes,
  directives: { 'default-src': "'self'", 'script-src': "'self'", 'object-src': "'none'" },
});
```

The build runs your component modules, so they must be safe to import in Node; split a
browser-only module from its component definition first. Pass `vite` with aliases or plugins
the modules need. Ship the JSON with the HTML and assets of the same build, and regenerate it
with every release: an old hash blocks new styles.

On a static host, deliver CSP as an HTTP response header where the host allows it. A
`<meta http-equiv>` policy is the fallback for hosts that can't set headers, and it can't set
`frame-ancestors` ([Deploying](https://gyral.dev/docs/deploying/#content-security-policy)). Review the
[SSR CSP options](https://gyral.dev/docs/server-rendering/#content-security-policy) and
[style-attribute policy](https://gyral.dev/docs/styling/#inline-styles-under-a-strict-csp). Test the production
page under its actual headers rather than relying on the development server.

## Uploaded files

Use `FormData` so the browser generates the multipart boundary; do not set its content type
by hand. On the server, enforce file count and size limits, validate content, and control
storage names and download permissions. A filename or MIME type supplied by the client is
untrusted. The [file-upload recipe](https://gyral.dev/docs/forms/#file-uploads) shows the transport boundary.

---

# Accessibility

> Build Gyral views with native controls, useful labels, announced errors, predictable focus, and browser tests that cover keyboard interaction.

Source: https://gyral.dev/docs/accessibility/

Start with the element that already has the behavior you need:

```html
<form action="/search" method="get">
  <label for="query">Search products</label>
  <input id="query" name="q" type="search" />
  <button type="submit">Search</button>
</form>
```

Native controls provide keyboard behavior, focus and accessible roles. Your Gyral view keeps
those semantics while `data-intent` names the messages. Use links for navigation, buttons for
actions, labels for inputs, and `fieldset`/`legend` for related choices. A placeholder does
not replace a visible label.

## Labels and shadow roots

A label and its control must share the relevant tree. A page's `label for` cannot simply
point at an input hidden in another component's shadow root. Put the label inside the
component, or use a deliberate naming contract that copies the external label into its
accessible name. The skill's [view recipes](https://github.com/gyraljs/gyral/blob/v0.3.6/skills/gyral/references/view.md#naming-a-components-form-from-the-page)
include naming a component's form from the page; the recipe is application code, not a Gyral
export.

Test the computed accessible name in the browser. Setting a prop called `label` does not
itself guarantee the rendered control has a name. Prefer native semantics before adding ARIA;
the [WAI guidance](https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/) explains when custom
interaction patterns need more work.

## Form errors

Keep schema failures as `IntentRejected` messages and visible errors in state.
`invalid(errors)` mirrors an error to native validity and `aria-invalid` on the server and
client. Add visible error text and connect it to the control:

```ts
// src/email-control.ts
import { html, invalid } from '@gyral/core';

export const emailControl = (errors: readonly string[]) => html`
  <label for="email">Email address</label>
  <input
    id="email"
    name="email"
    type="email"
    required
    aria-describedby="email-error"
    ${invalid(errors)}
  />
  <p id="email-error">${errors.join(' ')}</p>
`;
```

For a submit failure, show a useful summary and move focus to it or the first invalid control
when that helps the user recover. Do not put every keystroke's validation message in an alert
region. See the complete [form validation example](https://gyral.dev/docs/forms/).

## Focus after an update or navigation

Return `focus(selector)` as a command. Gyral applies it after the DOM update, within the
component's own root. A heading needs `tabindex="-1"` to accept programmatic focus without
becoming a normal Tab stop. `focus(selector, { wait: true })` can wait for a target that appears
in a later render. Avoid moving focus for routine background changes.

The router's [scroll and focus options](https://gyral.dev/docs/routing/#scroll-and-focus) handle navigation
after rendering settles. Test forward navigation and back/forward traversal; preserving a
user's place and announcing a new page require different behavior. Lists should use stable
`each()` keys so focus follows the same item when rows move. Where `moveBefore()` is absent,
the renderer uses `insertBefore()`; check your application's focus-sensitive interactions on
the browsers you support.

## Announcements, language and motion

Use `output` for a computed result and a restrained status/live region for asynchronous
results that need announcing. Give a busy region `aria-busy` when appropriate. Do not announce
the whole page on every render. Use `dialog.showModal()` through the [`?modal` binding](https://gyral.dev/docs/views/#dialogs-and-popovers) for modal
interaction, and keep a visible close control and a useful accessible name.

Set the document's `lang` and text direction. Keep machine date values locale-neutral and
isolate unknown-direction names with `bdi`. Honor `prefers-reduced-motion`; Gyral skips its
view transition when reduced motion is requested, but your own CSS animations need the same
care. Color must not be the only signal of selection, errors or status.

## Verify the real interface

Use browser tests to check roles, names, keyboard actions, focus after errors, Escape/close
behavior and focus return. Run axe on the rendered document and its shadow roots; the Gyral
repository's `pnpm ui:check` runs axe, overflow and console checks across desktop/phone and
light/dark. Apps own their equivalent checks. Automated checks catch some defects; also
exercise keyboard-only and screen-reader flows for your important tasks.

See [Testing](https://gyral.dev/docs/testing/) for browser helpers and [Browser support](https://gyral.dev/docs/browser-support/)
for enhancement behavior.

---

# Performance

> Measure Gyral's production payload, rendering work and hydration cost, then use keyed rows, structural sharing and islands where they help.

Source: https://gyral.dev/docs/performance/

Measure your production page before changing its update strategy. Include the entry, static
imports and modules the page actually fetches; a small entry can still load a large set of
component, hydration and fallback chunks.

## Rendering and keyed rows

Reducers run immediately. One scheduler batches DOM work in a microtask, renders parents
before children, and runs focus and other post-render work after the commit. A message can
trigger a view even when the reducer returns the same state; unchanged binding values do not
rewrite the DOM. Keep views pure and deterministic.

Use `each(items, key, row, pick?)` for lists that insert, remove or reorder items. It skips a
row when its item reference and picked inputs are unchanged. Preserve unchanged objects in
your reducers and put changing external row inputs in `pick`; do not capture outer view state
in the row function. Development checks and the row-purity lint help detect mistakes. See
[Views](https://gyral.dev/docs/views/) and [Update](https://gyral.dev/docs/update/).

Child components receive props by property. Unchanged declared props avoid a prop-triggered
render; a child's own messages and stores can still update it. Mutating an object in place
can hide a real change, while rebuilding every unchanged object defeats structural sharing.
For a costly subtree, first isolate it as a component with explicit inputs and measure again.

## Production compilation and payload

Use `gyralVitePreset()` for production builds. It compiles template strings and binding paths
ahead of time and removes development diagnostics. A client-only app can use
`clientOnly: true` to exclude hydration machinery when no server markup needs it. This is a
build contract: do not use that option for a server-rendered page.

The repository's `pnpm size --json` measures production JavaScript with gzip level 9 and
reports the initial payload separately from all chunks. `pnpm size:check` enforces example
budgets. The [package overview](https://gyral.dev/docs/packages/#whats-inside) gives measurements of Gyral's
examples; they are examples, not a guarantee of your app's size. Compare versions with the same build options and assets.

## Hydration and loading

Hydration adopts server nodes rather than rebuilding the page. Its first view must agree with
the server's state, props, stores and formatted text. Recovery from a mismatch adds work and
can disturb user input. Read [Server rendering](https://gyral.dev/docs/server-rendering/) and use production
hydration tests, including forms edited before scripts arrive.

Choose islands when a region can wait until visible, idle or interaction. Keep initial HTML
useful and ensure keyboard users can reach the interactive part. Preload the modules a page
needs using its build manifest; avoid preloading every route just to make one navigation
faster. Automatic component loading and manual route splitting should be measured on the
whole page, including their loader and preload overhead. See
[Code splitting](https://gyral.dev/docs/code-splitting/) and [Rendering modes](https://gyral.dev/docs/rendering-modes/).

## Reproduce a speed claim

The [Gyral benchmarks](https://github.com/gyraljs/benchmarks) build the same six
client-rendered apps with Gyral from npm and with current React, Preact, Vue, Svelte, Solid and
Lit. Each run's [raw data and notes](https://github.com/gyraljs/benchmarks/tree/main/results)
describe the machine, versions and variation, so compare frameworks within one run only. They
measure small apps in one browser, not server rendering or your application.

For your page, record network payloads and a browser performance trace for the action users
care about. Separate script, layout, paint and frame wait; fewer reducer milliseconds need
not make the visible action faster. Warm up, repeat the same tasks, retain raw results and
compare in one environment. Check input correctness alongside timings. For bursty external
sources, evaluate `renderOnFrame`; discrete clicks and submits usually need the default
microtask rendering. See [Testing](https://gyral.dev/docs/testing/).

---

# Packages

> Every @gyral package, what it's for, how to install it, and the optional build tools Gyral works with.

Source: https://gyral.dev/docs/packages/

Gyral is a set of small packages under the `@gyral` scope on npm, plus `create-gyral`, which
sets up a new app. Every app needs `@gyral/core`; add the others when you need them. All nine
packages are released together with the same version number (0.3.6), are ES modules with
TypeScript types, and are published from GitHub Actions with
[npm provenance](https://docs.npmjs.com/generating-provenance-statements).

## Core

| Package       | What it gives you                                                                                                                                                                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@gyral/core` | `define()`, intents, update and commands, subscriptions, stores, forms, `subscription()`, and the view layer: `html`, `svg`, `css`, `each`, `keyed`, `raw`, hooks. `/vite` has the preset (template compiler, component loading, element typings), `/eslint` the template rules. |

```sh
npm install @gyral/core
```

`@gyral/core/storage` and `@gyral/core/indexeddb` are optional entry points in the same
package. They provide separate native [localStorage and IndexedDB drivers](https://gyral.dev/docs/browser-storage/).
Apps that do not import them carry no storage driver code.

## Optional packages

| Package           | What it gives you                                                                                                                                                                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@gyral/http`     | The `http` driver: `get`, `request`, `submitForm`, typed errors, schema decoding. `@gyral/http/testing` has `fakeHttp`.                                                                                                                                                                |
| `@gyral/router`   | Typed route tables, `listen`, `navigate`, `setHead`, browser and memory history.                                                                                                                                                                                                       |
| `@gyral/time`     | `delay`, `debounce` and `every` as commands; an app that only delays doesn't bundle `every`.                                                                                                                                                                                           |
| `@gyral/ssr`      | Server rendering: `renderPage`, `renderToString`, `contentSecurityPolicy`, `styleHashes`, `formAction`. `@gyral/ssr/static` prerenders and serves builds and writes component style hashes, `@gyral/ssr/node` mounts a fetch handler on Node's `http` and runs the development server. |
| `@gyral/testing`  | `step`, `run`, `viewOf`, `subscriptionsFor`, `outputsIn`, `mount`, `parse`, fake drivers, virtual time, `mountSsr` and `hydrated`. `@gyral/testing/vitest` renders server markup for browser tests.                                                                                    |
| `@gyral/devtools` | The in-page devtools panel, for development builds.                                                                                                                                                                                                                                    |
| `@gyral/mcp`      | An MCP server for coding agents: it searches these docs, looks up exact API signatures, reads the examples, scaffolds components and typechecks snippets against your project. Hosted at `https://mcp.gyral.dev/mcp`.                                                                  |

```sh
npm install @gyral/http @gyral/router @gyral/time
npm install @gyral/ssr
npm install -D @gyral/testing @gyral/devtools
```

The same `@gyral/http` installation includes optional `@gyral/http/sse` and
`@gyral/http/websocket` entries for [native network streams](https://gyral.dev/docs/network-streams/).
The fetch entry does not include those transports.

`@gyral/mcp` is a stdio server your agent starts with `npx -y @gyral/mcp`, from your project
directory. It answers from the docs, API and examples of its own version, bundled at build time,
so it works offline. `gyral-mcp http` runs a read-only Streamable HTTP server instead; Gyral hosts one at
`https://mcp.gyral.dev/mcp`, with no token. Setup for Claude Code,
VS Code, Cursor, Codex and other clients is in
[Use Gyral with coding agents](https://gyral.dev/docs/coding-agents/).

## create-gyral

`npm create gyral@latest` asks for a directory and a template, `basic` (client-rendered) or
`ssr` (server-rendered and hydrated), and writes an app that depends on the matching `@gyral/*`
release. [Getting started](https://gyral.dev/docs/getting-started/#create-a-project) walks through it.

## Optional peer dependencies

No Gyral package asks you to install another library at runtime. The build tools Gyral plugs
into are optional peer dependencies: install the ones you use.

| Package          | Optional peers                                                                            |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `@gyral/core`    | `vite` ^8 (preset and compiler), `eslint` 9 or 10 (the plugin), `parse5` (compiler check) |
| `@gyral/ssr`     | `vite` ^8 (the development server in `@gyral/ssr/node`)                                   |
| `@gyral/testing` | `vitest` ^4.1 or ^5 (only for `@gyral/testing/vitest`)                                    |
| `@gyral/mcp`     | `typescript` 5 or 6 (for `check_snippet`, which uses your project's compiler)             |

Validation in `@gyral/core`, `@gyral/http` and `@gyral/ssr` accepts any
[Standard Schema](https://standardschema.dev) library; Gyral depends only on its types.

Any custom element works next to Gyral components, including ones built with Lit; install that
library yourself if you use it. Upgrading an existing app? See
[Versioning and stability](https://gyral.dev/docs/versioning/).

## The Vite preset

`gyralVitePreset()` from `@gyral/core/vite` holds the settings every Gyral app needs:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { gyralVitePreset } from '@gyral/core/vite';

export default defineConfig({
  ...gyralVitePreset(),
});
```

- **`plugins`**: the template compiler, a template-locations plugin, a dev-server plugin and the
  element-typings plugin. In `vite build` the compiler checks every `html` and `svg` template,
  dependencies included, fails the build with a code frame on a rule violation, and replaces each
  template with a precompiled object, so the bundle doesn't carry the runtime template preparer. The
  dev server and Vitest keep the runtime path, which checks the same rules on first render; there
  the template-locations plugin tells the runtime where each template is written, so its errors and
  hydration mismatches name your file, line and column. With `parse5` installed, the build also
  compares each template with a full HTML parser's result. The dev-server plugin makes Vite, not
  Node, load `@gyral/*` (and your dependencies that use them) in server code under `vite dev`, so
  server rendering there gets development output and shares one copy of `@gyral/core`. If your
  config has plugins of its own, list them all: `plugins: [...gyralVitePreset().plugins, mine()]`.
- **`optimizeDeps.include`**: empty by default. If Vite discovers a dependency during the first
  browser test run and reloads the page, list it: `gyralVitePreset({ optimize: ['some-dep'] })`.
- **`clientOnly: true`**, for apps no server renders, leaves the hydration code out of the
  browser bundle. See [Client-only builds](https://gyral.dev/docs/rendering-modes/#client-only-builds).
- **`components: true`** loads each component's module once its tag is on the page, so pages
  need no client entry. See
  [Code splitting](https://gyral.dev/docs/code-splitting/#load-components-by-whats-on-the-page).
- **`types`**: the preset writes [element typings](https://gyral.dev/docs/components/#anatomy-of-define) to
  `.gyral/elements.d.ts` by scanning `src`; `types: false` turns that off.

Import `html` from `@gyral/core` wherever you write templates. The compiler follows that import,
and refuses an alias (`const h = html`) it can't follow. For Vitest browser tests, spread the
preset into each browser project's config too.

## The ESLint plugin

`@gyral/core/eslint` shows the compiler's template errors in your editor, with the same
messages, checks that `each` rows read only their arguments, and finds intent parsers no
template names:

```js
// eslint.config.js
import gyral from '@gyral/core/eslint';

export default [{ files: ['src/**/*.ts'], ...gyral.configs.recommended }];
```

`recommended` turns on `gyral/template` and `gyral/each-row-purity` as errors and
`gyral/unused-intent` as a warning. It works without Vite. See [Views](https://gyral.dev/docs/views/#checked-before-it-runs) for what the rules catch.

## What's inside

`@gyral/core` has no runtime dependencies. Its view layer was written for Gyral alone, from the
platform's own primitives: `<template>` cloning, constructable stylesheets, Declarative Shadow
DOM. Commands run on a small built-in runtime (one `AbortController` per task) that handles
cancellation, concurrency lanes and retries.

Apps ship only the features they use. `each`, `raw`, hooks, commands, stores and the prop builders
register themselves when your code first calls them, so an app that never calls one doesn't
bundle it, and the hydration code is a separate chunk that only server-rendered pages fetch.
Measured on Gyral's examples at 0.3.6 (KiB gzip, production builds with the preset):

| App                      | First load | All chunks |
| ------------------------ | ---------- | ---------- |
| hello-world              | 9.6        | 12.0       |
| hello-world, client-only | 8.5        | 8.5        |
| isomorphic (SSR)         | 15.3       | 18.3       |
| no-js-first (SSR, forms) | 19.8       | 20.0       |

"First load" is the entry chunk and what it imports statically: what a page downloads before any
lazy `import()`. The no-js-first example loads its components
[by what's on the page](https://gyral.dev/docs/code-splitting/#load-components-by-whats-on-the-page), so its first
load counts what a page with every component preloads, the hydration chunk included. Builds leave
out view transitions, the frame lane and custom states unless a module names their spec field (the
build reads your code and the packages that depend on Gyral; see [what the build
reads](https://gyral.dev/docs/rendering-modes/#what-the-build-reads)), and production builds print short
[error codes](https://gyral.dev/errors/) instead of messages. [Error handling](https://gyral.dev/docs/error-handling/), which every
app carries, costs about 0.75 KiB. The client-only row is the same app built with
[`clientOnly: true`](https://gyral.dev/docs/rendering-modes/#client-only-builds). The isomorphic example
routes, and the router's [scroll and focus handling](https://gyral.dev/docs/routing/#scroll-and-focus) costs it
about 0.5 KiB of first load; the History API code (about 0.75 KiB) loads only in browsers without
the Navigation API.

Browser code targets [Baseline](https://web.dev/baseline) "widely available" features. Newer
APIs, such as the Navigation API, URLPattern, invoker commands and View Transitions, are
feature-detected and used as enhancements.

## Known issues

- **Some markup isn't handled yet by the template checks**: `<select>` content under the new
  customizable-select parsing, CDATA in SVG, and `<noscript>` as raw text. Keep these out of
  templates, or put them in `raw()` on the server.
- **Deno and Cloudflare Workers have only had a spot check** for server rendering: a
  `renderPage` bundle ran on Deno and in a local Workers runtime, but adapters, deployed edge
  behavior, bindings and assets aren't tested (see
  [Deploying](https://gyral.dev/docs/deploying/#bun-deno-and-cloudflare-workers)).
- **Without a preload hint, the hydration chunk loads one round trip after the entry** on
  server-rendered pages. Pass `clientAssetsFromManifest()`'s `modulepreload` to `renderPage` (see
  [Static sites](https://gyral.dev/docs/static-sites/#a-static-build)); `productionServer` hands it to your app,
  with an `assets(modules)` that adds a page's lazily imported route chunks.

---

# API reference

> The public API of every Gyral package, generated from the type declarations at build time so it always matches the code.

Source: https://gyral.dev/docs/api/

Each package's page lists everything it exports, entry point by entry point: the declaration as
written in the source (function bodies left out) and its documentation comment. The pages are
generated from the packages this site is built with, every time it's built, so they can't drift
from the code.

> **Writing code? Start from working code, not from the reference.** [Recipes](https://gyral.dev/docs/recipes/)
> has a task list with filters and a signup form, with their tests, and [Forms](https://gyral.dev/docs/forms/)
> opens with a complete validated form. Adapt the closest one and check it; come here to look up
> a name an example or a compiler error shows you. Most of the types are inferred, so you rarely
> write them yourself.

| Package                                  | What's in it                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------ |
| [`@gyral/core`](https://gyral.dev/docs/api/core/)         | `define`, commands, subscriptions, stores, forms, the view layer; Vite, ESLint |
| [`@gyral/http`](https://gyral.dev/docs/api/http/)         | `get`, `request`, `submitForm`, the `http` driver; `fakeHttp` for tests        |
| [`@gyral/router`](https://gyral.dev/docs/api/router/)     | `routes`, `listen`, `navigate`, `setHead`, `makeRouter`                        |
| [`@gyral/time`](https://gyral.dev/docs/api/time/)         | `delay`, `debounce`, `every`                                                   |
| [`@gyral/ssr`](https://gyral.dev/docs/api/ssr/)           | `renderPage`, `formAction`, CSP; static generation, Node adapter, dev server   |
| [`@gyral/testing`](https://gyral.dev/docs/api/testing/)   | `step`, `run`, `mount`, `parse`, fake drivers, virtual time, `mountSsr`        |
| [`@gyral/devtools`](https://gyral.dev/docs/api/devtools/) | `mountDevtools` and the panel                                                  |

`@gyral/mcp` (an MCP server for coding agents) and `create-gyral` (the app scaffolder) aren't
in this reference; [Packages](https://gyral.dev/docs/packages/) describes them.

## Reading the reference

- **Types are the contract.** A component is `define<State, Msg, Props, Output>()(tag, spec)`;
  `ComponentSpec` in `@gyral/core` describes every field of `spec`.
- **Helper types are exported.** `Reducer`, `Variant`, `ParseResult` and `StandardSchemaV1`
  (type-only) are the types `Update`, `IntentParser` and the form helpers are
  built from, so a reducer or parser written outside a spec can be typed without copying
  Gyral's definitions.
- **Functions return data.** Command helpers such as `get`, `delay` and `navigate` return a
  `Command`, which does nothing until a reducer returns it.
- **The view layer is Gyral's own.** `html`, `css`, `each`, `keyed`, `raw`, `defineHook` and
  `nothing` are documented with the rest of `@gyral/core`; `@gyral/core/vite` is the preset and
  `@gyral/core/eslint` the template rules. Server rendering is `@gyral/ssr`.

The guides explain how the pieces fit together: start with [Components](https://gyral.dev/docs/components/).

---

# Browser support

> Gyral targets Baseline widely available browser features, with explicit fallbacks and progressive enhancement for newer platform APIs.

Source: https://gyral.dev/docs/browser-support/

Shipped browser code targets **Baseline widely available**: features supported across the
major browser engines for at least 30 months. The repository uses the Browserslist query
`baseline widely available`; compatibility lint checks JavaScript and CSS. This is a moving
feature floor, not a promise to support one permanently fixed browser version.

Custom elements, Shadow DOM, template cloning, constructable stylesheets and declarative
shadow roots are part of that floor. Gyral renders with these native primitives. Node 24+
is the repository's server/build target; browser support and server-runtime support are
separate questions.

## What happens without newer APIs

| Native enhancement      | Baseline behavior                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `URLPattern`            | A constrained literal/parameter matcher with the same supported patterns                |
| Navigation API          | Lazy History API implementation, popstate and link capture                              |
| `command`/`commandfor`  | Lazy component-scoped command shim                                                      |
| `moveBefore()`          | `insertBefore()`; test focus-sensitive moves in your app                                |
| `requestIdleCallback()` | A short timer releases the island                                                       |
| `startViewTransition()` | Ordinary rendering; reduced motion also skips the transition                            |
| `:state()`              | State enhancement is skipped; keep meaning in markup and ARIA                           |
| Popover API             | Model-driven toggling is skipped; provide an accessible inline alternative where needed |
| The `gyral` HTML policy | Ordinary string parsing when the API is absent                                          |

Gyral never installs a global browser polyfill. Substantial fallbacks are internal modules
loaded when needed; small fallbacks stay beside the native call. Capability checks for Node
or workers, such as the absence of animation frames, remain even as browser support improves.

## Removal dates

These dates follow the `web-features` 3.35.0 snapshot in
[ADR 0003](https://github.com/gyraljs/gyral/blob/v0.3.6/docs/design-docs/0003-browser-baseline.md),
adding 30 months to newly available. They are scheduled review points, not claims that the
fallback has already been removed:

| Primitive                 | Widely available date |
| ------------------------- | --------------------- |
| `Promise.withResolvers()` | 2026-09-05            |
| `AbortSignal.any()`       | 2026-09-19            |
| `AbortSignal.timeout()`   | 2026-10-18            |
| Custom states             | 2026-11-17            |
| Popover                   | 2027-07-27            |
| `URLPattern`              | 2028-03-15            |
| View Transitions          | 2028-04-14            |
| Invoker commands          | 2028-06-12            |
| Navigation API            | 2028-07-13            |
| Trusted Types             | 2028-08-24            |

`moveBefore()` and `requestIdleCallback()` have no Baseline removal date in that snapshot.
The [native-first audit](https://github.com/gyraljs/gyral/blob/v0.3.6/docs/references/native-first-audit-2026-10-11.md)
records why cancellable and virtual-time timers remain useful even when native timeout
signals become widely available.

## Your application's features

Feature-detect newer JavaScript APIs and keep a working experience when they are absent.
Guard newer CSS with `@supports`, preserving an accessible baseline layout. Do not make
essential labels, errors or interactions depend on a skipped enhancement. Check current
[Baseline data](https://web.dev/baseline) before choosing a new primitive, and test your actual
minimum browser versions.

SSR mounting in `@gyral/testing` uses `setHTMLUnsafe()` to reproduce declarative shadow roots,
so choose a test browser that supports it. The repository runs real Chromium tests in
development and production configurations. Those tests are not evidence that every app flow
has also been tested in Firefox or Safari.

---

# Versioning and stability

> Understand Gyral's 0.x API policy, package versions, how to upgrade and which entry points are internal.

Source: https://gyral.dev/docs/versioning/

Gyral is in **0.x**. A minor version can include breaking changes. Read its upgrade guide
and the package changelogs before moving to it; do not treat every 0.x minor as an
interchangeable dependency update.

## Public and internal APIs

Use documented public package entries. Entries containing `/internal` are for Gyral's own
packages and have no stability promise. A symbol being technically exported does not make
an internal entry an application API. The
[export inventory](https://github.com/gyraljs/gyral/blob/v0.3.6/docs/references/public-api-0.3.1.md)
records the public boundary of 0.3.6: every entry and what it exports.

The `@gyral/*` packages and `create-gyral` release together at a shared version. Keep core, router,
HTTP, time, testing, devtools, SSR and MCP aligned; verify your lockfile when a package manager
resolves multiple versions. The [package guide](https://gyral.dev/docs/packages/) explains what each app needs.

## Releases

These guides describe **0.3.6**, the `latest` version on npm. Every package is published
from GitHub Actions with npm provenance; install from the registry. Today npm has releases
only, under the `latest` tag.

For a released application, pin the registry version you verified and retain the lockfile.
Deploy server output and client assets from the same build: stale HTML with new component
templates can cause hydration mismatches. Versioned hashed assets help keep that agreement.

Breaking changes wait for a new minor version, and that release gets an upgrade guide in these
docs. On an older 0.3.x release? Install 0.3.6 and read the
[core changelog](https://github.com/gyraljs/gyral/blob/main/packages/core/CHANGELOG.md).

## Upgrade with evidence

1. Read the changelogs for every release between yours and the target, and the upgrade guide
   when the target is a new minor version.
2. Update packages together and install from the lockfile.
3. Run typechecking, component/browser tests and the production build.
4. Test server/client hydration, edited forms, routing and the production CSP if your app
   uses them. Check payload size for the pages whose loading matters.

The generated [API reference](https://gyral.dev/docs/api/) describes the packages installed for this site's
build. Consult the changelog for the exact version your app runs:
[core](https://github.com/gyraljs/gyral/blob/main/packages/core/CHANGELOG.md),
[HTTP](https://github.com/gyraljs/gyral/blob/main/packages/http/CHANGELOG.md),
[router](https://github.com/gyraljs/gyral/blob/main/packages/router/CHANGELOG.md),
[SSR](https://github.com/gyraljs/gyral/blob/main/packages/ssr/CHANGELOG.md) and the other package
directories. Report a regression with the versions, a small reproducer and the expected
behavior. The repository's `pnpm check` is its release-quality gate.

---

# Error codes

> Every code a production build of Gyral prints, such as G0010: what the message says, what it means and how to fix it.

Source: https://gyral.dev/errors/

Development builds of `@gyral/core` print each diagnostic in full. Production builds print a short line instead, so the message texts stay out of your bundle: `Gyral`, the code, the message’s arguments in order, and a link to this page.

```text
Gyral G0010 my-cart Add https://gyral.dev/errors/#G0010
```

Read that one as: `<my-cart>` has no update for the message `Add`. Find the code below; its message shows where each argument goes. For the full sentence, reproduce the problem in development (the dev server, tests, or a build with `--mode development`). A hydration mismatch keeps its own sentence in production and ends with its code and link.

The codes and messages are read from `@gyral/core` 0.3.6, the version this site is built with; codes are never reused.

## Components

### G0001

```text
<{tag}> is a browser element (render it on the server with @gyral/ssr).
```

Arguments: `tag`.

Outside the browser, `define()` only records your component for the server renderer, so there is no element class to construct: `new MyElement()` on the server throws this.

**Fix:** Render the component on the server through `@gyral/ssr` (`renderPage`, `renderToString`), instead of constructing it.

### G0010

```text
<{tag}> has no update for message "{message}".
```

Arguments: `tag`, `message`.

A component received a message whose `_tag` has no reducer in its `update`, so the message was dropped. It is usually a typo, or a reducer you forgot.

**Fix:** Add a reducer for the message to the component’s `update`, or stop sending it.

### G0011

```text
<{tag}> has no intent parser for data-intent="{intent}".
```

Arguments: `tag`, `intent`.

An event reached an element whose `data-intent` names an intent the component has no parser for, so the user’s action was ignored.

**Fix:** Add a parser with that name to the spec’s `intent`, or correct the name in the view (`data-intent=${i.Name}` catches typos at compile time).

### G0012

```text
<{tag}> intent parser for "{intent}" failed
```

Arguments: `tag`, `intent`.

An asynchronous intent parser rejected. The error is logged with this message, and the event produced no message.

**Fix:** Handle failures inside the parser (return a message that describes the failure, or `undefined`), or move the fallible work into a command with `onFailure`.

### G0013

```text
<{tag}> focus("{selector}") matched no focusable element.
```

Arguments: `tag`, `selector`.

A `focus(selector)` command found no element to focus in the component’s root after the render, so focus stayed where it was. Keyboard and screen reader users notice.

**Fix:** Make the selector match an element inside the component (its shadow root, or its children for `shadow: false`). Give targets that aren’t focusable, such as headings, `tabindex="-1"`.

### G0014

```text
<{tag}> is on the page, but no custom element named "{tag}" is defined {seconds} s after it loaded, so it renders nothing. If it is one of your components, import the module that calls define()('{tag}', …) from the entry; for a third-party element, load its package. Ignore this for an element defined later on purpose.
```

Arguments: `tag`, `seconds`.

Development builds look for custom-element tags on the page that nothing has defined, 3 seconds after load and again after each later `define()`. Such an element renders nothing: usually the entry never imports the module that defines it.

**Fix:** Import the component’s module from the entry (or from a module the entry imports). For a third-party element, load its package; ignore the warning for an element you define later on purpose.

## Props

### G0020

```text
<{tag}> prop "{prop}" has an asynchronous schema; it must be synchronous.
```

Arguments: `tag`, `prop`.

A prop’s Standard Schema returned a promise. Props are validated synchronously, while the element updates and renders, so they can’t wait for it.

**Fix:** Use a synchronous schema or a type guard for the prop, and do asynchronous checks in a command.

### G0021

```text
<{tag}> prop "{prop}" got an invalid value from {source}, so it is treated as missing: {issues}
```

Arguments: `tag`, `prop`, `source`, `issues`.

A prop value failed its type or its schema, so it is treated as missing and its `default` applies. Attributes are checked in every build; property sets and hydration seeds in development only.

**Fix:** Pass a value that matches the prop’s declaration (a numeric string for `prop.number`, valid JSON for `prop.json`), or loosen the schema.

### G0022

```text
<{tag}> is missing required prop(s): {props}.
```

Arguments: `tag`, `props`.

A component rendered for the first time while props declared `required` were still missing. The parent probably forgot an attribute or a property.

**Fix:** Set the prop on the element (an attribute, or `.prop=${…}`) before it renders, or give it a `default` instead of `required`.

### G0023

```text
<{tag}> declares prop(s) that shadow built-in element properties: {props}. Setting them changes platform behaviour (a prop named "hidden" hides the element). Rename them.
```

Arguments: `tag`, `props`.

A component declares props named after built-in element properties (`hidden`, `title`, `id`). The prop would replace the platform’s property, so setting it would change how the element behaves. Development throws; production warns.

**Fix:** Rename the props.

## Scheduling

### G0030

```text
gyral: a deferred callback failed
```

Arguments: none.

A callback Gyral deferred to a microtask threw: delivering a child component’s output to its parent. The parent may not have received the output.

**Fix:** Look at the error logged with this message, and make sure the parent’s `child()` mapper and any `gyral-output` listener don’t throw.

### G0031

```text
<{tag}> view failed; it shows its error view, or its previous DOM stays.
```

Arguments: `tag`.

A component’s `view` threw during a render. Gyral reports a `GyralError` (phase `view`) through its error channel and keeps rendering the other components. The component renders its `error` view if its spec has one; otherwise its DOM shows its previous state.

**Fix:** Fix the exception in the view, using the `cause` of the reported error. It is often a field read on state that has a different shape than the view expects. Give the spec an `error(failure, state)` view so users see a fallback ([Error handling](https://gyral.dev/docs/error-handling/)).

### G0032

```text
gyral: post-render work failed
```

Arguments: none.

Work that runs after a render failed: a focus command, custom states from `states`, the `Hydrated` message, or the commands `init` returned for a resumed component.

**Fix:** Fix the exception logged with this message, typically in the spec’s `states` function or the `Hydrated` reducer.

### G0033

```text
gyral: rendering did not settle in one flush (a cycle between {tags}). Components are probably feeding each other props or messages; break the cycle with a condition in update.
```

Arguments: `tags`.

Rendering didn’t settle in one flush: the named components kept re-rendering each other. Components are probably feeding each other props or messages in a cycle. Development throws; production logs it and drops the rest of the work so the page doesn’t freeze.

**Fix:** Break the cycle with a condition in `update`, for example by sending a message or changing state only when the value actually differs.

### G0034

```text
settled(): the page did not settle after {rounds} flushes or busy turns. A stream is emitting without pause, or components (or drivers) are feeding each other messages in a cycle.
```

Arguments: `rounds`.

`settled()` rejected because messages kept arriving: more than the given number of flushes or busy turns went by without a quiet moment. Something is sending messages in a cycle, or a stream emits on every turn.

**Fix:** Find the cycle and break it with a condition in `update`, or substitute the chatty driver in the test.

## Commands

### G0040

```text
{owner}: the onSuccess or onFailure mapper for driver "{driver}" threw; no message was sent.
```

Arguments: `owner`, `driver`.

A command’s `onSuccess` or `onFailure` mapper threw while turning a driver’s result into a message, so the result never reached `update`. It is reported as a `GyralError` (phase `command`), and the component’s `Errored` reducer, if any, receives it.

**Fix:** Make the mapper total: return a message, or `undefined`, for every input.

### G0041

```text
{owner}: driver "{driver}" failed and the command has no onFailure.
```

Arguments: `owner`, `driver`.

A driver failed, after any `retry()` policy, and the command has no `onFailure`. This is an error, not a warning: it is reported as a `GyralError` (phase `command`) and reaches the component’s `Errored` reducer, if any. Without one, the component can’t react: a spinner may spin forever.

**Fix:** Give the command an `onFailure` that turns the error into a message, and handle that message in `update`. Expected failures (the network, a 5xx, a refusal) should always be messages.

### G0042

```text
gyral: subscription "{name}" failed to unsubscribe
```

Arguments: `name`.

The function (or `unsubscribe()`) a `subscription()` returned threw when Gyral released the source, so the source may still be sending values or holding listeners.

**Fix:** Make the stop function that `subscribe` returns safe to call once, and return a function or an object with `unsubscribe()`.

### G0043

```text
{owner}: no driver provides "{driver}". It is a driver token: provide an implementation by name with provideDrivers(root, { {driver}: … }) or el.drivers.
```

Arguments: `owner`, `driver`.

The command’s driver is a token: `defineDriver<I, O, E>(name)` without an implementation of its own. Nothing above the component provides that name, so the command can’t run. It is reported through the error channel (phase `command`); `onFailure` isn’t called, because there was no driver to fail.

**Fix:** Provide the driver where the app starts, `provideDrivers(document.body, { name: implementation })`, or on the element with `el.drivers`. In tests, pass a fake by the same name ([Drivers the app provides](https://gyral.dev/docs/effects/#drivers-the-app-provides)).

## Stores

### G0050

```text
<{tag}> uses store "{store}" without declaring it. Add it to the spec: stores: [{store}], so the component subscribes to its changes.
```

Arguments: `tag`, `store`.

A component read a store with `ctx.read(store)`, or sent to one, without listing it in its spec. A component subscribes only to the stores it declares, so it would miss the store’s changes.

**Fix:** Declare the store in the spec, for example `stores: [cart]`.

### G0051

```text
store "{store}": the server's seed failed its schema, so it starts from init. Issues: {issues}
```

Arguments: `store`, `issues`.

The store state the server seeded into the page failed the store’s `schema`, so the browser discarded it and the store starts from `init`. The page may show different data than the server rendered.

**Fix:** Fix the state the server sends, or align the store’s `schema` with it.

### G0052

```text
unreadable {attribute} seed on {where}
```

Arguments: `attribute`, `where`.

The store seed on the page, or on a `<gyral-stores>` provider, isn’t valid JSON, so every store in it starts from `init`.

**Fix:** Let `@gyral/ssr` write the seed (`renderPage({ stores })`, or the provider’s `.instances`) instead of writing it by hand, and check that nothing rewrites or truncates the HTML on its way.

### G0053

```text
<{tag}> reads store "{store}" during a server render without a store scope. Pass the request's store instances to renderPage({ stores }) or renderToString(value, { stores }).
```

Arguments: `tag`, `store`.

A component read a store during a server render without a store scope. On the server each request needs its own store instances, and without a scope Gyral can’t tell whose state to read.

**Fix:** Render through `@gyral/ssr` and pass the request’s instances: `renderPage({ stores })` or `renderToString(value, { stores })`.

### G0054

```text
store "{store}" sends to "{target}" but is not held by a store scope (a registry, <gyral-stores> or the page default), so the message is dropped.
```

Arguments: `store`, `target`.

A store’s `update` sent a message to another store, but this store instance isn’t held by a store scope, so the message has nowhere to go and is dropped.

**Fix:** Let a scope hold the instance: the page’s default, a `<gyral-stores>` provider (`.instances=${[…]}`), or a store registry in tests.

### G0055

```text
store "{store}" has no update for message "{message}".
```

Arguments: `store`, `message`.

A store received a message whose `_tag` has no reducer in its `update`, so the message was dropped and the change you expected didn’t happen.

**Fix:** Add a reducer for the message to the store’s `update`, or correct the tag being sent.

## Hydration

### G0060

```text
<{tag}> has an unreadable {attribute}
```

Arguments: `tag`, `attribute`.

A server-rendered component’s `data-gyral-seed` isn’t valid JSON, so the browser can’t resume the server’s state: the component starts from `init`, and its first render may not match the server’s HTML.

**Fix:** Don’t edit or write `data-gyral-seed` yourself. Look for whatever changes the server’s HTML on its way: a proxy, an HTML minifier, string templating.

### G0061

```text
gyral: hydration code failed to load; rendering fresh
```

Arguments: none.

The hydration code, which loads lazily with the first server-rendered component, failed to load, so server-rendered components render fresh instead of hydrating. The page works, but redoes the server’s work. It is usually a stale deploy: a cached page that points at a chunk that no longer exists.

**Fix:** Keep the previous build’s assets online for a while after a deploy, or don’t cache HTML that points at removed chunks. The network error is logged with this message.

### G0062

```text
gyral: hydration mismatch in {host} at {path}: expected {expected}, found {found}. The server's HTML differs from the first client render: a view that isn't deterministic (Date.now(), locale), a third party that changed the DOM before scripts ran, or a stale cached page (https://gyral.dev/docs/server-rendering/#mismatches).
```

Arguments: `host`, `path`, `expected`, `found`.

The server’s HTML differs from the first client render, so the component can’t be hydrated in place. Development throws `HydrationMismatch`, naming the template’s file and line; production keeps the sentence (the component, the DOM path, what was expected and found), ends it with this code, and renders the component fresh (G0063).

**Fix:** Make the view render the same on both sides: no `Date.now()`, random numbers or locale-dependent formatting in `view` (put them in state through a command). Also rule out a browser extension or script that changed the DOM before hydration, and a stale cached page.

### G0063

```text
<{tag}> was rendered fresh after a hydration mismatch:
```

Arguments: `tag`.

Production only: after a hydration mismatch (G0062, which follows in the same warning), Gyral cleared this component and rendered it fresh. The rest of the page stays hydrated, but this component flashes and redoes the server’s work.

**Fix:** Fix the mismatch the warning describes; reproducing it in development gives the full message and the template’s location.

## Templates

### G0070

```text
gyral: an html template was not compiled: `{start}`. Under the gyral-compiled condition every html`…` must be compiled by the Gyral Vite preset.
```

Arguments: `start`.

A bundle built with the Vite preset leaves out the runtime template preparer, so every `html` template must be precompiled, and this one wasn’t. The build normally fails before this can happen.

**Fix:** Import `html` (and `svg`) from `@gyral/core`, or from a package listed in the compiler’s `sources`, and use it directly as a tag: the compiler can’t follow an alias, a call or a re-export.

### G0071

```text
gyral: template rule 11: a page shell rendered in the browser.
```

Arguments: none.

A page shell, a template with `<!doctype>`, `<html>`, `<head>` or `<body>`, was rendered in the browser. Only the server renders document-level tags. Development reports it as template rule 11, with the full explanation.

**Fix:** Render the page shell on the server with `@gyral/ssr`’s `renderPage`, and render only components in the browser.

### G0072

```text
gyral: this page's Trusted Types policy list does not allow the policy "gyral", so templates are parsed from plain strings, which works only while Trusted Types are not enforced. Add `trusted-types gyral` to the Content-Security-Policy.
```

Arguments: none.

Gyral parses template HTML and `raw()` markup through a Trusted Types policy named `gyral`. The page’s Content-Security-Policy has a `trusted-types` directive that lists allowed policy names without `gyral`, so the browser refused to create it. Gyral falls back to plain strings, which works only while the page doesn’t enforce Trusted Types (`require-trusted-types-for 'script'`). Development warns once.

**Fix:** Add `gyral` to the policy list: `trusted-types gyral` (with your own policies, if any). If you don’t use Trusted Types, remove the `trusted-types` directive.

## Error handling

### G0073

```text
<{tag}> update for "{message}" failed; the state is unchanged.
```

Arguments: `tag`, `message`.

A reducer threw while handling the named message. Nothing changed: the state stays as it was and the commands that reducer would have returned don’t run. It is reported as a `GyralError` (phase `update`), and the component’s `Errored` reducer, if any, receives it.

**Fix:** Fix the exception in that reducer, using the `cause` of the reported error. Add an `Errored` reducer if the component should show an error state ([Error handling](https://gyral.dev/docs/error-handling/)).

### G0074

```text
<{tag}> init failed; it shows its error view, or stays empty.
```

Arguments: `tag`.

A component’s `init` threw, so it has no state. It renders its `error(failure, undefined)` view if its spec has one, or stays empty. The error is reported as a `GyralError` (phase `init`).

**Fix:** Fix the exception in `init`, using the `cause` of the reported error; often a prop or seed read with an unexpected shape. Give the spec an `error` view for a visible fallback.

### G0075

```text
<{tag}> element hook failed; the other hooks still ran.
```

Arguments: `tag`.

An element hook’s `client` function threw. Gyral reported it (phase `hook`) and still ran the other hooks of that render; the element itself is in the DOM.

**Fix:** Fix the exception in the hook, using the `cause` of the reported error.

### G0076

```text
store "{store}": update for "{message}" failed; the state is unchanged.
```

Arguments: `store`, `message`.

A store’s reducer threw while handling the named message. The store’s state is unchanged and its commands don’t run. The error is reported as a `GyralError` (phase `store`); the sender isn’t affected.

**Fix:** Fix the exception in that store reducer, using the `cause` of the reported error.

### G0077

```text
store "{store}": a subscriber failed; the other subscribers were still notified.
```

Arguments: `store`.

A component that reads the store threw while handling `StoreChanged`. The other subscribers were still notified and the store’s commands still ran.

**Fix:** Fix the exception in that component’s `StoreChanged` reducer (or the code it calls), using the `cause` of the reported error.

### G0078

```text
<{tag}> failed to render on the server; it renders its error view (or nothing) and starts fresh in the browser.
```

Arguments: `tag`.

A component’s `init` or view threw during server rendering. It rendered its `error` view (or nothing), marked `data-gyral-error` and without a seed, and the rest of the page was sent; the browser starts that component fresh. `renderPage`’s `onError` received the error.

**Fix:** Fix the exception, using the error your `onError` received. Pass `onError: 'throw'` to `renderPage` if a failing component should fail the whole page instead, so the route can answer with its error page.

## Subscriptions

### G0079

```text
<{tag}> subscriptions returned two commands for lane "{lane}"; only the first runs. Give each its own `key`.
```

Arguments: `tag`, `lane`.

The component’s `subscriptions` returned two commands in the same lane: the same `key`, or no key and the same driver. Gyral keeps one running command per lane, so only the first runs. Development warns.

**Fix:** Give each subscription its own `key`, such as one per room or per URL.

### G0080

```text
<{tag}> subscriptions kept restarting: a subscription's input data changes with every message it sends (for example a timestamp or a counter in the input). Keep inputs to what should restart it; functions are ignored, so to restart on a new selector, change the key.
```

Arguments: `tag`.

A subscription restarted again and again: its input changed with every message it sent, so each new state asked for a different input, which restarted it. Gyral stops after 100 rounds rather than loop.

**Fix:** Keep a subscription’s input to what should restart it (an id, a URL), not values that its own messages change, such as a counter or a timestamp.

## Element calls

### G0085

```text
<{tag}> call("{selector}", "{method}") failed
```

Arguments: `tag`, `selector`, `method`.

A `call(selector, method, …args)` command failed after the render: no element of the component matched the selector, the element has no such method, or the method threw or rejected. The reported error’s `cause` says which. It is reported through the error channel (phase `command`).

**Fix:** Check that the element is rendered when the command runs (return the command from the reducer whose new state renders it), that the selector matches inside the component’s own tree, and that the method exists on that element.

### G0086

```text
call("{selector}", "{method}"): arguments must be plain data.
```

Arguments: `selector`, `method`.

Development checks that a `call()` command’s arguments are plain data that can be cloned (strings, numbers, arrays and plain objects). A function, an element or a class instance would make the command impossible to compare or record in a test.

**Fix:** Pass plain data, and let the element look up anything else itself.

---

# @gyral/core

> Gyral core: Model-View-Intent web components on the web platform, with their own view layer.

Source: https://gyral.dev/docs/api/core/

Gyral core: Model-View-Intent web components on the web platform, with their own view layer.

```sh
npm install @gyral/core
```

> **Writing code? Start from working code, not from this page.** [Recipes](https://gyral.dev/docs/recipes/) has a task list with filters and a signup form, with their tests; [Forms](https://gyral.dev/docs/forms/) opens with a complete validated form; [Getting started](https://gyral.dev/docs/getting-started/) builds a first component. Adapt the closest example and check it, then look a name up here when you are about to call it.

Generated from the package's type declarations. Entry points: [`@gyral/core`](#gyralcore), [`@gyral/core/storage`](#gyralcorestorage), [`@gyral/core/indexeddb`](#gyralcoreindexeddb), [`@gyral/core/vite`](#gyralcorevite), [`@gyral/core/eslint`](#gyralcoreeslint).

## `@gyral/core`

### Functions

| Name | Summary |
| --- | --- |
| [`call`](#core-call) | A command that calls `method` with `args` on the first element matching `selector` inside this component (its shadow root, or its own children in light-DOM mode) once the current update has rendered: |
| [`changed`](#core-changed) | Narrows a `StoreChanged` message to one store's typed state, or `undefined`. |
| [`child`](#core-child) | Intent parser for a child component's outputs, typed by the child's output union. |
| [`command`](#core-command) | Builds a command whose mappers are typed by the driver's input, output and error. |
| [`componentsReady`](#core-componentsready) | Resolves once every rendered tag the component loader knows (in the document and in the shadow roots of components it defined) is defined, and the page has settled. |
| [`css`](#core-css) | Component CSS: `` css`p { margin-block: ${GAP}px; }` ``. |
| [`define`](#core-define) | Compiles a Model-View-Intent spec into a custom element and registers it under `tag`. |
| [`defineDriver`](#core-definedriver) | Defines a driver. |
| [`defineForm`](#core-defineform) |  |
| [`defineHook`](#core-definehook) | Defines an element hook: a small behaviour attached to the element it sits on. |
| [`defineStore`](#core-definestore) | Defines a store. |
| [`each`](#core-each) | A keyed list. |
| [`field`](#core-field) | Intent parser for one control (pair with `data-intent-on="input"` for live checks). |
| [`fieldErrors`](#core-fielderrors) | Groups issues by field name. |
| [`focus`](#core-focus) | A command that focuses the first element matching `selector` inside this component (its shadow root, or its own children in light-DOM mode) once the current update has rendered: |
| [`form`](#core-form) | Intent parser for a `<form data-intent>` submission, validated by a schema. |
| [`html`](#core-html) | The template tag: `` html`<p>${s.text}</p>` ``. |
| [`intentsOf`](#core-intentsof) | A component's intent names as a module-level constant, so pure list rows can name intents without passing them through `pick` (rows must be pure). |
| [`invalid`](#core-invalid) | Mirrors model errors to native validity: `setCustomValidity` and `aria-invalid`. |
| [`keyed`](#core-keyed) | Renders `value`, and replaces it with a fresh copy whenever `key` changes: a form cleared after sending, a CSS animation restarted, a child component reset. |
| [`outputs`](#core-outputs) | `emit`, typed by a component's output union (the 4th `define` type parameter), so an output of the wrong shape fails to compile. |
| [`provideDrivers`](#core-providedrivers) | Makes `element` a driver provider for every Gyral component below it (including inside shadow roots). |
| [`raw`](#core-raw) | Trusted markup from your own code (Markdown output, JSON-LD), parsed in a child hole and re-parsed only when the string changes. |
| [`retry`](#core-retry) | The same driver (same name, so substitution by name still works), with `run` retried when it rejects: up to `policy.times` more attempts, after `delayMs` (doubling from it with `backoff: 'exponential'`; a random part of it with `jitter`), and only for failures `retryIf` accepts. |
| [`send`](#core-send) | A command that sends `msg` to the component's instance of `store`. |
| [`settled`](#core-settled) | Resolves once the page is quiet: every connected Gyral host has rendered its latest state, view-transition updates have run, focus commands and outputs have been delivered, and messages have stopped arriving (a stream's next value, already on its way in a microtask, is waited for; long-lived commands themselves are not). |
| [`subscription`](#core-subscription) | A streaming driver over a source Gyral doesn't own. |
| [`svg`](#core-svg) | The SVG fragment tag: `` svg`<path d=${s.d} />` ``. |

#### `call`

```ts
function call(selector: string, method: string, ...args: readonly unknown[]): Command<never>;
```

A command that calls `method` with `args` on the first element matching `selector` inside
this component (its shadow root, or its own children in light-DOM mode) once the current
update has rendered:


```ts
Start: (s) => [{ ...s, playing: true }, [call('video', 'play')]]
Join: (s, m) => [s, [call('room-stage', 'join', m.room)]]
```

`args` must be plain data (structured-cloneable), so the command stays data a test can
compare. A missing element or method, or a method that throws or rejects, is reported
through the error channel (ADR 0024); the error's cause says which.

#### `changed`

```ts
function changed<S>(store: StoreRef<S>, msg: StoreChanged): {
    readonly state: S;
    readonly prev: S;
} | undefined;
```

Narrows a `StoreChanged` message to one store's typed state, or `undefined`.

#### `child`

```ts
function child<O extends Tagged, E extends Element, M>(source: ChildSource<O, E>, toMsg: (output: O, el: E) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;
```

Intent parser for a child component's outputs, typed by the child's output union.
`el` is the child element, for reading its props (an item id, for example).

Pass `() => Child` when the class isn't defined yet, e.g. a component that contains
itself; annotate the constant's type so TypeScript accepts the self-reference:


```ts
const Folder: GyralElementClass<State, Msg, Props, Out> = define()('x-folder', {
  intent: { Child: child(() => Folder, (out, el) => …) }, …
});
```


#### `command`

```ts
function command<I, O, E, const MS = never, const MF = MS>(driver: Driver<I, O, E>, input: I, handlers?: CommandHandlers<O, E, MS, MF>): Command<MS | MF>;
```

Builds a command whose mappers are typed by the driver's input, output and error. Without
handlers (or without `onSuccess`) it answers with no message: `command(log, line)` is a
`Command<never>`, which fits any `Command<Msg>`.

#### `componentsReady`

```ts
function componentsReady(): Promise<void>;
```

Resolves once every rendered tag the component loader knows (in the document and in the
shadow roots of components it defined) is defined, and the page has settled. Await it in
browser tests and page scripts after the loader has run (page scripts placed after it; in
tests, import `virtual:gyral/components` first).

#### `css`

```ts
function css(strings: TemplateStringsArray, ...values: readonly CssValue[]): StyleSource;
```

Component CSS: `` css`p { margin-block: ${GAP}px; }` ``. Strings and numbers are inserted as
written, so values from your own constants need no wrapper.

#### `define`

```ts
function define(): <S, M extends Tagged = never, P extends object = object, N extends string = never>(tag: string, spec: ComponentSpec<S, M, P, N>) => GyralElementClass<S, M, P, never, N>;
function define<S, M extends Tagged = never, P extends object = object, O extends Tagged = never>(): Definer<S, M, P, O>;
```

Compiles a Model-View-Intent spec into a custom element and registers it under `tag`. Two
calls (ADR 0023): the first takes the types, the second the tag and spec, from whose
`intent` keys it infers the component's intent names.


```ts
define<State, Msg>()('x-counter', { init, intent: { Increment: … }, update, view })
```

With no type arguments, `define()('x-badge', spec)` infers the state, messages, props and
intent names from the spec. Guide: https://gyral.dev/docs/components/

#### `defineDriver`

```ts
function defineDriver<I, O, E = unknown>(spec: Driver<I, O, E> | DriverToken<E> | string): Driver<I, O, E>;
```

Defines a driver. Given an implementation (`run`), it returns it as is, so literals infer
`I`, `O` and `E`. Given only a name, it returns a typed **token**: commands built from it are
typed, and it runs only when a provider (`provideDrivers`) or `el.drivers` supplies a driver of
that name. A command whose token nothing provides fails with G0043, naming the driver.

#### `defineForm`

```ts
function defineForm<Schema extends StandardSchemaV1>(schema: Schema, options?: FormOptions<Schema>): FormDefinition<Schema>;
```


#### `defineHook`

```ts
function defineHook<A extends readonly unknown[]>(spec: HookSpec<A>): (...args: A) => HookResult<A>;
```

Defines an element hook: a small behaviour attached to the element it sits on.

#### `defineStore`

```ts
function defineStore<S, M extends Tagged>(name: string, spec: StoreSpec<S, M>): Store<S, M>;
```

Defines a store. `name` keys it in registries, seeds and overrides, so keep it unique.

#### `each`

```ts
function each<T>(items: readonly T[], key: (item: T) => string | number, row: (item: T) => ChildValue): ListResult;
function each<T, P>(items: readonly T[], key: (item: T) => string | number, row: (item: T, picked: P) => ChildValue, pick: (item: T) => P): ListResult;
```

A keyed list. `key` must give each item a unique string or number; `row`
must depend only on its arguments: a row re-renders only when its item object or its `pick`
result changes.

#### `field`

```ts
function field<Schema extends StandardSchemaV1, M>(schema: Schema, toMsg: (value: Out<Schema>) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;
```

Intent parser for one control (pair with `data-intent-on="input"` for live checks).
Validates `checked` for checkboxes and radios, otherwise `value`.

#### `fieldErrors`

```ts
function fieldErrors(issues: readonly FieldIssue[]): Readonly<Record<string, readonly string[]>>;
```

Groups issues by field name. Call it in the `IntentRejected` reducer and keep the result in
state: `invalid()` re-applies an error only when it gets a new array.

#### `focus`

```ts
function focus(selector: string, options?: FocusOptions): Command<never>;
```

A command that focuses the first element matching `selector` inside this component (its
shadow root, or its own children in light-DOM mode) once the current update has rendered:


```ts
NextPage: (s, m) => [{ ...s, page: m.page }, [focus('h2', { preventScroll: true })]]
```

Non-focusable targets (a heading) need `tabindex="-1"` in the view.

#### `form`

```ts
function form<Schema extends StandardSchemaV1, M>(definition: FormDefinition<Schema> | Schema, toMsg: (data: Out<Schema>, formData: FormData) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;
```

Intent parser for a `<form data-intent>` submission, validated by a schema. `toMsg` also
gets the raw `FormData`, for sending the submission to the server (`submitForm` in
`@gyral/http`) after it passed client-side validation.

#### `html`

```ts
const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult
```

The template tag: `` html`<p>${s.text}</p>` ``.

#### `intentsOf`

```ts
function intentsOf<C extends {
    readonly intentNames?: string;
}>(): IntentNames<NonNullable<C['intentNames']>>;
```

A component's intent names as a module-level constant, so pure list rows can name intents
without passing them through `pick` (rows must be pure). The same object
the view gets as `i`, typed by the component's class (ADR 0023). A row that names intents
this way needs an explicit return type, or the row, the view and the class infer each other
in a circle:


```ts
const i = intentsOf<typeof TodoList>();
const Row = (t: Todo): TemplateResult => html`<input value=${t.id} data-intent=${i.Toggle} />`;
```


#### `invalid`

```ts
const invalid: (errors?: Errors) => HookResult<[errors?: Errors]>
```

Mirrors model errors to native validity: `setCustomValidity` and `aria-invalid`.


```ts
<input name="email" ${invalid(s.errors.email)} />
```

The custom error clears when the control fires `input` or `change` (the user edited it), when
the bound errors become `undefined` or empty (the model cleared them), or when a submit finds
the error stale (the value changed without an event, e.g. set from code): then the error is
dropped and the form is submitted again once. An error is applied again only when a new value
arrives (keep `fieldErrors()` results in state): `client` runs only when the errors change.

#### `keyed`

```ts
function keyed(key: string | number, value: ChildValue): ListResult;
```

Renders `value`, and replaces it with a fresh copy whenever `key` changes: a form cleared
after sending, a CSS animation restarted, a child component reset.

#### `outputs`

```ts
function outputs<O extends Tagged>(): (output: O) => Command<never>;
```

`emit`, typed by a component's output union (the 4th `define` type parameter), so an
output of the wrong shape fails to compile. A module-level constant, like `intentsOf()`:


```ts
type Out = { readonly _tag: 'Picked'; readonly id: number };
const emit = outputs<Out>();
// in update: Pick: (s, m) => [s, [emit({ _tag: 'Picked', id: m.id })]]
```

Costs nothing at run time: it returns `emit` itself.

#### `provideDrivers`

```ts
function provideDrivers(element: Element, drivers: DriverOverrides): () => void;
```

Makes `element` a driver provider for every Gyral component below it (including inside
shadow roots). Returns a function that removes the overrides. Use it on a test container
or an app root; a `<gyral-drivers>` element with a `.drivers` property works the same way.

#### `raw`

```ts
function raw(html: string): RawResult;
```

Trusted markup from your own code (Markdown output, JSON-LD), parsed in a child hole and
re-parsed only when the string changes. Never pass user input.

#### `retry`

```ts
function retry<I, O, E>(driver: Driver<I, O, E>, policy: RetryPolicy<E>): Driver<I, O, E>;
```

The same driver (same name, so substitution by name still works), with `run` retried when it
rejects: up to `policy.times` more attempts, after `delayMs` (doubling from it with
`backoff: 'exponential'`; a random part of it with `jitter`), and only for failures
`retryIf` accepts. An abort (the command switched away, the component disconnected) ends it
at once and is never retried. Wrap where the driver is chosen: `provideDrivers` at app
setup, `el.drivers`, or a test fake.


```ts
const api = retry(makeHttpDriver({ baseUrl: '/api', timeoutMs: 8000 }), {
  times: 3, delayMs: 300, backoff: 'exponential', jitter: true, retryIf: retryableHttpError,
});
const feed = retry(subscription('feed', connect), { times: Infinity, delayMs: 1000 });
```


#### `send`

```ts
function send<S, M extends Tagged>(store: Store<S, M>, msg: NoInfer<M>): Command<never>;
```

A command that sends `msg` to the component's instance of `store`. Writes are commands.

#### `settled`

```ts
function settled(): Promise<void>;
```

Resolves once the page is quiet: every connected Gyral host has rendered its latest state,
view-transition updates have run, focus commands and outputs have been delivered, and
messages have stopped arriving (a stream's next value, already on its way in a microtask, is
waited for; long-lived commands themselves are not). Rejects with the loop guard's error
when rendering never settles in development (components feeding each other).


```ts
el.send({ _tag: 'Increment' });
await settled();
```


#### `subscription`

```ts
function subscription<O, I = undefined, E = unknown>(name: string, subscribe: (emit: (value: O) => void, ctx: SubscriptionContext<I>) => Unsubscribe, options?: SubscriptionOptions<E>): Driver<I, O, E>;
```

A streaming driver over a source Gyral doesn't own. `subscribe` starts listening, calls
`emit` with each value (it may emit the current value at once) and returns how to stop
(a function, or an object with `unsubscribe()`).
The subscription lasts while the command runs; aborting it (lane `switch`, disconnect)
releases the source, and emits after that are ignored. Substitute it by `name` in tests.


```ts
const cart = subscription<CartState>('cart', (emit) => {
  emit(reduxStore.getState());
  return reduxStore.subscribe(() => emit(reduxStore.getState()));
});
// subscriptions: () => [command(cart, undefined, { onSuccess: (c) => ({ _tag: 'Cart', c }) })]
```


#### `svg`

```ts
const svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult
```

The SVG fragment tag: `` svg`<path d=${s.d} />` ``. Its top level is SVG content, so it
renders only inside an `<svg>` (or another SVG element) of an html template. A whole `<svg>` graphic is written with html.

### Classes

| Name | Summary |
| --- | --- |
| [`GyralError`](#core-gyralerror) | A failure Gyral caught, with its context; `cause` is what was thrown. |

#### `GyralError`

```ts
class GyralError extends Error {
  readonly name = "GyralError";
  readonly component: string | undefined;
  readonly phase: ErrorPhase;
  readonly msg: string | undefined;
  constructor(phase: ErrorPhase, text: string, cause: unknown, component?: string, msg?: string);
}
```

A failure Gyral caught, with its context; `cause` is what was thrown.

### Constants

| Name | Summary |
| --- | --- |
| [`nothing`](#core-nothing) | Renders nothing in a child hole; removes the attribute in an attribute hole. |
| [`OUTPUT_EVENT`](#core-output_event) | Event a child component dispatches on its host to send an output up (ADR 0010); public. |
| [`prop`](#core-prop) | The prop builders. |

#### `nothing`

```ts
const nothing: typeof nothing
```

Renders nothing in a child hole; removes the attribute in an attribute hole.

#### `OUTPUT_EVENT`

```ts
const OUTPUT_EVENT: "gyral-output"
```

Event a child component dispatches on its host to send an output up (ADR 0010); public.

#### `prop`

```ts
const prop: { readonly string: Scalar<string>; readonly number: Scalar<number>; readonly boolean: <O extends boolean = boolean>(opts?: (Common & { readonly schema?: Schema<O> | undefined; } & { readonly default?: NoInfer<O> | undefined; }) | undefined) => Prop<O>; readonly json: WithSchema; readonly value: WithSchema; }
```

The prop builders.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`AnyDriver`](#core-anydriver) | Any driver, with its input type erased. |
| [`AnyStore`](#core-anystore) | Any store, with its types erased (for declarations and registries). |
| [`AnyStoreInstance`](#core-anystoreinstance) | Any store instance, with its types erased. |
| [`CallInput`](#core-callinput) | The input of a `call()` command. |
| [`ChildSource`](#core-childsource) | A child class, or a function returning it (for recursive or later-defined components). |
| [`ChildValue`](#core-childvalue) | Everything a child hole accepts. |
| [`Command`](#core-command) | A side effect described as data, plus pure mappers from its outcome to messages. |
| [`CommandHandlers`](#core-commandhandlers) | How a command's outcome becomes a message. |
| [`CommandInfo`](#core-commandinfo) |  |
| [`ComponentSpec`](#core-componentspec) | A component spec. |
| [`Concurrency`](#core-concurrency) | How commands in the same lane interact. |
| [`CssValue`](#core-cssvalue) | A `css` interpolation: inserted as written (another `css` value inserts its text). |
| [`Ctx`](#core-ctx) | Read-only context handed to every reducer and to the view (ADR 0007, 0013). |
| [`Definer`](#core-definer) | The second call of `define()`: takes the tag and the spec, infers the intent names. |
| [`Driver`](#core-driver) | Performs one kind of side effect. |
| [`DriverContext`](#core-drivercontext) |  |
| [`DriverOverrides`](#core-driveroverrides) | Drivers substituted by name (test fakes, configured instances): `el.drivers`, `provideDrivers`. |
| [`DriverToken`](#core-drivertoken) | A driver with no implementation of its own (`defineDriver<I, O, E>('session')`): commands built from it are typed by `I`, `O` and `E`, and it runs only when `provideDrivers` or `el.drivers` supplies a driver of that name (ADR 0006 addendum "Driver tokens"). |
| [`Errored`](#core-errored) | Framework message (ADR 0024): an update, an intent parser or a command of this component failed. |
| [`ErrorPhase`](#core-errorphase) | Where a failure happened. |
| [`FieldIssue`](#core-fieldissue) | One validation problem. |
| [`FieldName`](#core-fieldname) | The definition's field names, when its input is an object; otherwise any string. |
| [`FocusOptions`](#core-focusoptions) |  |
| [`FormAssociation`](#core-formassociation) | Pure model projections applied by Gyral to the host's ElementInternals (ADR 0008). |
| [`FormControlValidity`](#core-formcontrolvalidity) | Native constraint flags and a validation bubble anchor in the component's render root. |
| [`FormControlValue`](#core-formcontrolvalue) | A native submitted value, or null to omit this component from the submission. |
| [`FormDefinition`](#core-formdefinition) | A form's schema, shared by the client component and (with `@gyral/ssr`) the server route. |
| [`FormDisabled`](#core-formdisabled) | Framework message: the host or its fieldset changed the effective disabled state. |
| [`FormFields`](#core-formfields) | Submitted text values of a form (Files are dropped: they can't be re-filled). |
| [`FormOptions`](#core-formoptions) |  |
| [`FormReset`](#core-formreset) | Framework message: the owning native form was reset. |
| [`FormResult`](#core-formresult) |  |
| [`FormStateRestore`](#core-formstaterestore) | Framework message: native session restoration or autofill supplied control state. |
| [`FormValue`](#core-formvalue) |  |
| [`FormValues`](#core-formvalues) | A form's submitted text values, keyed by the definition's fields, for re-rendering the form with what was typed (sticky fields). |
| [`GyralElement`](#core-gyralelement) | The custom element `define()` produces: a plain `HTMLElement`. |
| [`GyralElementClass`](#core-gyralelementclass) |  |
| [`Head`](#core-head) | A page's head: what `renderPage()` writes on the server and `setHead()` applies on the client. |
| [`HeadLink`](#core-headlink) | A metadata `<link>`: `alternate` (with `hreflang`), `icon` (with `sizes`, `type`), `manifest` (with `crossorigin`), `prev`/`next`, … Any other attribute is written as given. |
| [`HeadMeta`](#core-headmeta) | `<meta name content>`, or `<meta property content>` (Open Graph uses `property`). |
| [`HookAttributes`](#core-hookattributes) | Attributes a hook's server half adds to the start tag (`true`: present, no value). |
| [`HookResult`](#core-hookresult) | What a hook returns in a template: `<input ${invalid(errors)}>`. |
| [`HookSpec`](#core-hookspec) |  |
| [`Hydrated`](#core-hydrated) | Framework message: the component is live in the browser (ADR 0012 addendum). |
| [`HydrateStrategy`](#core-hydratestrategy) | When a server-rendered component hydrates. |
| [`IntentInput`](#core-intentinput) | What the intent layer sees when an element's intent fires. |
| [`IntentNames`](#core-intentnames) | A component's intent names, the keys of its `intent` object, as the view's `i` and as `intentsOf<typeof C>()`, so `data-intent=${i.Increment}` is checked (ADR 0023). |
| [`IntentParser`](#core-intentparser) | Parses a platform event into one message variant, `IntentRejected`, or `undefined` to decline it: a synchronous `undefined` passes the event to the next intent outward for the same event. |
| [`IntentRejected`](#core-intentrejected) | Framework message: an intent's input failed schema validation (ADR 0008). |
| [`Intents`](#core-intents) | Intent parsers keyed by intent name (ADR 0001, ADR 0023). |
| [`JsonValue`](#core-jsonvalue) | A JSON value: what a JSON-LD block holds. |
| [`ListResult`](#core-listresult) | A keyed list for a child hole: what `each(…)` returns. |
| [`Next`](#core-next) | What a reducer (or `init`) returns: new state, optionally with commands to run. |
| [`OutputEvent`](#core-outputevent) | The `gyral-output` event a child dispatches on its host for each output (ADR 0010): `detail` is the output. |
| [`OutputsOf`](#core-outputsof) | The output union of a `define()` class: `OutputsOf<typeof Item>`. |
| [`OutputSource`](#core-outputsource) | Anything `child()` can read an output type from: a `define()` class. |
| [`ParserCtx`](#core-parserctx) | What an intent parser gets besides the input: the reducers' context plus the component's current state, read-only. |
| [`ParseResult`](#core-parseresult) | What an intent parser returns: a message, `IntentRejected` (invalid input), or `undefined` to decline the event. |
| [`ParserFor`](#core-parserfor) | The parser for intent name `K` (ADR 0023): a name that is a message tag parses into that variant; any other name is an intent of its own whose parser may produce any message. |
| [`Prop`](#core-prop) | One declared prop: what a builder returns. |
| [`PropDeclarations`](#core-propdeclarations) | The prop builders for props type `P`: one `prop.*` builder per key. |
| [`PropGuard`](#core-propguard) | A plain type guard, accepted by `prop.value` and `prop.json` in place of a schema. |
| [`PropKind`](#core-propkind) |  |
| [`PropsChanged`](#core-propschanged) | Framework message: declared props changed after the first render (ADR 0007). |
| [`PropsOf`](#core-propsof) | The props type of a table of builders: `PropsOf<typeof props>`. |
| [`RawResult`](#core-rawresult) | Trusted markup for a child hole: what `raw(html)` returns. |
| [`Reducer`](#core-reducer) | One entry of `update`: takes the state, one message (`Msg`, a variant of `M` or a framework message) and the read-only context, and returns the next state, optionally with commands that produce more `M` messages. |
| [`RetryPolicy`](#core-retrypolicy) | How `retry(driver, policy)` retries a rejected run (retry.ts). |
| [`SeedCheck`](#core-seedcheck) | The result of checking a seed against a store's schema. |
| [`ShadowOption`](#core-shadowoption) | `spec.shadow`: `true` (the default) or an object for a shadow root, `false` for light DOM. |
| [`StandardSchemaV1`](#core-standardschemav1) | The Standard Schema interface. |
| [`Stateless`](#core-stateless) | State of a component that keeps none (a pure view of its props). |
| [`Store`](#core-store) |  |
| [`StoreChanged`](#core-storechanged) | Framework message: a store this component reads changed (ADR 0013). |
| [`StoreInstance`](#core-storeinstance) | A live store: one per page on the client, one per request on the server, one per test. |
| [`StoreOverrides`](#core-storeoverrides) | Store instances substituted by store name (tests, islands). |
| [`StoreReader`](#core-storereader) | Reads a declared store's current state, typed by the store (ADR 0013). |
| [`StoreRef`](#core-storeref) | What `ctx.read()` accepts: anything that names a store and carries its state type. |
| [`StoreResolver`](#core-storeresolver) | Finds a store's instance in a scope (a registry). |
| [`StoreSpec`](#core-storespec) |  |
| [`StoreUpdate`](#core-storeupdate) | One pure reducer per message tag, like a component's `update` but without context. |
| [`Styles`](#core-styles) | What `spec.styles` accepts: `css` values, plain CSS strings (e.g. |
| [`StyleSource`](#core-stylesource) | What `css` returns: CSS text, mapped to one shared `CSSStyleSheet` in the browser. |
| [`SubscriptionContext`](#core-subscriptioncontext) |  |
| [`SubscriptionOptions`](#core-subscriptionoptions) | Driver options a subscription may set. |
| [`Tagged`](#core-tagged) | Every message is a tagged object; the tag is also the intent name used in markup. |
| [`TemplateResult`](#core-templateresult) | What `html` returns: a template plus this render's values. |
| [`Unsubscribe`](#core-unsubscribe) | How to stop listening: a function, or an object with `unsubscribe()` (RxJS, XState). |
| [`Update`](#core-update) | One pure reducer per message tag (exhaustive by construction), plus optional reducers for framework messages. |
| [`Variant`](#core-variant) | The member of message union `M` whose tag is `K`: `Variant<Msg, 'Add'>`. |

#### `AnyDriver`

```ts
type AnyDriver = Driver<never, unknown>;
```

Any driver, with its input type erased. Every `Driver<I, O, E>` (from `defineDriver`,
`subscription`, a test fake) is assignable to it as is: no cast.

#### `AnyStore`

```ts
interface AnyStore {
    readonly name: string;
    instance(initial?: never): AnyStoreInstance;
    checkSeed(seed: unknown): SeedCheck<unknown>;
}
```

Any store, with its types erased (for declarations and registries).

#### `AnyStoreInstance`

```ts
interface AnyStoreInstance {
    readonly store: AnyStore;
    readonly state: unknown;
    send(msg: never): void;
    subscribe(listener: (state: unknown, prev: unknown) => void): () => void;
    dispose(): void;
    /**
     * Called by the registry that holds this instance, so the store's `send(other, msg)`
     * commands reach `other`'s instance in the same scope.
     */
    bindScope?(resolve: StoreResolver): void;
}
```

Any store instance, with its types erased.

#### `CallInput`

```ts
interface CallInput {
    readonly selector: string;
    readonly method: string;
    readonly args: readonly unknown[];
}
```

The input of a `call()` command.

#### `ChildSource`

```ts
type ChildSource<O extends Tagged, E extends Element> = OutputSource<O, E> | (() => OutputSource<O, E>);
```

A child class, or a function returning it (for recursive or later-defined components).

#### `ChildValue`

```ts
type ChildValue = string | number | boolean | null | undefined | typeof nothing | TemplateResult | ListResult | RawResult | readonly ChildValue[];
```

Everything a child hole accepts.

#### `Command`

```ts
interface Command<M> {
    readonly driver: AnyDriver;
    readonly input: unknown;
    /** Concurrency lane. Default: the driver's name. */
    readonly key?: string;
    readonly concurrency?: Concurrency;
    readonly onSuccess: (output: unknown) => M | undefined;
    /** If omitted, a failure is reported to the error channel (ADR 0024, G0041). */
    readonly onFailure?: (error: unknown) => M | undefined;
}
```

A side effect described as data, plus pure mappers from its outcome to messages. Commands
that answer with no message (`focus()`, `call()`, `navigate()`) are `Command<never>`,
which fits wherever a `Command<Msg>` is expected: no type argument needed.

#### `CommandHandlers`

```ts
interface CommandHandlers<O, E, MS, MF = MS> {
    readonly onSuccess?: (output: O) => MS | undefined;
    readonly onFailure?: (error: E) => MF | undefined;
    readonly key?: string;
    readonly concurrency?: Concurrency;
}
```

How a command's outcome becomes a message. Every field is optional: without `onSuccess` the
command answers with nothing (`Command<never>`); without `onFailure` a failure is reported to
the error channel (ADR 0024).

#### `CommandInfo`

```ts
interface CommandInfo {
    /** The command, e.g. `--clear`. */
    readonly command: string;
    /** The invoker (the button) that sent it. */
    readonly source: Element | undefined;
}
```


#### `ComponentSpec`

```ts
type ComponentSpec<S, M extends Tagged, P, N extends string = string> = SpecBody<S, M, P, N> & IntentField<S, M, P, N> & UpdateField<S, M, P> & InitField<S, M, P>;
```

A component spec. `N` is the component's intent names, the keys of `intent` (ADR 0023).

#### `Concurrency`

```ts
type Concurrency = 'merge' | 'switch' | 'exhaust' | 'queue';
```

How commands in the same lane interact. See ADR 0006 for the table.

#### `CssValue`

```ts
type CssValue = string | number | StyleSource;
```

A `css` interpolation: inserted as written (another `css` value inserts its text).

#### `Ctx`

```ts
interface Ctx<P> {
    /** Props from above. */
    readonly props: P;
    /** Stores from the side: `read(cart).lines`. The store must be in `spec.stores`. */
    readonly read: StoreReader;
}
```

Read-only context handed to every reducer and to the view (ADR 0007, 0013).

#### `Definer`

```ts
type Definer<S, M extends Tagged, P extends object, O extends Tagged> = <N extends string = never>(tag: string, spec: ComponentSpec<S, M, P, N>) => GyralElementClass<S, M, P, O, N>;
```

The second call of `define()`: takes the tag and the spec, infers the intent names.

#### `Driver`

```ts
interface Driver<I, O, E = unknown> {
    readonly name: string;
    readonly run: (input: I, ctx: DriverContext<O>) => O | Promise<O>;
    /** Default policy for this driver's commands. Default `'merge'`. */
    readonly concurrency?: Concurrency;
    /** Turns a thrown or rejected value into this driver's typed error. */
    readonly toError?: (cause: unknown) => E;
}
```

Performs one kind of side effect. A plain object: easy to fake in tests.

#### `DriverContext`

```ts
interface DriverContext<O = unknown> {
    /** Aborts when the command is switched away or its component disconnects. */
    readonly signal: AbortSignal;
    /**
     * Delivers an extra result while the command runs (streaming drivers: routers, timers,
     * sockets). Each value goes through the command's `onSuccess`. Ignored once the command
     * has settled or been aborted. A streaming `run` usually never resolves; abort ends it.
     */
    readonly emit: (output: O) => void;
}
```


#### `DriverOverrides`

```ts
type DriverOverrides = Readonly<Record<string, AnyDriver>>;
```

Drivers substituted by name (test fakes, configured instances): `el.drivers`,
`provideDrivers`. Annotate a driver map with this type (or `Record<string, AnyDriver>`), not
`Record<string, Driver<unknown, unknown>>`, which rejects drivers with a typed input.

#### `DriverToken`

```ts
interface DriverToken<E = unknown> {
    readonly name: string;
    readonly concurrency?: Concurrency;
    readonly toError?: (cause: unknown) => E;
}
```

A driver with no implementation of its own (`defineDriver<I, O, E>('session')`): commands built
from it are typed by `I`, `O` and `E`, and it runs only when `provideDrivers` or `el.drivers`
supplies a driver of that name (ADR 0006 addendum "Driver tokens").

#### `Errored`

```ts
interface Errored {
    readonly _tag: 'Errored';
    readonly phase: 'update' | 'parse' | 'command';
    readonly error: GyralError;
}
```

Framework message (ADR 0024): an update, an intent parser or a command of this component
failed. The failure was reported (`reportError`, or claimed by an ancestor's boundary) and
changed nothing; reduce it to show an error state or to reset. A failure while reducing
`Errored` is reported and not sent again.

#### `ErrorPhase`

```ts
type ErrorPhase = 'init' | 'update' | 'view' | 'parse' | 'command' | 'hook' | 'store' | 'subscribe';
```

Where a failure happened.

#### `FieldIssue`

```ts
interface FieldIssue {
    readonly path: string;
    readonly message: string;
}
```

One validation problem. `path` is dot-joined and matches the field's `name`.

#### `FieldName`

```ts
type FieldName<Schema extends StandardSchemaV1> = In<Schema> extends Readonly<Record<string, unknown>> ? keyof In<Schema> & string : string;
```

The definition's field names, when its input is an object; otherwise any string.

#### `FocusOptions`

```ts
interface FocusOptions {
    /** Don't scroll the element into view (default `false`: the browser scrolls if needed). */
    readonly preventScroll?: boolean;
    /** Also select the text of an input or textarea. */
    readonly select?: boolean;
    /**
     * If nothing matches after this render, keep the request and focus the target as soon as a
     * later render of this component produces it; a newer `focus()` from the component replaces
     * it, and after one second it gives up with the usual warning. `settled()` doesn't wait for it.
     */
    readonly wait?: boolean;
}
```


#### `FormAssociation`

```ts
interface FormAssociation<S, P> {
    readonly value: (state: S, ctx: Ctx<P>) => FormControlValue;
    readonly state?: (state: S, ctx: Ctx<P>) => FormControlValue;
    readonly validity?: (state: S, ctx: Ctx<P>) => FormControlValidity | undefined;
}
```

Pure model projections applied by Gyral to the host's ElementInternals (ADR 0008).

#### `FormControlValidity`

```ts
interface FormControlValidity {
    readonly flags: ValidityStateFlags;
    readonly message: string;
    readonly anchor?: string;
}
```

Native constraint flags and a validation bubble anchor in the component's render root.

#### `FormControlValue`

```ts
type FormControlValue = string | File | FormData | null;
```

A native submitted value, or null to omit this component from the submission.

#### `FormDefinition`

```ts
interface FormDefinition<Schema extends StandardSchemaV1> {
    readonly _tag: 'FormDefinition';
    readonly schema: Schema;
    /** The fields listed as secret (names containing `password`, `passcode`, `csrf` or `xsrf` are secret too). */
    readonly secret: readonly string[];
    /**
     * Validates submitted form data exactly as `form()` does; the server's `formAction` uses it,
     * so both paths produce the same `IntentRejected` (`intent` defaults to `''`).
     */
    readonly validate: (data: FormData, intent?: string) => FormResult<Out<Schema>> | Promise<FormResult<Out<Schema>>>;
    /** The submitted text values without secrets: what a re-rendered form may show again. */
    readonly values: (data: FormData) => FormValues<Schema>;
}
```

A form's schema, shared by the client component and (with `@gyral/ssr`) the server route.

#### `FormDisabled`

```ts
interface FormDisabled {
    readonly _tag: 'FormDisabled';
    readonly disabled: boolean;
}
```

Framework message: the host or its fieldset changed the effective disabled state.

#### `FormFields`

```ts
type FormFields = Readonly<Record<string, string | readonly string[]>>;
```

Submitted text values of a form (Files are dropped: they can't be re-filled).

#### `FormOptions`

```ts
interface FormOptions<Schema extends StandardSchemaV1> {
    /**
     * Fields whose submitted values are never sent back: not in `IntentRejected.values`, not in
     * `values()`, not in the devtools timeline. Any posted field name may be listed, including
     * fields outside the schema. Names containing `password`, `passcode`, `csrf` or `xsrf` are
     * secret without being listed (the browser never restores a password field either, and a
     * CSRF token must come fresh from the server, not from the echo).
     */
    readonly secret?: readonly (FieldName<Schema> | (string & {}))[];
}
```


#### `FormReset`

```ts
interface FormReset {
    readonly _tag: 'FormReset';
}
```

Framework message: the owning native form was reset.

#### `FormResult`

```ts
type FormResult<T> = {
    readonly ok: true;
    readonly data: T;
} | {
    readonly ok: false;
    readonly rejected: IntentRejected;
};
```


#### `FormStateRestore`

```ts
interface FormStateRestore {
    readonly _tag: 'FormStateRestore';
    readonly state: FormControlValue;
    readonly mode: 'restore' | 'autocomplete';
}
```

Framework message: native session restoration or autofill supplied control state.

#### `FormValue`

```ts
type FormValue = FormDataEntryValue | readonly FormDataEntryValue[];
```


#### `FormValues`

```ts
type FormValues<Schema extends StandardSchemaV1> = In<Schema> extends Readonly<Record<string, unknown>> ? {
    readonly [K in keyof In<Schema> & string]?: string | readonly string[];
} : FormFields;
```

A form's submitted text values, keyed by the definition's fields, for re-rendering the form
with what was typed (sticky fields). The same shape as `IntentRejected.values`: repeated names
(and `name[]`) are arrays; `File`s and secret fields are left out.

#### `GyralElement`

```ts
interface GyralElement<S, M extends Tagged> extends HTMLElement {
    /** Current model state. */
    readonly state: S;
    /** Feeds a message through `update`, as if an intent had produced it. */
    send(msg: M): void;
    /** Per-instance driver substitutions by name (test fakes). Checked before the spec's. */
    drivers: DriverOverrides;
    /**
     * Per-instance store instances by store name (tests, islands). Checked before the nearest
     * `<gyral-stores>` provider and the document default (ADR 0013).
     */
    stores: StoreOverrides;
    /**
     * Messages applied through `update` right after `init`, before the first render. The server
     * uses it to render a rejected form with the same reducer as the JS path (ADR 0008). Ignored
     * when the element resumes from a hydration seed (the seed already contains their effect).
     */
    initialMessages: readonly Tagged[];
}
```

The custom element `define()` produces: a plain `HTMLElement`. Tests wait for rendering with `settled()`.

#### `GyralElementClass`

```ts
interface GyralElementClass<S, M extends Tagged, P, O extends Tagged = never, N extends string = string> {
    /** Instances expose their declared props as settable properties. */
    new (): GyralElement<S, M> & {
        -readonly [K in keyof P]: P[K];
    };
    readonly spec: ComponentSpec<S, M, P, N>;
    readonly tagName: string;
    /** Native custom-element registration flag, true when the spec opts into forms. */
    readonly formAssociated?: boolean;
    /** Type-only: the outputs this component emits (read by `child()`). */
    readonly outputs?: O;
    /** Type-only: the component's intent names, the keys of `intent` (read by `intentsOf()`). */
    readonly intentNames?: N;
}
```


#### `Head`

```ts
interface Head {
    readonly title: string;
    readonly description?: string;
    /** Absolute URL, usually `new URL(match.path, origin).href` (ADR 0009 "Canonical paths"). */
    readonly canonical?: string;
    /** `<meta name="robots">`, e.g. `'noindex, follow'`. */
    readonly robots?: string;
    /** Later entries win over earlier ones with the same name or property. */
    readonly meta?: readonly HeadMeta[];
    /** Later entries win over earlier ones with the same attributes other than `href`. */
    readonly links?: readonly HeadLink[];
    /** Structured data, each written as one `<script type="application/ld+json">`. */
    readonly jsonLd?: readonly JsonValue[];
    /** `<html lang>`. */
    readonly lang?: string;
    /** `<html dir>`. */
    readonly dir?: 'ltr' | 'rtl' | 'auto';
}
```

A page's head: what `renderPage()` writes on the server and `setHead()` applies on the client.

#### `HeadLink`

```ts
interface HeadLink {
    readonly rel: string;
    readonly href: string;
    readonly [attribute: string]: string;
}
```

A metadata `<link>`: `alternate` (with `hreflang`), `icon` (with `sizes`, `type`), `manifest`
(with `crossorigin`), `prev`/`next`, … Any other attribute is written as given.

#### `HeadMeta`

```ts
type HeadMeta = {
    readonly name: string;
    readonly content: string;
    readonly media?: string;
} | {
    readonly property: string;
    readonly content: string;
    readonly media?: string;
};
```

`<meta name content>`, or `<meta property content>` (Open Graph uses `property`). `media`
makes one entry per media query (`theme-color` for light and dark).

#### `HookAttributes`

```ts
type HookAttributes = Readonly<Record<string, string | true>>;
```

Attributes a hook's server half adds to the start tag (`true`: present, no value).

#### `HookResult`

```ts
interface HookResult<A extends readonly unknown[] = readonly unknown[]> {
    readonly [HOOK]: HookSpec<A>;
    readonly [COMMIT_HOOK]: (part: HookPart, result: HookResult) => void;
    readonly args: A;
}
```

What a hook returns in a template: `<input ${invalid(errors)}>`.

#### `HookSpec`

```ts
interface HookSpec<A extends readonly unknown[]> {
    /** Attributes for the server-rendered start tag. */
    server?(args: A): HookAttributes;
    /** Runs after the commit when `args` changed; `prev` is undefined the first time. */
    client(el: Element, args: A, prev: A | undefined): void;
    /**
     * When `client` runs again: `'args'` (the default) when an argument changed (`Object.is`),
     * `'always'` on every render that commits the hook's position (a skipped `each` row doesn't).
     */
    readonly update?: 'args' | 'always';
    /**
     * Teardown, with the last arguments `client` got: runs
     * when Gyral removes the element, when the position stops holding this hook, or when the host
     * disconnects (not on moves). After a host reconnects, `client` runs again with `prev`
     * undefined.
     */
    dispose?(el: Element, args: A): void;
}
```


#### `Hydrated`

```ts
interface Hydrated {
    readonly _tag: 'Hydrated';
    /** `true` when the instance resumed from server-rendered markup (a hydration seed). */
    readonly serverRendered: boolean;
}
```

Framework message: the component is live in the browser (ADR 0012 addendum). Sent once,
after the first client render has completed, to every client-side instance. Use it for
progressive enhancement: render the no-JS form on the server and in the first client render
(so hydration matches), then switch to the enhanced UI in the `Hydrated` reducer.

#### `HydrateStrategy`

```ts
type HydrateStrategy = 'load' | 'idle' | 'visible' | 'interaction';
```

When a server-rendered component hydrates. `load` (the default) means right away.

#### `IntentInput`

```ts
interface IntentInput {
    /** The intent's name (a message tag): the `data-intent-<event>` or `data-intent` value. */
    readonly name: string;
    readonly event: Event;
    /** The element carrying the intent attribute (`event.currentTarget` is Gyral's root). */
    readonly target: Element;
    /** `value` of the input, select, textarea or button that carries the intent. */
    readonly value: string | undefined;
    /** `checked` for checkbox and radio inputs. */
    readonly checked: boolean | undefined;
    /** Submitted data (including the submitter button) when the intent is on a `<form>`. */
    readonly formData: FormData | undefined;
    /**
     * `detail` of any `CustomEvent`: a Gyral child's output, or the event of another custom
     * element (a map's `marker-select`). Unknown until the parser checks it (a guard, a schema).
     */
    readonly detail: unknown;
    /** `KeyboardEvent.key` for `keydown`/`keyup` intents. */
    readonly key: string | undefined;
    /** For `toggle` intents (popover, `<details>`): the state it changed to. */
    readonly newState: 'open' | 'closed' | undefined;
    /** For `command` intents: the invoker's command (e.g. `--clear`) and source. */
    readonly command: CommandInfo | undefined;
}
```

What the intent layer sees when an element's intent fires.

#### `IntentNames`

```ts
type IntentNames<N extends string> = {
    readonly [K in N]: K;
};
```

A component's intent names, the keys of its `intent` object, as the view's `i` and as
`intentsOf<typeof C>()`, so `data-intent=${i.Increment}` is checked (ADR 0023).

#### `IntentParser`

```ts
type IntentParser<M, P = unknown, S = unknown> = (input: IntentInput, ctx: ParserCtx<P, S>) => ParseResult<M> | Promise<ParseResult<M>>;
```

Parses a platform event into one message variant, `IntentRejected`, or `undefined` to
decline it: a synchronous `undefined` passes the event to the next intent outward for the
same event. May be async because schema validation may be;
an async parser keeps the event. `ctx` is the read-only context reducers get (props as
they are when the event fires, `read(store)`) plus `state`, the component's state at that
moment; parsers that don't need it take one parameter.

#### `IntentRejected`

```ts
interface IntentRejected {
    readonly _tag: 'IntentRejected';
    /** The `data-intent` name whose input was rejected. */
    readonly intent: string;
    readonly issues: readonly FieldIssue[];
    /**
     * For `form()` rejections: what the user submitted, so the view can re-fill the form. On
     * the no-JS path (ADR 0008 server half) the server re-renders the page from this.
     */
    readonly values?: FormFields | undefined;
}
```

Framework message: an intent's input failed schema validation (ADR 0008).

#### `Intents`

```ts
type Intents<M extends Tagged, P = unknown, N extends string = string, S = unknown> = {
    readonly [K in N]: ParserFor<M, P, K, S>;
};
```

Intent parsers keyed by intent name (ADR 0001, ADR 0023). The keys are the component's
intent names: `define<State, Msg>()(tag, { intent: { Archive: …, Increment: … } })` gives the
view `i.Archive` and `i.Increment`. A key that is a message tag must return that variant; any
other key may return any message (several controls that change one thing can also share one
intent and tell themselves apart by `name`). Messages from drivers need no parser.

#### `JsonValue`

```ts
type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
    readonly [key: string]: JsonValue;
};
```

A JSON value: what a JSON-LD block holds.

#### `ListResult`

```ts
interface ListResult {
    readonly [EACH]: (part: ChildPart, list: ListResult) => void;
    readonly items: readonly unknown[];
    readonly key: (item: unknown) => unknown;
    readonly row: (item: unknown, picked: unknown) => unknown;
    readonly pick: ((item: unknown) => unknown) | undefined;
}
```

A keyed list for a child hole: what `each(…)` returns.

#### `Next`

```ts
type Next<S, M> = S | readonly [S, ReadonlyArray<Command<M | IntentRejected>>];
```

What a reducer (or `init`) returns: new state, optionally with commands to run. Commands may
also answer with the framework message `IntentRejected` (e.g. `submitForm` in `@gyral/http`
when the server rejects a form), which goes to the optional `IntentRejected` reducer.

#### `OutputEvent`

```ts
type OutputEvent<O extends Tagged = Tagged> = CustomEvent<O>;
```

The `gyral-output` event a child dispatches on its host for each output (ADR 0010): `detail`
is the output. Bubbles, not composed. A non-Gyral parent listens for `OUTPUT_EVENT`. Only the
direct parent's intent on the child host takes it, and once it does the event stops there.

#### `OutputsOf`

```ts
type OutputsOf<C> = C extends {
    readonly outputs?: infer O;
} ? Exclude<O, undefined> : never;
```

The output union of a `define()` class: `OutputsOf<typeof Item>`.

#### `OutputSource`

```ts
interface OutputSource<O extends Tagged, E extends Element> {
    new (): E;
    /** Type-only marker for the component's output union. Never set at runtime. */
    readonly outputs?: O;
}
```

Anything `child()` can read an output type from: a `define()` class.

#### `ParserCtx`

```ts
interface ParserCtx<P, S = unknown> extends Ctx<P> {
    /** The state when the event fires. */
    readonly state: Readonly<S>;
}
```

What an intent parser gets besides the input: the reducers' context plus the component's
current state, read-only. Parsers decide synchronously (`preventDefault()`), and where the
user is often decides it: Tab leaves a grid only from its last cell.

#### `ParseResult`

```ts
type ParseResult<M> = M | IntentRejected | undefined;
```

What an intent parser returns: a message, `IntentRejected` (invalid input), or `undefined` to
decline the event.

#### `ParserFor`

```ts
type ParserFor<M extends Tagged, P, K, S = unknown> = string extends K ? // The wide form (any intent name), which every specific spec is assignable to.
IntentParser<M, P, S> | true | TrueOnlyForFieldlessMessage : K extends M['_tag'] ? IntentParser<Variant<M, K>, P, S> | TagOnly<Variant<M, K>> : IntentParser<M, P, S>;
```

The parser for intent name `K` (ADR 0023): a name that is a message tag parses into that
variant; any other name is an intent of its own whose parser may produce any message.

#### `Prop`

```ts
interface Prop<T> {
    readonly kind: PropKind;
    /** The attribute name, `false` for property only, `undefined` for the kebab-case default. */
    readonly attribute: string | false | undefined;
    /**
     * Refines (string/number/boolean) or defines (json/value) the accepted values: a Standard
     * Schema, or for json/value a type guard (props.ts `checkValue` tells them apart).
     */
    readonly schema: StandardSchemaV1 | PropGuard<unknown> | undefined;
    /** A missing value is a bug: warned once per instance at first render. */
    readonly required: boolean;
    /** Used whenever the element's value is missing (`boolean` props default to `false`). */
    readonly default?: unknown;
    /**
     * When a new value counts as unchanged (no re-render, no `PropsChanged`): `Object.is`, the
     * same JSON for `prop.json`, or the `equals` option of `prop.json`/`prop.value`.
     */
    readonly equals: (a: unknown, b: unknown) => boolean;
    /** Type-only: the value components see. Never set. */
    readonly [OUTPUT]?: () => T;
}
```

One declared prop: what a builder returns.

#### `PropDeclarations`

```ts
type PropDeclarations<P> = {
    readonly [K in keyof P]-?: Prop<P[K]>;
};
```

The prop builders for props type `P`: one `prop.*` builder per
key. A builder's output type must fit the prop's type, so a prop whose type excludes
`undefined` needs `required: true` or a `default` (the honesty rule, ADR 0007 addendum).
Without explicit type arguments, `define()` infers `P` from the builders.

#### `PropGuard`

```ts
type PropGuard<T> = (value: unknown) => value is T;
```

A plain type guard, accepted by `prop.value` and `prop.json` in place of a schema.

#### `PropKind`

```ts
type PropKind = 'string' | 'number' | 'boolean' | 'json' | 'value';
```


#### `PropsChanged`

```ts
interface PropsChanged<P> {
    readonly _tag: 'PropsChanged';
    readonly props: P;
    readonly prev: P;
}
```

Framework message: declared props changed after the first render (ADR 0007).

#### `PropsOf`

```ts
type PropsOf<T extends Readonly<Record<string, Prop<unknown>>>> = {
    readonly [K in keyof T]: T[K] extends Prop<infer V> ? V : never;
};
```

The props type of a table of builders: `PropsOf<typeof props>`.

#### `RawResult`

```ts
interface RawResult {
    readonly [MARKUP]: (part: ChildPart, html: string) => void;
    readonly html: string;
}
```

Trusted markup for a child hole: what `raw(html)` returns.

#### `Reducer`

```ts
type Reducer<S, M, Msg, P = object> = (state: S, msg: Msg, ctx: Ctx<P>) => Next<S, M>;
```

One entry of `update`: takes the state, one message (`Msg`, a variant of `M` or a framework
message) and the read-only context, and returns the next state, optionally with commands
that produce more `M` messages. To type a reducer written outside the spec:


```ts
const add: Reducer<State, Msg, Variant<Msg, 'Add'>, object> = (s, m) => …
```


#### `RetryPolicy`

```ts
interface RetryPolicy<E = unknown> {
    /** Retries after the first failure. */
    readonly times: number;
    /** Delay before each retry (the base delay for exponential backoff). Default 0. */
    readonly delayMs?: number;
    readonly backoff?: 'fixed' | 'exponential';
    /** Full jitter: wait a random time between 0 and the computed delay, so clients spread out. */
    readonly jitter?: boolean;
    /**
     * Which failures to retry, given the driver's typed error (its `toError`, else the thrown
     * value). Default: every failure. For `@gyral/http`, `retryableHttpError`.
     */
    readonly retryIf?: (error: E) => boolean;
}
```

How `retry(driver, policy)` retries a rejected run (retry.ts). `E`: the driver's error.

#### `SeedCheck`

```ts
type SeedCheck<S> = {
    readonly ok: true;
    readonly state: S;
} | {
    readonly ok: false;
    readonly issues: readonly string[];
};
```

The result of checking a seed against a store's schema.

#### `ShadowOption`

```ts
type ShadowOption = boolean | {
    readonly delegatesFocus?: boolean;
};
```

`spec.shadow`: `true` (the default) or an object for a shadow root, `false` for light DOM.
`delegatesFocus: true`: focusing the host, or clicking a non-focusable part of it, focuses its
first focusable element, and `:focus` matches the host while focus is inside; the server
writes `shadowrootdelegatesfocus` on the declarative shadow root.

#### `StandardSchemaV1`

```ts
interface StandardSchemaV1<Input = unknown, Output = Input> {
    /** The Standard Schema properties. */
    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
}
```

The Standard Schema interface.

#### `Stateless`

```ts
type Stateless = Readonly<Record<string, never>>;
```

State of a component that keeps none (a pure view of its props). Its `init` is optional.

#### `Store`

```ts
interface Store<S, M extends Tagged> extends StoreRef<S> {
    readonly spec: StoreSpec<S, M>;
    /**
     * A fresh, independent instance. `initial` skips `init`'s state (a server seed, a test
     * fixture); `init`'s commands still run on the client.
     */
    instance(initial?: S): StoreInstance<S, M>;
    /** Checks a seed with `spec.schema` (ok as-is without one). */
    checkSeed(seed: unknown): SeedCheck<S>;
    /** Type-only marker for the message type. Never set at runtime. */
    readonly messageType?: (msg: M) => M;
}
```


#### `StoreChanged`

```ts
interface StoreChanged {
    readonly _tag: 'StoreChanged';
    /** The store's name. Narrow with `changed(store, msg)`. */
    readonly store: string;
    readonly state: unknown;
    readonly prev: unknown;
}
```

Framework message: a store this component reads changed (ADR 0013). Optional reducer.

#### `StoreInstance`

```ts
interface StoreInstance<S, M extends Tagged> {
    readonly store: Store<S, M>;
    readonly state: S;
    /** Feeds a message through the store's `update` and notifies subscribers on change. */
    send(msg: M): void;
    /** Called after every state change. Returns an unsubscribe function. */
    subscribe(listener: (state: S, prev: S) => void): () => void;
    /** Per-instance driver substitutions (test fakes). Checked before the spec's. */
    drivers: DriverOverrides;
    /** Stops running commands and drops subscribers. */
    dispose(): void;
    /** Set by the registry that holds the instance (store-to-store `send`). */
    bindScope(resolve: StoreResolver): void;
}
```

A live store: one per page on the client, one per request on the server, one per test.

#### `StoreOverrides`

```ts
type StoreOverrides = Readonly<Record<string, AnyStoreInstance>>;
```

Store instances substituted by store name (tests, islands).

#### `StoreReader`

```ts
type StoreReader = <S>(store: StoreRef<S>) => S;
```

Reads a declared store's current state, typed by the store (ADR 0013).

#### `StoreRef`

```ts
interface StoreRef<S> {
    readonly name: string;
    /** Type-only marker for the state type. Never set at runtime. */
    readonly stateType?: (state: S) => S;
}
```

What `ctx.read()` accepts: anything that names a store and carries its state type.

#### `StoreResolver`

```ts
type StoreResolver = (store: AnyStore) => AnyStoreInstance;
```

Finds a store's instance in a scope (a registry).

#### `StoreSpec`

```ts
interface StoreSpec<S, M extends Tagged> {
    /** Initial state (and optional commands, e.g. load a saved cart). */
    readonly init: () => Next<S, M>;
    readonly update: StoreUpdate<S, M>;
    /** Driver substitutions by name for this store's commands. */
    readonly drivers?: DriverOverrides;
    /**
     * Validates the server's page seed before the client uses it (any synchronous Standard
     * Schema). An invalid seed is reported with console.error and the store starts from `init`.
     */
    readonly schema?: StandardSchemaV1<unknown, S>;
}
```


#### `StoreUpdate`

```ts
type StoreUpdate<S, M extends Tagged> = {
    readonly [K in M['_tag']]: (state: S, msg: Variant<M, K>) => Next<S, M>;
};
```

One pure reducer per message tag, like a component's `update` but without context.

#### `Styles`

```ts
type Styles = StyleSource | string | readonly Styles[];
```

What `spec.styles` accepts: `css` values, plain CSS strings (e.g.
`import base from './base.css?inline'`) and arrays of them, nested freely. CSS is trusted
author code: never interpolate user input.

#### `StyleSource`

```ts
interface StyleSource {
    readonly [STYLE]: true;
    readonly text: string;
}
```

What `css` returns: CSS text, mapped to one shared `CSSStyleSheet` in the browser.

#### `SubscriptionContext`

```ts
interface SubscriptionContext<I> {
    /** The command's input (a room code, a URL, a store key). */
    readonly input: I;
    /** Aborts when the command is switched away or its component disconnects. */
    readonly signal: AbortSignal;
    /**
     * Ends the subscription with an error: the source is released and the command's
     * `onFailure` gets it. Wrap the driver in `retry()` to subscribe again instead.
     */
    readonly fail: (error: unknown) => void;
}
```


#### `SubscriptionOptions`

```ts
interface SubscriptionOptions<E> {
    readonly concurrency?: Concurrency;
    readonly toError?: (cause: unknown) => E;
}
```

Driver options a subscription may set. `concurrency` defaults to `'switch'`.

#### `Tagged`

```ts
interface Tagged {
    readonly _tag: string;
}
```

Every message is a tagged object; the tag is also the intent name used in markup.

#### `TemplateResult`

```ts
interface TemplateResult {
    readonly [SOURCE]: readonly string[] | TemplateObject;
    readonly values: readonly unknown[];
}
```

What `html` returns: a template plus this render's values.

#### `Unsubscribe`

```ts
type Unsubscribe = (() => void) | {
    readonly unsubscribe: () => void;
};
```

How to stop listening: a function, or an object with `unsubscribe()` (RxJS, XState).

#### `Update`

```ts
type Update<S, M extends Tagged, P = object> = {
    readonly [K in M['_tag']]: Reducer<S, M, Variant<M, K>, P>;
} & {
    readonly PropsChanged?: Reducer<S, M, PropsChanged<P>, P>;
    readonly IntentRejected?: Reducer<S, M, IntentRejected, P>;
    readonly StoreChanged?: Reducer<S, M, StoreChanged, P>;
    readonly Hydrated?: Reducer<S, M, Hydrated, P>;
    readonly Errored?: Reducer<S, M, Errored, P>;
    readonly FormReset?: Reducer<S, M, FormReset, P>;
    readonly FormDisabled?: Reducer<S, M, FormDisabled, P>;
    readonly FormStateRestore?: Reducer<S, M, FormStateRestore, P>;
};
```

One pure reducer per message tag (exhaustive by construction), plus optional reducers
for framework messages. Reducers may return commands.

#### `Variant`

```ts
type Variant<M extends Tagged, K> = Extract<M, {
    readonly _tag: K;
}>;
```

The member of message union `M` whose tag is `K`: `Variant<Msg, 'Add'>`.

## `@gyral/core/storage`

### Functions

| Name | Summary |
| --- | --- |
| [`makeLocalStorageDriver`](#core-storage-makelocalstoragedriver) | JSON storage with typed reads/writes and cancellable native + own-write change streams. |

#### `makeLocalStorageDriver`

```ts
function makeLocalStorageDriver<T>(schema: StandardSchemaV1<unknown, T>, options?: LocalStorageOptions<T>): Driver<StorageInput<T>, StorageOutput<T>, StorageError>;
```

JSON storage with typed reads/writes and cancellable native + own-write change streams.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`LocalStorageOptions`](#core-storage-localstorageoptions) |  |
| [`StorageChangeSource`](#core-storage-storagechangesource) |  |
| [`StorageDecodeError`](#core-storage-storagedecodeerror) |  |
| [`StorageError`](#core-storage-storageerror) |  |
| [`StorageInput`](#core-storage-storageinput) |  |
| [`StorageOutput`](#core-storage-storageoutput) |  |
| [`StoredValue`](#core-storage-storedvalue) | Absence differs from a decoded value, even when the schema accepts null or undefined. |

#### `LocalStorageOptions`

```ts
interface LocalStorageOptions<T> {
    /** Name for normal driver substitution. Default localStorage. */
    readonly name?: string;
    /** Keys and Clear are restricted to this namespace. Default empty (all keys). */
    readonly prefix?: string;
    /** Accessed only when a command runs. Default native localStorage. */
    readonly storage?: () => Storage;
    /** A transformed schema may need to encode model values back into its input shape. */
    readonly encode?: (value: T) => unknown;
}
```


#### `StorageChangeSource`

```ts
type StorageChangeSource = 'initial' | 'driver' | 'tab';
```


#### `StorageDecodeError`

```ts
interface StorageDecodeError {
    readonly _tag: 'StorageDecodeError';
    readonly key: string;
    readonly issues: readonly StandardSchemaV1.Issue[];
}
```


#### `StorageError`

```ts
type StorageError = StorageDecodeError | {
    readonly _tag: 'StorageAccessError';
    readonly operation: StorageInput<unknown>['_tag'];
    readonly key: string | undefined;
    readonly message: string;
};
```


#### `StorageInput`

```ts
type StorageInput<T> = {
    readonly _tag: 'Read';
    readonly key: string;
} | {
    readonly _tag: 'Write';
    readonly key: string;
    readonly value: T;
} | {
    readonly _tag: 'Remove';
    readonly key: string;
} | {
    readonly _tag: 'Clear';
} | {
    readonly _tag: 'Watch';
    readonly key: string;
};
```


#### `StorageOutput`

```ts
type StorageOutput<T> = {
    readonly _tag: 'StorageValue';
    readonly key: string;
    readonly entry: StoredValue<T>;
} | {
    readonly _tag: 'StorageWritten' | 'StorageRemoved';
    readonly key: string;
} | {
    readonly _tag: 'StorageCleared';
} | {
    readonly _tag: 'StorageChanged';
    readonly key: string;
    readonly source: StorageChangeSource;
    readonly entry: StoredValue<T>;
} | {
    readonly _tag: 'StorageDecodeFailed';
    readonly key: string;
    readonly source: StorageChangeSource;
    readonly error: StorageDecodeError;
};
```


#### `StoredValue`

```ts
type StoredValue<T> = {
    readonly found: false;
} | {
    readonly found: true;
    readonly value: T;
};
```

Absence differs from a decoded value, even when the schema accepts null or undefined.

## `@gyral/core/indexeddb`

### Functions

| Name | Summary |
| --- | --- |
| [`makeIndexedDBDriver`](#core-indexeddb-makeindexeddbdriver) | Typed record operations and atomic batches over application-owned stores and migrations. |

#### `makeIndexedDBDriver`

```ts
function makeIndexedDBDriver<S extends IndexedDBStores>(stores: S, options: IndexedDBOptions<S>): Driver<IndexedDBInput<S>, IndexedDBOutput<S>, IndexedDBError>;
```

Typed record operations and atomic batches over application-owned stores and migrations.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`IndexedDBError`](#core-indexeddb-indexeddberror) |  |
| [`IndexedDBInput`](#core-indexeddb-indexeddbinput) |  |
| [`IndexedDBOperation`](#core-indexeddb-indexeddboperation) |  |
| [`IndexedDBOptions`](#core-indexeddb-indexeddboptions) |  |
| [`IndexedDBOutput`](#core-indexeddb-indexeddboutput) |  |
| [`IndexedDBRange`](#core-indexeddb-indexeddbrange) |  |
| [`IndexedDBRecord`](#core-indexeddb-indexeddbrecord) |  |
| [`IndexedDBResult`](#core-indexeddb-indexeddbresult) |  |
| [`IndexedDBStores`](#core-indexeddb-indexeddbstores) |  |

#### `IndexedDBError`

```ts
type IndexedDBError = {
    readonly _tag: 'IndexedDBBlockedError';
    readonly database: string;
    readonly version: number;
} | {
    readonly _tag: 'IndexedDBInputError';
    readonly message: string;
} | {
    readonly _tag: 'IndexedDBAccessError';
    readonly database: string;
    readonly phase: 'encode' | 'open' | 'upgrade' | 'transaction';
    readonly name: string;
    readonly message: string;
} | {
    readonly _tag: 'IndexedDBDecodeError';
    readonly store: string;
    readonly issues: readonly StandardSchemaV1.Issue[];
    /** Native transaction completed before decoding. Its writes cannot be undone. */
    readonly committed: true;
};
```


#### `IndexedDBInput`

```ts
type IndexedDBInput<S extends IndexedDBStores> = IndexedDBOperation<S> | {
    readonly _tag: 'Transaction';
    readonly operations: readonly IndexedDBOperation<S>[];
};
```


#### `IndexedDBOperation`

```ts
type IndexedDBOperation<S extends IndexedDBStores> = {
    [K in keyof S & string]: {
        readonly _tag: 'Read' | 'Delete';
        readonly store: K;
        readonly key: IDBValidKey;
    } | {
        readonly _tag: 'Put';
        readonly store: K;
        readonly value: IndexedDBRecord<S[K]>;
        readonly key?: IDBValidKey;
    } | {
        readonly _tag: 'Query';
        readonly store: K;
        readonly index?: string;
        readonly range?: IndexedDBRange;
        readonly direction?: IDBCursorDirection;
        readonly limit: number;
    };
}[keyof S & string];
```


#### `IndexedDBOptions`

```ts
interface IndexedDBOptions<S extends IndexedDBStores> {
    readonly database: string;
    readonly version: number;
    readonly name?: string;
    readonly factory?: () => IDBFactory;
    /** Synchronous: queue migration requests before returning; never await. */
    readonly upgrade?: (db: IDBDatabase, oldVersion: number, newVersion: number, transaction: IDBTransaction) => void;
    readonly encode?: <K extends keyof S & string>(store: K, value: IndexedDBRecord<S[K]>) => unknown;
}
```


#### `IndexedDBOutput`

```ts
type IndexedDBOutput<S extends IndexedDBStores> = IndexedDBResult<S> | {
    readonly _tag: 'Committed';
    readonly results: readonly IndexedDBResult<S>[];
};
```


#### `IndexedDBRange`

```ts
type IndexedDBRange = {
    readonly _tag: 'Only';
    readonly key: IDBValidKey;
} | {
    readonly _tag: 'Lower' | 'Upper';
    readonly key: IDBValidKey;
    readonly open?: boolean;
} | {
    readonly _tag: 'Bound';
    readonly lower: IDBValidKey;
    readonly upper: IDBValidKey;
    readonly lowerOpen?: boolean;
    readonly upperOpen?: boolean;
};
```


#### `IndexedDBRecord`

```ts
type IndexedDBRecord<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;
```


#### `IndexedDBResult`

```ts
type IndexedDBResult<S extends IndexedDBStores> = {
    [K in keyof S & string]: {
        readonly _tag: 'Record';
        readonly store: K;
        readonly key: IDBValidKey;
        readonly entry: {
            readonly found: false;
        } | {
            readonly found: true;
            readonly value: IndexedDBRecord<S[K]>;
        };
    } | {
        readonly _tag: 'Put' | 'Deleted';
        readonly store: K;
        readonly key: IDBValidKey;
    } | {
        readonly _tag: 'Records';
        readonly store: K;
        readonly records: readonly {
            readonly key: IDBValidKey;
            readonly value: IndexedDBRecord<S[K]>;
        }[];
    };
}[keyof S & string];
```


#### `IndexedDBStores`

```ts
type IndexedDBStores = Readonly<Record<string, StandardSchemaV1>>;
```


## `@gyral/core/vite`

### Functions

| Name | Summary |
| --- | --- |
| [`gyralVitePreset`](#core-vite-gyralvitepreset) | Spread into a Vite config, or into each Vitest project: |

#### `gyralVitePreset`

```ts
function gyralVitePreset(options?: GyralViteOptions): GyralViteConfig;
```

Spread into a Vite config, or into each Vitest project:


```ts
export default defineConfig({ ...gyralVitePreset(), build: { … } });
```

With plugins of your own, list both: `plugins: [...preset.plugins, mine()]`.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`ComponentsOptions`](#core-vite-componentsoptions) |  |
| [`ElementTypesOptions`](#core-vite-elementtypesoptions) | Where the preset looks for components and writes their typings. |
| [`GyralViteConfig`](#core-vite-gyralviteconfig) |  |
| [`GyralViteOptions`](#core-vite-gyralviteoptions) |  |
| [`TemplateCompilerOptions`](#core-vite-templatecompileroptions) |  |

#### `ComponentsOptions`

```ts
interface ComponentsOptions {
    /** Directories (relative to Vite's root) whose modules' `define()` tags are found. Default `['src']`. */
    readonly include?: readonly string[];
    /**
     * Tag → module (relative to Vite's root) for components the scan can't find: those defined
     * through a wrapper such as `defineMemberForm({ tag: 'member-form' })`, which calls
     * `define()` itself. Listed entries win over scanned ones.
     */
    readonly modules?: Readonly<Record<string, string>>;
}
```


#### `ElementTypesOptions`

```ts
interface ElementTypesOptions {
    /** Source directories to scan, relative to the Vite root. Default `['src']`. */
    readonly dirs?: readonly string[];
    /** The declaration file to write, relative to the Vite root. Default `.gyral/elements.d.ts`. */
    readonly out?: string;
}
```

Where the preset looks for components and writes their typings.

#### `GyralViteConfig`

```ts
interface GyralViteConfig {
    readonly plugins: Plugin[];
    readonly optimizeDeps: {
        readonly include: string[];
    };
}
```


#### `GyralViteOptions`

```ts
interface GyralViteOptions {
    /**
     * Generated element typings (`.gyral/elements.d.ts`, see `ElementTypesOptions`), or `false`
     * to write none. Default: on, scanning `src`.
     */
    readonly types?: ElementTypesOptions | false;
    /** Modules to pre-bundle in dev, so Vite doesn't discover them mid-run and reload. */
    readonly optimize?: readonly string[];
    /** Template compiler options (`vite build` only). */
    readonly compiler?: TemplateCompilerOptions;
    /**
     * The app is never server-rendered: leave the hydration code out of the browser bundle.
     * Default false.
     */
    readonly clientOnly?: boolean;
    /**
     * Automatic component loading (ADR 0016 addendum): every component defined under `include`
     * gets a client module the build splits out, and a loader (`virtual:gyral/components`, added
     * to the client build's input) imports a tag's module once that tag is in the page.
     * `renderPage({ components })` then links exactly the components a page rendered, so pages
     * need no client entry of their own and no side-effect imports. Default off.
     */
    readonly components?: boolean | ComponentsOptions;
}
```


#### `TemplateCompilerOptions`

```ts
interface TemplateCompilerOptions {
    /**
     * Module specifiers whose `html` (and `svg`) exports are the view layer's tags (default
     * `DEFAULT_TEMPLATE_SOURCES`). An import matches when its specifier is listed, or when it
     * resolves to the same module as a listed one; core's own view modules always match. A
     * source other than '@gyral/core' must also export `compiled` (and `compiledSvg` when it
     * exports `svg`).
     */
    readonly sources?: readonly string[];
    /**
     * Rule 7's extra check with parse5 (an optional peer dependency): `true` (default) uses
     * 'parse5' when it is installed, a string names the module to load, `false` skips it.
     */
    readonly parse5?: boolean | string;
}
```


## `@gyral/core/eslint`

### Constants

| Name | Summary |
| --- | --- |
| [`default`](#core-eslint-default) |  |

#### `default`

```ts
declare const _default: GyralPlugin;
export default _default;
```


### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`GyralPlugin`](#core-eslint-gyralplugin) |  |

#### `GyralPlugin`

```ts
interface GyralPlugin extends ESLint.Plugin {
    readonly rules: {
        readonly template: typeof templateRule;
        readonly 'each-row-purity': typeof rowPurityRule;
        readonly 'unused-intent': typeof unusedIntentRule;
    };
    readonly configs: {
        readonly recommended: Linter.Config;
    };
}
```

---

# @gyral/http

> Gyral HTTP driver: fetch requests as data, typed errors, Standard Schema decoding.

Source: https://gyral.dev/docs/api/http/

Gyral HTTP driver: fetch requests as data, typed errors, Standard Schema decoding.

```sh
npm install @gyral/http
```

> **Writing code? Start from working code, not from this page.** [Effects and drivers](https://gyral.dev/docs/effects/). Adapt the closest example and check it, then look a name up here when you are about to call it.

Generated from the package's type declarations. Entry points: [`@gyral/http`](#gyralhttp), [`@gyral/http/sse`](#gyralhttpsse), [`@gyral/http/websocket`](#gyralhttpwebsocket), [`@gyral/http/testing`](#gyralhttptesting).

## `@gyral/http`

### Functions

| Name | Summary |
| --- | --- |
| [`csrfFromMeta`](#http-csrffrommeta) | A header source that reads a token from `<meta name=…>` when each request runs. |
| [`get`](#http-get) |  |
| [`makeHttpDriver`](#http-makehttpdriver) |  |
| [`redirectedTo`](#http-redirectedto) | The `location` of a `FormRedirected` answer (`formAction` in `@gyral/ssr`), if it is one. |
| [`request`](#http-request) | A command that performs `req` with the `http` driver (or its substitute). |
| [`retryableHttpError`](#http-retryablehttperror) | The failures worth retrying: network errors, timeouts, 408, 429 and 5xx. |
| [`submitForm`](#http-submitform) | Sends a form submission to the server (usually after `form()` validated it in the browser, which passes the raw `FormData`). |

#### `csrfFromMeta`

```ts
function csrfFromMeta(meta: string, header?: string): () => Readonly<Record<string, string>>;
```

A header source that reads a token from `<meta name=…>` when each request runs. On the
server, or when the meta is missing, it adds nothing. The header defaults to `x-csrf-token`.

#### `get`

```ts
function get<O = unknown, MS = never, MF = MS>(url: string, handlers: RequestHandlers<O, MS, MF>): Command<MS | MF>;
```


#### `makeHttpDriver`

```ts
function makeHttpDriver(options?: HttpDriverOptions): Driver<HttpRequest, unknown, HttpError>;
```


#### `redirectedTo`

```ts
function redirectedTo(body: unknown): string | undefined;
```

The `location` of a `FormRedirected` answer (`formAction` in `@gyral/ssr`), if it is one.

#### `request`

```ts
function request<O = unknown, MS = never, MF = MS>(req: Omit<HttpRequest, 'schema' | 'errorSchema'>, handlers: RequestHandlers<O, MS, MF>): Command<MS | MF>;
```

A command that performs `req` with the `http` driver (or its substitute).

#### `retryableHttpError`

```ts
const retryableHttpError: (error: HttpError) => boolean
```

The failures worth retrying: network errors, timeouts, 408, 429 and 5xx. Pass it as
`retry(…, { retryIf: retryableHttpError })`. A 4xx other than 408/429 means the request
itself is wrong, and decoding errors won't change on a retry. `Retry-After` isn't read.

#### `submitForm`

```ts
function submitForm<MS, MF = MS>(url: string, formData: FormData, options: SubmitFormOptions<MS, MF>): Command<MS | MF | IntentRejected>;
```

Sends a form submission to the server (usually after `form()` validated it in the browser,
which passes the raw `FormData`). The body is the `FormData` itself, so the server's
`formAction` parses it exactly like a no-JS post. A 422 answer with an `IntentRejected`
(server-only checks: duplicate email, wrong password) is dispatched as `IntentRejected`.


```ts
Register: (s, m) => [{ ...s, busy: true }, [submitForm('/register', m.form, {
  onSuccess: (body) => ({ _tag: 'Registered', location: redirectedTo(body) }),
  onFailure: () => ({ _tag: 'Failed' }),
})]],
```


### Constants

| Name | Summary |
| --- | --- |
| [`http`](#http-http) | The default driver. |

#### `http`

```ts
const http: Driver<HttpRequest, unknown, HttpError>
```

The default driver. Substitute it by name: `el.drivers = { http: makeHttpDriver({...}) }`.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`FormRedirected`](#http-formredirected) | A server's JSON answer to a valid form post that would have redirected without JS. |
| [`HeaderSource`](#http-headersource) | Headers as data, or computed when each request runs (e.g. |
| [`HttpDriverOptions`](#http-httpdriveroptions) |  |
| [`HttpError`](#http-httperror) | Every way a request can fail. |
| [`HttpMethod`](#http-httpmethod) |  |
| [`HttpRequest`](#http-httprequest) | An HTTP request described as data. |
| [`RequestHandlers`](#http-requesthandlers) |  |
| [`SubmitFormOptions`](#http-submitformoptions) |  |

#### `FormRedirected`

```ts
interface FormRedirected {
    readonly _tag: 'Redirected';
    readonly location: string;
}
```

A server's JSON answer to a valid form post that would have redirected without JS.

#### `HeaderSource`

```ts
type HeaderSource = Readonly<Record<string, string>> | ((req: HttpRequest) => Readonly<Record<string, string>> | undefined);
```

Headers as data, or computed when each request runs (e.g. read a CSRF `<meta>`).

#### `HttpDriverOptions`

```ts
interface HttpDriverOptions {
    /** Driver name used for substitution (`el.drivers`). Default `'http'`. */
    readonly name?: string;
    /**
     * Default headers for every request through this driver: app-level concerns such as a CSRF
     * token or an API key, so components and stores never read the DOM themselves. This is the
     * one place a CSRF token is configured (ADR 0022). Per-request `headers` win over these.
     *
     *   provideDrivers(document.body, { http: makeHttpDriver({ headers: csrfFromMeta('csrf-token') }) });
     */
    readonly headers?: HeaderSource;
    /** Resolves relative URLs. Default: the document location. */
    readonly baseUrl?: string;
    readonly fetch?: typeof fetch;
    readonly concurrency?: Concurrency;
    /**
     * Aborts a request that takes longer than this, failing with `HttpTimeoutError`. Applies per
     * attempt: under `retry(…)` each attempt gets the full time. Default: no limit.
     */
    readonly timeoutMs?: number;
}
```


#### `HttpError`

```ts
type HttpError = {
    readonly _tag: 'HttpStatusError';
    readonly url: string;
    readonly status: number;
    readonly statusText: string;
    /** The response body: parsed JSON, or text, or `undefined` when empty. */
    readonly body: unknown;
    /** `body` decoded by the request's `errorSchema`, when it was given and matched. */
    readonly detail?: unknown;
} | {
    readonly _tag: 'HttpNetworkError';
    readonly url: string;
    readonly message: string;
}
/** The attempt took longer than the driver's `timeoutMs`. */
 | {
    readonly _tag: 'HttpTimeoutError';
    readonly url: string;
    readonly timeoutMs: number;
} | {
    readonly _tag: 'HttpDecodeError';
    readonly url: string;
    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
};
```

Every way a request can fail. Delivered to `onFailure`, never thrown into the view.

#### `HttpMethod`

```ts
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
```


#### `HttpRequest`

```ts
interface HttpRequest {
    readonly url: string;
    readonly method?: HttpMethod;
    readonly headers?: Readonly<Record<string, string>>;
    /** Sent as JSON, except `FormData` and `URLSearchParams`, which are sent as forms. */
    readonly body?: unknown;
    /** Decodes the JSON response. Any Standard Schema library works (Zod, Valibot, Effect…). */
    readonly schema?: StandardSchemaV1;
    /**
     * Decodes the body of a non-2xx response into `HttpStatusError.detail` (for example a 422
     * `IntentRejected`). A body that doesn't match leaves `detail` unset; `body` is always kept.
     */
    readonly errorSchema?: StandardSchemaV1;
}
```

An HTTP request described as data.

#### `RequestHandlers`

```ts
interface RequestHandlers<O, MS, MF> {
    /** Decodes the response; its output type becomes `onSuccess`'s input. */
    readonly schema?: StandardSchemaV1<unknown, O>;
    /** Decodes non-2xx bodies into `HttpStatusError.detail` (e.g. a 422 `IntentRejected`). */
    readonly errorSchema?: StandardSchemaV1;
    readonly onSuccess: (body: O) => MS | undefined;
    readonly onFailure?: (error: HttpError) => MF | undefined;
    /** Concurrency lane, e.g. `'search'`. Default `'http'`. */
    readonly key?: string;
    readonly concurrency?: Concurrency;
}
```


#### `SubmitFormOptions`

```ts
interface SubmitFormOptions<MS, MF> {
    readonly method?: 'POST' | 'PUT' | 'PATCH';
    /**
     * A CSRF token the app already holds, for this submission only. The header defaults to
     * `x-csrf-token`. A token from a `<meta>` is configured once, on the driver:
     * `makeHttpDriver({ headers: csrfFromMeta('csrf-token') })` (ADR 0022).
     */
    readonly csrf?: {
        readonly token: string;
        readonly header?: string;
    };
    /** The server's success answer, e.g. `{ _tag: 'Redirected', location }` (see `redirectedTo`). */
    readonly onSuccess: (body: unknown) => MS | undefined;
    /** Any failure except a 422 `IntentRejected`, which goes to the `IntentRejected` reducer. */
    readonly onFailure?: (error: HttpError) => MF | undefined;
    /** Concurrency lane. Default `form:<url>`. */
    readonly key?: string;
    /** Default `exhaust`: a second submit while one is in flight is ignored. */
    readonly concurrency?: Concurrency;
}
```


## `@gyral/http/sse`

### Functions

| Name | Summary |
| --- | --- |
| [`makeEventSourceDriver`](#http-sse-makeeventsourcedriver) | A cancellable feed; native EventSource owns reconnection, credentials and Last-Event-ID. |

#### `makeEventSourceDriver`

```ts
function makeEventSourceDriver<T>(schema: StandardSchemaV1<unknown, T>, options?: EventSourceOptions): Driver<EventSourceInput, EventSourceOutput<T>, EventSourceError>;
```

A cancellable feed; native EventSource owns reconnection, credentials and Last-Event-ID.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`EventSourceError`](#http-sse-eventsourceerror) |  |
| [`EventSourceInput`](#http-sse-eventsourceinput) |  |
| [`EventSourceOptions`](#http-sse-eventsourceoptions) |  |
| [`EventSourceOutput`](#http-sse-eventsourceoutput) |  |

#### `EventSourceError`

```ts
interface EventSourceError {
    readonly _tag: 'EventSourceError';
    readonly url: string | undefined;
    readonly message: string;
}
```


#### `EventSourceInput`

```ts
interface EventSourceInput {
    readonly url: string;
}
```


#### `EventSourceOptions`

```ts
interface EventSourceOptions {
    readonly name?: string;
    readonly withCredentials?: boolean;
    /** Named events in addition to the default message event. No wildcard native listener. */
    readonly events?: readonly string[];
    /** Default JSON parsing. Validation may be asynchronous. */
    readonly parse?: (text: string) => unknown;
}
```


#### `EventSourceOutput`

```ts
type EventSourceOutput<T> = {
    readonly _tag: 'EventSourceState';
    readonly url: string;
    readonly state: 'connecting' | 'open' | 'closed';
} | {
    readonly _tag: 'EventSourceMessage';
    readonly url: string;
    readonly eventType: string;
    readonly lastEventId: string;
    readonly data: T;
} | {
    readonly _tag: 'EventSourceDecodeFailed';
    readonly url: string;
    readonly eventType: string;
    readonly lastEventId: string;
    readonly issues: readonly StandardSchemaV1.Issue[];
};
```


## `@gyral/http/websocket`

### Functions

| Name | Summary |
| --- | --- |
| [`makeWebSocketDriver`](#http-websocket-makewebsocketdriver) | Typed receive/send/close commands on one owned socket, with bounded outgoing buffering. |

#### `makeWebSocketDriver`

```ts
function makeWebSocketDriver<T, Out>(schema: StandardSchemaV1<unknown, T>, options: WebSocketOptions<Out>): Driver<WebSocketInput<Out>, WebSocketOutput<T>, WebSocketError>;
```

Typed receive/send/close commands on one owned socket, with bounded outgoing buffering.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`WebSocketClosed`](#http-websocket-websocketclosed) |  |
| [`WebSocketError`](#http-websocket-websocketerror) |  |
| [`WebSocketIncoming`](#http-websocket-websocketincoming) |  |
| [`WebSocketInput`](#http-websocket-websocketinput) |  |
| [`WebSocketOptions`](#http-websocket-websocketoptions) |  |
| [`WebSocketOutput`](#http-websocket-websocketoutput) |  |
| [`WebSocketPayload`](#http-websocket-websocketpayload) |  |

#### `WebSocketClosed`

```ts
interface WebSocketClosed {
    readonly _tag: 'WebSocketClosed';
    readonly connection: string;
    readonly url: string;
    readonly code: number;
    readonly reason: string;
    readonly wasClean: boolean;
    /** The application issued a valid Close command on this connection. */
    readonly requested: boolean;
}
```


#### `WebSocketError`

```ts
type WebSocketError = {
    readonly _tag: 'WebSocketConnectError';
    readonly connection: string | undefined;
    readonly url: string | undefined;
    readonly message: string;
} | {
    readonly _tag: 'WebSocketClosedError';
    readonly connection: string;
    readonly url: string;
    readonly code: number;
    readonly reason: string;
    readonly wasClean: boolean;
    readonly errored: boolean;
    readonly requested: boolean;
} | {
    readonly _tag: 'WebSocketSendError';
    readonly connection: string;
    readonly reason: 'not-open' | 'buffer-limit' | 'encode' | 'send';
    readonly message: string;
    readonly bufferedBytes?: number;
    readonly bytes?: number;
    readonly limit?: number;
} | {
    readonly _tag: 'WebSocketCloseError';
    readonly connection: string;
    readonly message: string;
};
```


#### `WebSocketIncoming`

```ts
type WebSocketIncoming = string | ArrayBuffer;
```


#### `WebSocketInput`

```ts
type WebSocketInput<T> = {
    readonly _tag: 'Connect';
    readonly connection: string;
    readonly url: string;
    readonly protocols?: string | readonly string[];
} | {
    readonly _tag: 'Send';
    readonly connection: string;
    readonly value: T;
} | {
    readonly _tag: 'Close';
    readonly connection: string;
    readonly code?: number;
    readonly reason?: string;
};
```


#### `WebSocketOptions`

```ts
interface WebSocketOptions<T> {
    readonly name?: string;
    readonly encode: (value: T) => WebSocketPayload;
    /** Synchronous parse; default JSON text. Validation may be async. */
    readonly parse?: (payload: WebSocketIncoming) => unknown;
    /** Maximum native bufferedAmount + encoded payload bytes. Default 65536. */
    readonly maxBufferedBytes?: number;
}
```


#### `WebSocketOutput`

```ts
type WebSocketOutput<T> = {
    readonly _tag: 'WebSocketState';
    readonly connection: string;
    readonly url: string;
    readonly state: 'connecting' | 'open' | 'closing';
} | {
    readonly _tag: 'WebSocketMessage';
    readonly connection: string;
    readonly data: T;
} | {
    readonly _tag: 'WebSocketDecodeFailed';
    readonly connection: string;
    readonly issues: readonly StandardSchemaV1.Issue[];
} | {
    readonly _tag: 'WebSocketSent';
    readonly connection: string;
    readonly bytes: number;
} | {
    readonly _tag: 'WebSocketCloseRequested';
    readonly connection: string;
} | WebSocketClosed;
```


#### `WebSocketPayload`

```ts
type WebSocketPayload = string | Blob | ArrayBuffer | ArrayBufferView<ArrayBuffer>;
```


## `@gyral/http/testing`

### Functions

| Name | Summary |
| --- | --- |
| [`fakeHttp`](#http-testing-fakehttp) | `el.drivers = { http: fakeHttp() }` (or `provideDrivers(root, { http })`), then `http.respondNext({ body })` or `http.reply(422, problem)`. |

#### `fakeHttp`

```ts
function fakeHttp(options?: FakeHttpOptions): FakeHttp;
```

`el.drivers = { http: fakeHttp() }` (or `provideDrivers(root, { http })`), then
`http.respondNext({ body })` or `http.reply(422, problem)`. Request inputs are recorded in
`requests` (alias `inputs`).

### Classes

| Name | Summary |
| --- | --- |
| [`FakeHttpResponderError`](#http-testing-fakehttprespondererror) | The error a fake request fails with when the `respond` option threw. |

#### `FakeHttpResponderError`

```ts
class FakeHttpResponderError extends Error {
  readonly request: HttpRequest;
  constructor(request: HttpRequest, cause: unknown);
}
```

The error a fake request fails with when the `respond` option threw.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`FakeHttp`](#http-testing-fakehttp) |  |
| [`FakeHttpCall`](#http-testing-fakehttpcall) | One request the fake driver received. |
| [`FakeHttpOptions`](#http-testing-fakehttpoptions) |  |
| [`FakeResponse`](#http-testing-fakeresponse) | What a fake server answers: a status (default 200) and a JSON body (omit for none). |

#### `FakeHttp`

```ts
interface FakeHttp extends Driver<HttpRequest, unknown, HttpError> {
    readonly calls: readonly FakeHttpCall[];
    /** Every request so far. */
    readonly requests: readonly HttpRequest[];
    /** Same as `requests`; matches `fakeDriver(…).inputs` from `@gyral/testing`. */
    readonly inputs: readonly HttpRequest[];
    /** Errors thrown (or rejected) by the `respond` option, in order. */
    readonly responderErrors: readonly unknown[];
    /** Answers the oldest request that is still waiting. Throws if there is none. */
    respondNext(response?: FakeResponse): void;
    /** Shorthand for `respondNext({ status, body })`, e.g. `reply(422, problem)`. */
    reply(status: number, body?: unknown): void;
    /** Fails the oldest waiting request as a network error. Throws if there is none. */
    failNext(message?: string): void;
}
```


#### `FakeHttpCall`

```ts
interface FakeHttpCall {
    readonly request: HttpRequest;
    readonly signal: AbortSignal;
    readonly settled: boolean;
    /** Answers this request; the real driver then decodes it. */
    readonly respond: (response?: FakeResponse) => void;
    /** Fails this request as a network error (`HttpNetworkError`). */
    readonly fail: (message?: string) => void;
}
```

One request the fake driver received.

#### `FakeHttpOptions`

```ts
interface FakeHttpOptions {
    /** Driver name to substitute (`el.drivers`, providers). Default `'http'`. */
    readonly name?: string;
    /** Answer every request immediately. Without it, requests wait for `respondNext`. */
    readonly respond?: (request: HttpRequest) => FakeResponse | Promise<FakeResponse>;
    /** Base URL for relative request URLs. Default `'http://localhost/'`. */
    readonly baseUrl?: string;
    readonly headers?: HeaderSource;
    readonly concurrency?: Concurrency;
    /**
     * Called when the `respond` option throws or rejects. That is a bug in the test, not a
     * network failure, so by default it is rethrown as an uncaught error (Vitest fails the run).
     * The request itself still fails (as `HttpNetworkError`) so the component never hangs.
     */
    readonly onResponderError?: (error: unknown, request: HttpRequest) => void;
}
```


#### `FakeResponse`

```ts
interface FakeResponse {
    readonly status?: number;
    readonly statusText?: string;
    readonly body?: unknown;
}
```

What a fake server answers: a status (default 200) and a JSON body (omit for none).

---

# @gyral/router

> Gyral router: typed route tables, navigation as commands, History API baseline with Navigation API enhancement.

Source: https://gyral.dev/docs/api/router/

Gyral router: typed route tables, navigation as commands, History API baseline with Navigation API enhancement.

```sh
npm install @gyral/router
```

> **Writing code? Start from working code, not from this page.** [Routing](https://gyral.dev/docs/routing/). Adapt the closest example and check it, then look a name up here when you are about to call it.

Generated from the package's type declarations. Entry points: [`@gyral/router`](#gyralrouter).

## `@gyral/router`

### Functions

| Name | Summary |
| --- | --- |
| [`listen`](#router-listen) | Streams the current location, then every URL change, as messages until the component disconnects (a streaming command, ADR 0006/0009). |
| [`makeRouter`](#router-makerouter) | A router driver. |
| [`navigate`](#router-navigate) | Navigates in-app (pushes a history entry, or replaces the current one). |
| [`routes`](#router-routes) |  |
| [`setHead`](#router-sethead) | Makes the document's head this `Head` (ADR 0019): the title, `lang`/`dir`, and every managed element (description, robots, canonical, meta, links, JSON-LD). |

#### `listen`

```ts
function listen<M>(toMsg: (location: RouteLocation) => M | undefined): Command<M>;
```

Streams the current location, then every URL change, as messages until the component
disconnects (a streaming command, ADR 0006/0009). Start it from `subscriptions`, which restarts
it when a moved or re-attached component connects again (a command from `init` is not):


```ts
subscriptions: () => [listen((location) => ({ _tag: 'Routed', location }))]
```


#### `makeRouter`

```ts
function makeRouter(options?: RouterOptions): RouterDriver;
```

A router driver. Listeners are installed on first use, never at import time.

#### `navigate`

```ts
function navigate(url: string, options?: NavigateOptions): Command<never>;
```

Navigates in-app (pushes a history entry, or replaces the current one). In the browser, once
the new page has rendered, a push scrolls to the `#fragment` target or the top and resets
focus, as the browser does for a page load (ADR 0009 "Scroll and focus"); `scroll: false` or
`focusReset: false` leaves that to the app. A `replace` (keeping the query in sync with a
search box) leaves scroll and focus alone unless `scroll: true` / `focusReset: true`.

#### `routes`

```ts
function routes<const T extends RouteTable>(table: T, options?: {
    readonly matcher?: Matcher;
}): Routes<T>;
```


#### `setHead`

```ts
function setHead(head: Head): Command<never>;
```

Makes the document's head this `Head` (ADR 0019): the title, `lang`/`dir`, and every managed
element (description, robots, canonical, meta, links, JSON-LD). Managed elements the new head
doesn't name are removed; unchanged ones are not written; content from `renderPage({ extraHead })`
is never touched. The memory history records it instead. Build the head with one pure
function and pass the same function's result to the server's `renderPage()`:


```ts
Routed: (s, m) => [next, [setHead(pageHead(site.match(m.location.href), origin))]]
```


### Constants

| Name | Summary |
| --- | --- |
| [`router`](#router-router) | The default router (global window, Navigation API when available). |

#### `router`

```ts
const router: RouterDriver
```

The default router (global window, Navigation API when available).

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`AfterNavigation`](#router-afternavigation) | What the browser history does once a navigation's render has committed (ADR 0009). |
| [`LocationLike`](#router-locationlike) | What link capture and URL resolution need from a location (a `URL` qualifies). |
| [`Matcher`](#router-matcher) |  |
| [`MemoryOptions`](#router-memoryoptions) |  |
| [`NavigateOptions`](#router-navigateoptions) | Options of `navigate()`. |
| [`Params`](#router-params) | Named required strings, optional strings and trailing catch-all arrays, inferred by path. |
| [`RouteLocation`](#router-routelocation) | The document location, numbered in the order this router saw changes. |
| [`RouteMatch`](#router-routematch) | The route name discriminates its params. |
| [`RouterDriver`](#router-routerdriver) |  |
| [`RouterInput`](#router-routerinput) |  |
| [`RouterOptions`](#router-routeroptions) |  |
| [`RouterSnapshot`](#router-routersnapshot) | The router's current URL and last head, for tests and server-side assertions. |
| [`Routes`](#router-routes) |  |
| [`RouteTable`](#router-routetable) |  |

#### `AfterNavigation`

```ts
interface AfterNavigation {
    /** Scroll to the `#fragment` target or the top (push), or restore (back/forward). */
    readonly scroll: boolean;
    /** Move focus to the first `[autofocus]` element, or reset it to the page start. */
    readonly focusReset: boolean;
}
```

What the browser history does once a navigation's render has committed (ADR 0009).

#### `LocationLike`

```ts
type LocationLike = Pick<Location, 'href' | 'origin' | 'pathname' | 'search'>;
```

What link capture and URL resolution need from a location (a `URL` qualifies).

#### `Matcher`

```ts
type Matcher = 'auto' | 'urlpattern' | 'fallback';
```


#### `MemoryOptions`

```ts
interface MemoryOptions {
    /** Starting URL, absolute or relative to `origin`. Default `'/'`. */
    readonly initial?: string;
    /** Origin that relative URLs resolve against. Default `'http://localhost'`. */
    readonly origin?: string;
    /**
     * Intercept same-origin link clicks. **Default `false`** (opt in): a router that captures
     * every link on the page breaks multi-page apps where only one component routes (ADR 0009).
     */
    readonly captureLinks?: boolean;
    /**
     * Where to capture link clicks when `captureLinks` is on. Default: the (global, or the
     * browser history's) `document`. Passing an element also turns capture on and limits it to
     * that subtree; `null` turns it off. Capture is only active while a component listens.
     */
    readonly linkRoot?: EventTarget | null;
}
```


#### `NavigateOptions`

```ts
interface NavigateOptions extends Partial<AfterNavigation> {
    /** Replace the current history entry instead of pushing one. Default `false`. */
    readonly replace?: boolean;
}
```

Options of `navigate()`.

#### `Params`

```ts
type Params<Path extends string> = Path extends `${infer Head}/${infer Rest}` ? Param<Head> & Params<Rest> : Param<Path>;
```

Named required strings, optional strings and trailing catch-all arrays, inferred by path.

#### `RouteLocation`

```ts
interface RouteLocation {
    readonly href: string;
    readonly pathname: string;
    readonly search: string;
    readonly hash: string;
    /** Increases on every URL change seen by this router. */
    readonly seq: number;
}
```

The document location, numbered in the order this router saw changes.

#### `RouteMatch`

```ts
type RouteMatch<T extends RouteTable> = {
    [N in keyof T & string]: {
        readonly name: N;
        readonly params: Params<T[N]>;
        readonly path: string;
    };
}[keyof T & string];
```

The route name discriminates its params. `path` is the canonical href for those captures.

#### `RouterDriver`

```ts
interface RouterDriver extends Driver<RouterInput, RouteLocation | undefined> {
    /** The current URL and last head as this router sees them. */
    readonly snapshot: () => RouterSnapshot;
    /** Removes document listeners and ends running `listen` commands. */
    readonly dispose: () => void;
}
```


#### `RouterInput`

```ts
type RouterInput = ({
    readonly _tag: 'Navigate';
    readonly url: string;
    readonly replace: boolean;
} & Partial<AfterNavigation>) | {
    readonly _tag: 'Traverse';
    readonly delta: number;
} | {
    readonly _tag: 'Head';
    readonly head: Head;
} | {
    readonly _tag: 'Listen';
};
```


#### `RouterOptions`

```ts
interface RouterOptions extends MemoryOptions {
    /** Driver name used for substitution (`el.drivers`). Default `'router'`. */
    readonly name?: string;
    /**
     * `'browser'` (default) drives the real document. `'memory'` keeps entries in memory: no
     * global URL changes, no `window` needed (tests, servers). See `initial` and `origin`.
     * `captureLinks`/`linkRoot` apply to both histories.
     */
    readonly history?: 'browser' | 'memory';
    /** Browser history: default the global window, resolved on first use (safe on a server). */
    readonly window?: Window;
    /** Browser history: use the Navigation API when present. Default `true`. */
    readonly navigationApi?: boolean;
    /**
     * Browser history, once a navigation has rendered: scroll to the `#fragment` target or the
     * top (push) and restore the position on back/forward. Default `true`; `false` for apps that
     * manage scroll themselves. A replace never scrolls unless `navigate(url, { scroll: true })`;
     * `navigate(url, { scroll })` overrides it per call.
     */
    readonly scroll?: boolean;
    /**
     * Browser history, once a navigation has rendered: move focus to the first `[autofocus]`
     * element, or reset it to the page start, unless something took focus during the navigation
     * (a `focus('main h1')` command). Default `true` (a replace: only with `focusReset: true`).
     * `navigate(url, { focusReset })` per call.
     */
    readonly focusReset?: boolean;
}
```


#### `RouterSnapshot`

```ts
interface RouterSnapshot {
    readonly href: string;
    /** The last `setHead()` head, if any (the browser applies it to the document too). */
    readonly head: Head | undefined;
    /** Number of history entries (memory history; `history.length` in a browser). */
    readonly length: number;
}
```

The router's current URL and last head, for tests and server-side assertions.

#### `Routes`

```ts
interface Routes<T extends RouteTable> {
    readonly table: T;
    /** First route in table order matching the pathname. A string beginning with / is a path. */
    match(url: string | URL): RouteMatch<T> | undefined;
    /** Percent-encode each parameter or catch-all segment; omit absent optional parameters. */
    href<N extends keyof T & string>(name: N, params: Params<T[N]>): string;
}
```


#### `RouteTable`

```ts
type RouteTable = Readonly<Record<string, string>>;
```

---

# @gyral/time

> Gyral time: delays, debounces and wall-clock ticks (every) as commands.

Source: https://gyral.dev/docs/api/time/

Gyral time: delays, debounces and wall-clock ticks (every) as commands.

```sh
npm install @gyral/time
```

> **Writing code? Start from working code, not from this page.** [Effects and drivers](https://gyral.dev/docs/effects/). Adapt the closest example and check it, then look a name up here when you are about to call it.

Generated from the package's type declarations. Entry points: [`@gyral/time`](#gyraltime).

## `@gyral/time`

### Functions

| Name | Summary |
| --- | --- |
| [`debounce`](#time-debounce) | Sends `msg` once `ms` pass without another `debounce` in the same lane: a delay under `switch`, so each call cancels the pending one. |
| [`delay`](#time-delay) | Sends `msg` after `ms`. |
| [`every`](#time-every) | Sends `toMsg(now)` at once and then every `ms`, `now` being `Date.now()` (virtual under `virtualTime()`), until it is stopped. |

#### `debounce`

```ts
function debounce<M>(ms: number, msg: M, key?: string): Command<M>;
```

Sends `msg` once `ms` pass without another `debounce` in the same lane: a delay under
`switch`, so each call cancels the pending one.

#### `delay`

```ts
function delay<M>(ms: number, msg: M, lane?: Lane): Command<M>;
```

Sends `msg` after `ms`. By default every delay runs (`merge` in lane `time:delay`).

#### `every`

```ts
function every<M>(ms: number, toMsg: (now: number) => M | undefined, key?: string): Command<M>;
```

Sends `toMsg(now)` at once and then every `ms`, `now` being `Date.now()` (virtual under
`virtualTime()`), until it is stopped. Made for `subscriptions` (ADR 0025):
`subscriptions: (s) => (s.live ? [every(1000, (now) => ({ _tag: 'Tick', now }))] : [])`.
Each `every` runs in lane `key` (`switch`: another one in the same lane replaces it).

### Constants

| Name | Summary |
| --- | --- |
| [`time`](#time-time) | The default time driver. |

#### `time`

```ts
const time: TimeDriver
```

The default time driver.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`Frame`](#time-frame) | One animation frame: the rAF timestamp and the time since the previous frame. |
| [`Lane`](#time-lane) | Concurrency lane for a timer. |
| [`TimeDriver`](#time-timedriver) |  |
| [`TimeInput`](#time-timeinput) |  |
| [`TimeOutput`](#time-timeoutput) | Delays resolve `undefined`; `every` streams wall-clock times (`Date.now()`); frames stream `Frame`s. |

#### `Frame`

```ts
interface Frame {
    readonly time: number;
    readonly delta: number;
}
```

One animation frame: the rAF timestamp and the time since the previous frame.

#### `Lane`

```ts
interface Lane {
    /** Lane name. Default: one shared lane per command kind (see each command). */
    readonly key?: string;
    readonly concurrency?: Concurrency;
}
```

Concurrency lane for a timer. Timers in different lanes run independently.

#### `TimeDriver`

```ts
type TimeDriver = Driver<TimeInput, TimeOutput>;
```


#### `TimeInput`

```ts
type TimeInput = {
    readonly _tag: 'Delay';
    readonly ms: number;
} | {
    readonly _tag: 'Every';
    readonly ms: number;
} | {
    readonly _tag: 'Frames';
};
```


#### `TimeOutput`

```ts
type TimeOutput = undefined | number | Frame;
```

Delays resolve `undefined`; `every` streams wall-clock times (`Date.now()`); frames stream `Frame`s.

---

# @gyral/ssr

> Gyral server rendering: Declarative Shadow DOM pages with hydration seeds.

Source: https://gyral.dev/docs/api/ssr/

Gyral server rendering: Declarative Shadow DOM pages with hydration seeds.

```sh
npm install @gyral/ssr
```

> **Writing code? Start from working code, not from this page.** [Server rendering](https://gyral.dev/docs/server-rendering/). Adapt the closest example and check it, then look a name up here when you are about to call it.

Generated from the package's type declarations. Entry points: [`@gyral/ssr`](#gyralssr), [`@gyral/ssr/static`](#gyralssrstatic), [`@gyral/ssr/node`](#gyralssrnode).

## `@gyral/ssr`

### Functions

| Name | Summary |
| --- | --- |
| [`contentSecurityPolicy`](#ssr-contentsecuritypolicy) | A `Content-Security-Policy` header value whose `style-src` allows Gyral's `<style>` elements by hash, for the components registered when it is called (import them first). |
| [`formAction`](#ssr-formaction) | A request handler for a `<form method="post">` that works with JavaScript disabled, and answers the JS path (`submitForm` in `@gyral/http`, `Accept: application/json`) with JSON: valid → the handler's response, a redirect turned into `{ _tag: 'Redirected', location }`; invalid → `422` with the `IntentRejected` (without `values`). |
| [`rejectWith`](#ssr-rejectwith) | Rejects a submission that passed the schema but failed a server-only check (email taken, wrong password). |
| [`renderPage`](#ssr-renderpage) | An HTML `Response` for a full page, its body pulled in chunks from a synchronous render (one component boundary per pull): load data first, since nothing is awaited and there is no async or suspense streaming. |
| [`renderToString`](#ssr-rendertostring) | Renders to a complete string (tests, caching, static generation), with this request's stores in scope (ADR 0013). |
| [`seeOther`](#ssr-seeother) | 303 See Other: the redirect that turns a POST into a GET (no resubmit on reload). |
| [`styleHashes`](#ssr-stylehashes) | `'sha256-…'` hashes of every registered shadow component's declarative-shadow-root `<style>`, for a `Content-Security-Policy` `style-src`. |
| [`wantsJson`](#ssr-wantsjson) | Whether the request asks for JSON rather than a page (`Accept: application/json` without `text/html`): `submitForm` and other fetch calls do, a browser's form post doesn't. |

#### `contentSecurityPolicy`

```ts
function contentSecurityPolicy(options?: CspOptions): Promise<string>;
```

A `Content-Security-Policy` header value whose `style-src` allows Gyral's `<style>`
elements by hash, for the components registered when it is called (import them first).
`renderPage({ …, csp: options })` builds it at render time instead; pass this result to
`renderPage({ …, csp })` or set it on any response. Other inline styles (`style`
attributes, hand-written `<style>` in `head`) are not covered.

#### `formAction`

```ts
function formAction<Schema extends StandardSchemaV1>(definition: FormDefinition<Schema>, handlers: FormActionHandlers<StandardSchemaV1.InferOutput<Schema>>): (request: Request) => Promise<Response>;
```

A request handler for a `<form method="post">` that works with JavaScript disabled, and
answers the JS path (`submitForm` in `@gyral/http`, `Accept: application/json`) with JSON:
valid → the handler's response, a redirect turned into `{ _tag: 'Redirected', location }`;
invalid → `422` with the `IntentRejected` (without `values`). On the no-JS path `values`
never includes the definition's secret fields (`defineForm(schema, { secret })`).

#### `rejectWith`

```ts
function rejectWith(issues: string | readonly FieldIssue[]): FormReject;
```

Rejects a submission that passed the schema but failed a server-only check (email taken,
wrong password). A string is a form-level message (path `''`). `formAction` turns it into
the same `IntentRejected` as a schema failure, on both the no-JS and the JS path.

#### `renderPage`

```ts
function renderPage(options: PageOptions, init?: ResponseInit): Response;
```

An HTML `Response` for a full page, its body pulled in chunks from a synchronous render (one
component boundary per pull): load data first, since nothing is awaited
and there is no async or suspense streaming. Status and headers are final before the first
byte. `csp` sets the `Content-Security-Policy`
header: a string as is, or `contentSecurityPolicy()`'s options to build it now, with every
component registered by the time the page renders (and the page's `styles`). With
`csp: { styleAttributes: 'hash' }` the page is rendered to a string first, so the header can
list its `style` attribute values by hash (ADR 0020); a render error then throws here.
A component whose `init` or view throws renders its error view and the page goes on;
`onError` hears it, and `onError: 'throw'` renders to a string first and throws here instead,
before any byte is sent (ADR 0024).

#### `renderToString`

```ts
function renderToString(value: ChildValue, options?: RenderOptions): Promise<string>;
```

Renders to a complete string (tests, caching, static generation), with this request's stores
in scope (ADR 0013).

#### `seeOther`

```ts
function seeOther(location: string): Response;
```

303 See Other: the redirect that turns a POST into a GET (no resubmit on reload).

#### `styleHashes`

```ts
function styleHashes(): Promise<readonly string[]>;
```

`'sha256-…'` hashes of every registered shadow component's declarative-shadow-root `<style>`,
for a `Content-Security-Policy` `style-src`.

#### `wantsJson`

```ts
const wantsJson: (request: Request) => boolean
```

Whether the request asks for JSON rather than a page (`Accept: application/json` without
`text/html`): `submitForm` and other fetch calls do, a browser's form post doesn't. The rule
`formAction` answers by; for your own routes that serve both.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`ComponentAssets`](#ssr-componentassets) | The client side of automatic component loading, for `renderPage({ components })`: from `componentsFromManifest()` in production, handed over by `productionServer` and `gyralDevServer`. |
| [`ComponentModule`](#ssr-componentmodule) | One component's client module: what to preload and link when the page renders its tag. |
| [`CspDirectives`](#ssr-cspdirectives) | CSP directives by name: a source list, as one string or a list of sources. |
| [`CspOptions`](#ssr-cspoptions) |  |
| [`FormActionHandlers`](#ssr-formactionhandlers) |  |
| [`FormReject`](#ssr-formreject) | A server-side rejection of a schema-valid submission (see `rejectWith`). |
| [`PageOptions`](#ssr-pageoptions) | The page shell's options. |
| [`RenderOptions`](#ssr-renderoptions) |  |

#### `ComponentAssets`

```ts
interface ComponentAssets {
    /** URL of the loader module, which imports each rendered tag's module when it's in the page. */
    readonly loader: string;
    /** Tag → its client module. A rendered tag missing here won't hydrate (development warns). */
    readonly modules: ReadonlyMap<string, ComponentModule>;
    /** The loader's own imports, preloaded with it (production). */
    readonly preload?: readonly string[];
    /** More module scripts for pages with components (development: Vite's client). */
    readonly scripts?: readonly string[];
}
```

The client side of automatic component loading, for `renderPage({ components })`: from
`componentsFromManifest()` in production, handed over by `productionServer` and
`gyralDevServer`.

#### `ComponentModule`

```ts
interface ComponentModule {
    /** The module's chunk and its static imports (production; empty in development). */
    readonly preload: readonly string[];
    /** Hashed CSS the module imports (production; empty in development). */
    readonly stylesheets: readonly string[];
}
```

One component's client module: what to preload and link when the page renders its tag.

#### `CspDirectives`

```ts
type CspDirectives = Readonly<Record<string, string | readonly string[]>>;
```

CSP directives by name: a source list, as one string or a list of sources.

#### `CspOptions`

```ts
interface CspOptions {
    /**
     * Precomputed component `<style>` hashes from `styleHashes()` at build time. Append them
     * to registered component hashes, allowing a policy-only server to read JSON metadata
     * without executing every component module. Regenerate with each release's actual CSS.
     */
    readonly componentStyleHashes?: readonly string[];
    /**
     * Your other directives (`default-src`, `script-src`, …). A `style-src` given here is kept
     * and the hashes are appended; without one it is `'self'` plus the hashes.
     */
    readonly directives?: CspDirectives;
    /**
     * The page's global styles, exactly as passed to `renderPage({ styles })`, hashed too. In
     * `renderPage({ csp })` it defaults to the page's own `styles`.
     */
    readonly styles?: string | readonly string[];
    /**
     * The page's inline head scripts, exactly as passed to `renderPage({ headScripts })`, allowed in
     * `script-src` by hash (a `script-src` given in `directives` is kept and the hashes appended;
     * without one it is `'self'` plus the hashes). In `renderPage({ csp })` it defaults to the
     * page's own `headScripts`.
     */
    readonly scripts?: string | readonly string[];
    /**
     * `'hash'` (`renderPage` only, ADR 0020): allow the `style` attributes the page writes by
     * hash, in `style-src-attr` with `'unsafe-hashes'`, so they apply on first paint under a
     * strict policy. The page is rendered to a string before the response is built (its
     * headers need every value), so the body isn't chunked. Covers static, bound, multi-part and
     * element-hook values, not `raw()` markup. A `style-src-attr` given in `directives` is kept;
     * when it allows `'unsafe-inline'`, no hashes are added (a hash would disable it).
     */
    readonly styleAttributes?: 'hash';
    /**
     * The most `style` attribute hashes one page's header lists (default 128, about 7 KB of
     * header; proxies reject large headers). Values past it are left out and logged once;
     * hydration applies them.
     */
    readonly maxStyleHashes?: number;
}
```


#### `FormActionHandlers`

```ts
interface FormActionHandlers<T> {
    /**
     * The form's `data-intent` name. It becomes `IntentRejected.intent`, exactly as on the
     * JS path, so the component's reducer can't tell the two apart.
     */
    readonly intent: string;
    /**
     * Valid submission: do the work, then usually `seeOther(url)` (Post/Redirect/Get), or return
     * `rejectWith(…)` when a server-only check fails.
     */
    readonly valid: (data: T, request: Request) => Response | FormReject | Promise<Response | FormReject>;
    /**
     * Invalid submission without JavaScript: re-render the page with the component's
     * `.initialMessages` set to `[rejected]`, typically with status 422. The component's own
     * `IntentRejected` reducer turns it into state, so the errors render through the same view as
     * with JavaScript. Leave it out for an endpoint only `submitForm` calls: every rejection is
     * then the JSON 422.
     */
    readonly invalid?: (rejected: IntentRejected, request: Request) => Response | Promise<Response>;
}
```


#### `FormReject`

```ts
interface FormReject {
    readonly _tag: 'FormReject';
    readonly issues: readonly FieldIssue[];
}
```

A server-side rejection of a schema-valid submission (see `rejectWith`).

#### `PageOptions`

```ts
interface PageOptions extends RenderOptions, Head {
    /** The hydratable app: an `html` template, usually one custom element. */
    readonly body: ChildValue;
    /**
     * Server-only head content the head model doesn't cover, written with `html` (icons that
     * never change, preconnect hints, …). Never touched by `setHead()`.
     */
    readonly extraHead?: ChildValue;
    /**
     * Global CSS for the document (your app's own stylesheet text, e.g. a `?raw` import), written
     * as `<style>` elements in the head. A `</style` inside the text is escaped, so it can't
     * close the element early. Trusted CSS only: never put user input here.
     */
    readonly styles?: string | readonly string[];
    /**
     * Stylesheet URLs, written as `<link rel="stylesheet">` before `styles`: in production,
     * `clientAssetsFromManifest()`'s `css` (the hashed CSS Vite emitted for what the client entry
     * imports), served immutable and allowed by `style-src 'self'` without hashes.
     */
    readonly stylesheets?: readonly string[];
    /** Module scripts to load, e.g. the client entry. */
    readonly scripts?: readonly string[];
    /**
     * Inline classic scripts written early in the head, after the managed head entries and
     * before any stylesheet, so they run before the page paints (a theme script that sets
     * `data-theme` from storage, say). Trusted code only. A `</script` inside the text is escaped.
     * `renderPage({ csp })` allows them in `script-src` by hash.
     */
    readonly headScripts?: string | readonly string[];
    /**
     * Modules to fetch early with `<link rel="modulepreload">`, written before `scripts`: in
     * production, `clientAssetsFromManifest()`'s `modulepreload` (the entry's static imports and
     * the hydration chunk), so hydration doesn't wait for extra round trips.
     */
    readonly modulepreload?: readonly string[];
    /**
     * `renderPage` only: the `Content-Security-Policy` header. Pass `contentSecurityPolicy()`'s
     * options (`{ directives }`; the page's `styles` are included) to build it when the page
     * renders, with every component registered by then and the `<style>` elements allowed by
     * hash; or a header value, e.g. from `await contentSecurityPolicy({ styles })` (development
     * warns when it lacks a registered component's hash).
     */
    readonly csp?: string | CspOptions;
}
```

The page shell's options. The `Head` fields (title, description, canonical, robots, meta,
links, JSON-LD, lang, dir) are the managed head (ADR 0019): the same object a client router
applies with `setHead()` after a navigation, so build both from one function.

#### `RenderOptions`

```ts
interface RenderOptions {
    /**
     * This request's store instances (ADR 0013). Components read them during the render; a
     * store not listed starts from its `init`. Create new instances per request.
     */
    readonly stores?: readonly AnyStoreInstance[];
    /**
     * Development markers and checks. Default: on when
     * `@gyral/core` resolves with the `development` condition (Vite's dev server, Vitest).
     */
    readonly dev?: boolean;
    /**
     * A component whose `init` or view throws (ADR 0024): by default the page goes on with that
     * component's error view (or an empty host the browser starts fresh) and the `GyralError` is
     * logged with `console.error`. A function hears each failure instead (logging, monitoring).
     * `'throw'` ends the render with the failure instead; `renderPage` then renders the whole page
     * first, so it throws before any byte is sent and the route can answer with an error page.
     */
    readonly onError?: ((error: GyralError) => void) | 'throw';
    /**
     * Automatic component loading: the page links the client modules of exactly the components
     * it rendered (their preload links and the loader), after the body, and nothing when it
     * rendered none. `productionServer` and `gyralDevServer` hand it to `createApp`.
     */
    readonly components?: ComponentAssets;
}
```


## `@gyral/ssr/static`

### Functions

| Name | Summary |
| --- | --- |
| [`assetHandler`](#ssr-static-assethandler) | Serves content-hashed files from `dir` at `prefix` (`/assets/` by default) for GET and HEAD, with `cache-control: public, max-age=31536000, immutable`, `content-type` by extension, `content-length` and `x-content-type-options: nosniff`. |
| [`clientAssetsFromManifest`](#ssr-static-clientassetsfrommanifest) | `ClientAssets` for `entry`, read from a Vite build manifest (`build.manifest: true`). |
| [`componentsFromManifest`](#ssr-static-componentsfrommanifest) | `componentAssets` read from a client build directory (`dist/client`): its `.vite/manifest.json` and the preset's `.vite/gyral-components.json`. |
| [`prerender`](#ssr-static-prerender) | Renders each path through the app (exactly what a request would get) and writes the HTML. |
| [`productionServer`](#ssr-static-productionserver) | A production request handler (framework-neutral: mount its `fetch` in Hono, Node, …): - `GET`/`HEAD /assets/*`: content-hashed client build output, cached immutable (`assetHandler`); - `GET`/`HEAD` of a prerendered path: the `static/` file, revalidated on every use; - everything else (other GETs, POSTs): the request-time app, `no-cache` unless it set one. |
| [`writeComponentStyleManifest`](#ssr-static-writecomponentstylemanifest) | After the client build, automatically import its discovered/listed component modules in a temporary SSR bundle and fresh Node process, then write their real `styleHashes()` as JSON. |

#### `assetHandler`

```ts
function assetHandler(options: AssetHandlerOptions): AssetHandler;
```

Serves content-hashed files from `dir` at `prefix` (`/assets/` by default) for GET and HEAD,
with `cache-control: public, max-age=31536000, immutable`, `content-type` by extension,
`content-length` and `x-content-type-options: nosniff`. Paths that are not under `dir` after
decoding (`..`, encoded slashes leading out) or have a dot segment (`.hidden`) are refused;
a malformed escape is a 400. Misses are 404 with `cache-control: no-store`, so a CDN never
keeps a miss for a file the next deploy brings. Other methods get 405. A single-range
`Range` request gets a 206 with that slice (media seeking: Safari won't play video without
it); several ranges get the whole file. Hashed files never change, so `If-Range` isn't needed.

#### `clientAssetsFromManifest`

```ts
function clientAssetsFromManifest(manifestPath: string, entry: string, also?: readonly string[], options?: ManifestOptions): Promise<ClientAssets>;
```

`ClientAssets` for `entry`, read from a Vite build manifest (`build.manifest: true`). `also`:
manifest keys of modules the page will import lazily (a route's module, by source path such
as `src/routes/product.ts`), preloaded too, each with its static imports and CSS.
`options.base`: Vite's `base`, which every URL starts with.

#### `componentsFromManifest`

```ts
function componentsFromManifest(clientDir: string, options?: ManifestOptions): Promise<ComponentAssets | undefined>;
```

`componentAssets` read from a client build directory (`dist/client`): its
`.vite/manifest.json` and the preset's `.vite/gyral-components.json`. Undefined when the
build wasn't made with `components: true`.

#### `prerender`

```ts
function prerender(options: PrerenderOptions): Promise<readonly PrerenderedPage[]>;
```

Renders each path through the app (exactly what a request would get) and writes the HTML.
A non-200 response fails the build: an `ssg` route must render successfully.

#### `productionServer`

```ts
function productionServer<Env = unknown>(options: ProductionOptions<Env>): Promise<FetchApp<Env>>;
```

A production request handler (framework-neutral: mount its `fetch` in Hono, Node, …):
- `GET`/`HEAD /assets/*`: content-hashed client build output, cached immutable
  (`assetHandler`);
- `GET`/`HEAD` of a prerendered path: the `static/` file, revalidated on every use;
- everything else (other GETs, POSTs): the request-time app, `no-cache` unless it set one.

Its `fetch` passes the server's `env` (`toNodeListener`'s `{ incoming, remoteAddress }`) on to
the app, so the app can read the client's address.

#### `writeComponentStyleManifest`

```ts
function writeComponentStyleManifest(options: ComponentStyleManifestOptions): Promise<ComponentStyleManifest>;
```

After the client build, automatically import its discovered/listed component modules in a
temporary SSR bundle and fresh Node process, then write their real `styleHashes()` as JSON.
This executes trusted application module initialization at BUILD time: modules must be
SSR-safe. It is not AST guessing and must not run against untrusted source. Vite is loaded
only when invoked; production reads the resulting JSON into `CspOptions.componentStyleHashes`.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`AppAssets`](#ssr-static-appassets) | What `productionServer` hands `createApp`: the built entry and what pages link with it. |
| [`AssetHandler`](#ssr-static-assethandler) | Answers a request under the prefix, `undefined` for any other path. |
| [`AssetHandlerOptions`](#ssr-static-assethandleroptions) |  |
| [`ClientAssets`](#ssr-static-clientassets) | What a server-rendered page loads: the client entry, the modules to preload, the CSS. |
| [`ComponentStyleManifest`](#ssr-static-componentstylemanifest) |  |
| [`ComponentStyleManifestOptions`](#ssr-static-componentstylemanifestoptions) |  |
| [`FetchApp`](#ssr-static-fetchapp) | Anything with a fetch handler: a Hono app, or a plain function. |
| [`ManifestChunk`](#ssr-static-manifestchunk) | One chunk of Vite's `.vite/manifest.json` (the fields serving uses). |
| [`ManifestOptions`](#ssr-static-manifestoptions) | Where the build is served: Vite's `base` (default `/`), which the manifest's paths omit. |
| [`PageAssets`](#ssr-static-pageassets) | The page-level parts of `ClientAssets`, named as `renderPage` takes them. |
| [`PrerenderedPage`](#ssr-static-prerenderedpage) |  |
| [`PrerenderOptions`](#ssr-static-prerenderoptions) |  |
| [`ProductionOptions`](#ssr-static-productionoptions) |  |
| [`RenderMode`](#ssr-static-rendermode) | How a route is rendered. |
| [`ViteManifest`](#ssr-static-vitemanifest) | Vite's build manifest (`build.manifest: true`): chunks by source path or chunk key. |

#### `AppAssets`

```ts
interface AppAssets extends PageAssets {
    /** The built client entry's URL; undefined when the build has none (components only). */
    readonly clientEntry: string | undefined;
    /**
     * For `renderPage({ components })` when the build was made with
     * `gyralVitePreset({ components: true })`: each page links exactly the components it rendered.
     */
    readonly components: ComponentAssets | undefined;
    /** `modulepreload` and `stylesheets` with `modules` added (cached per list). */
    readonly assets: (modules: readonly string[]) => PageAssets;
    /** `assets(modules).modulepreload`. */
    readonly preload: (modules: readonly string[]) => readonly string[];
}
```

What `productionServer` hands `createApp`: the built entry and what pages link with it.

#### `AssetHandler`

```ts
type AssetHandler = (request: Request) => Promise<Response | undefined>;
```

Answers a request under the prefix, `undefined` for any other path. Never throws.

#### `AssetHandlerOptions`

```ts
interface AssetHandlerOptions {
    /** The directory served under `prefix`, e.g. `dist/client/assets`. */
    readonly dir: string;
    /** The URL path prefix, with both slashes. Default `/assets/`. */
    readonly prefix?: string;
    /**
     * Keep served files in memory (hashed files never change): `true` (default) up to 64 MiB,
     * `{ maxBytes }` for another bound (least recently served files are dropped first), `false`
     * to read every request from disk. Misses are never cached.
     */
    readonly cache?: boolean | {
        readonly maxBytes: number;
    };
}
```


#### `ClientAssets`

```ts
interface ClientAssets {
    /** The entry chunk's URL, for `renderPage({ scripts })`. */
    readonly entry: string;
    /**
     * Chunks the entry is known to need, for `renderPage({ modulepreload })`: the entry itself first
     * (when there is anything else), then its static imports and Gyral's lazily loaded hydration
     * chunk with its imports. Without the hints the browser
     * finds them only after it has fetched and parsed the entry (a server-rendered page would
     * fetch the hydration chunk a round trip later still).
     */
    readonly modulepreload: readonly string[];
    /**
     * The hashed CSS files of those chunks, for `renderPage({ stylesheets })`: what Vite emitted for
     * CSS imported by the entry, its static imports and the `also` modules, each chunk's after
     * its imports' (module order), each file once.
     */
    readonly css: readonly string[];
}
```

What a server-rendered page loads: the client entry, the modules to preload, the CSS.

#### `ComponentStyleManifest`

```ts
interface ComponentStyleManifest {
    readonly schema: 1;
    /** Sorted, deduplicated, quoted CSP SHA-256 sources for actual serialized shadow styles. */
    readonly hashes: readonly string[];
}
```


#### `ComponentStyleManifestOptions`

```ts
interface ComponentStyleManifestOptions {
    /** Application root used by its client build. Its component modules must be SSR-safe. */
    readonly root: string;
    /** Client output from `gyralVitePreset({ components: true })`, including `.vite` metadata. */
    readonly clientDir: string;
    /** Standalone JSON deployment artifact; no component module is needed to read it later. */
    readonly outFile: string;
    /** Build-time aliases/plugins used by application modules. No config file is loaded. */
    readonly vite?: InlineConfig;
}
```


#### `FetchApp`

```ts
interface FetchApp<Env = unknown> {
    readonly fetch: (request: Request, env?: Env) => Response | Promise<Response>;
}
```

Anything with a fetch handler: a Hono app, or a plain function. `env` is what the server
passes along (`toNodeListener`'s `{ incoming, remoteAddress }`); a prerender passes none.

#### `ManifestChunk`

```ts
interface ManifestChunk {
    readonly file: string;
    readonly imports?: readonly string[];
    readonly dynamicImports?: readonly string[];
    readonly css?: readonly string[];
}
```

One chunk of Vite's `.vite/manifest.json` (the fields serving uses).

#### `ManifestOptions`

```ts
interface ManifestOptions {
    /** Vite's `base`, e.g. `/app/` (a missing trailing slash is added). Default `/`. */
    readonly base?: string;
}
```

Where the build is served: Vite's `base` (default `/`), which the manifest's paths omit.

#### `PageAssets`

```ts
interface PageAssets {
    readonly modulepreload: readonly string[];
    readonly stylesheets: readonly string[];
}
```

The page-level parts of `ClientAssets`, named as `renderPage` takes them.

#### `PrerenderedPage`

```ts
interface PrerenderedPage {
    readonly path: string;
    readonly file: string;
    readonly status: number;
}
```


#### `PrerenderOptions`

```ts
interface PrerenderOptions {
    readonly app: FetchApp;
    /** URL paths to render, e.g. every `ssg` route of the route table. */
    readonly paths: readonly string[];
    /** Directory the HTML files go to (`/about` → `<outDir>/about/index.html`). */
    readonly outDir: string;
    /** Origin used for the requests (absolute URLs in canonical links etc.). */
    readonly origin?: string;
}
```


#### `ProductionOptions`

```ts
interface ProductionOptions<Env = unknown> {
    /** Build output: `client/` (Vite, with `.vite/manifest.json`) and `static/` (prerendered). */
    readonly distDir: string;
    /**
     * The client entry as named in the Vite manifest. Default `src/entry-client.ts`. A build made
     * with `gyralVitePreset({ components: true })` may have none: pages then load components
     * through `components` alone.
     */
    readonly entry?: string;
    /**
     * The directory served at `/assets/`. Default `<distDir>/client/assets`; point it at a
     * directory that keeps older releases' hashed files too, so tabs opened before a deploy keep
     * loading their chunks.
     */
    readonly assetsDir?: string;
    /**
     * Prerendered pages. Default `<distDir>/static`; `false` when the app prerenders nothing, so
     * page requests don't look for files first.
     */
    readonly staticDir?: string | false;
    /**
     * Vite's `base` when the build is served under a path (e.g. `/app/`): the entry, preload and
     * stylesheet URLs start with it, and assets are served at `<base>assets/`. Default `/`.
     */
    readonly base?: string;
    /** Keep served assets in memory (`assetHandler`'s `cache`). Default `true`. */
    readonly cache?: boolean | {
        readonly maxBytes: number;
    };
    /**
     * Builds the request-time renderer (the same app the prerender step used). Pass
     * `modulepreload` and `stylesheets` on to `renderPage` so pages preload what the entry needs
     * and link its hashed CSS. A page that imports modules lazily (a route's chunk) spreads
     * `assets(modules)` instead: both lists plus those modules, their imports and their CSS
     * (`clientAssetsFromManifest`' `also`). `preload(modules)` is `assets(modules).modulepreload`.
     */
    readonly createApp: (options: AppAssets) => FetchApp<Env>;
    /**
     * Sees every response before it goes out (built assets, prerendered pages and the app's), to
     * add headers such as a CSP or security headers, or cookies. Return the response to send.
     */
    readonly onResponse?: (response: Response, request: Request) => Response | Promise<Response>;
}
```


#### `RenderMode`

```ts
type RenderMode = 'ssg' | 'ssr' | 'csr';
```

How a route is rendered.

#### `ViteManifest`

```ts
type ViteManifest = Readonly<Record<string, ManifestChunk>>;
```

Vite's build manifest (`build.manifest: true`): chunks by source path or chunk key.

## `@gyral/ssr/node`

### Functions

| Name | Summary |
| --- | --- |
| [`gyralDevServer`](#ssr-node-gyraldevserver) | Starts the development server of a server-rendered app: |
| [`toNodeListener`](#ssr-node-tonodelistener) | A `node:http` request listener that runs `fetch` for each request: - the `Request` gets the method, URL (on `origin`), headers and, for methods other than `GET`/`HEAD`, the body as a stream; its `signal` aborts when the client disconnects; - the `Response` body is piped with backpressure (a slow client pauses the stream, so a `renderPage` body renders as fast as it is read) and cancelled on disconnect; - `HEAD` sends the headers only; each `set-cookie` stays its own header; - an unparsable request target is a 400; a throwing handler a 500 (`onError` sees it); - the handler's second argument is a {@link NodeEnv}: `{ incoming, remoteAddress }`. |

#### `gyralDevServer`

```ts
function gyralDevServer<M, S = undefined>(options: DevServerOptions<M, S>): Promise<DevServer>;
```

Starts the development server of a server-rendered app:


```ts
await gyralDevServer({
  entry: '/server/app.ts',
  app: (mod: typeof import('./app.js'), { components }) => mod.createApp({ components }),
});
```

Client modules, CSS and HMR come from Vite (middleware mode); any other request renders
through the app, streamed. A render error answers 500 with Vite's error overlay.

#### `toNodeListener`

```ts
function toNodeListener(fetch: FetchHandler, options?: NodeListenerOptions): NodeListener;
```

A `node:http` request listener that runs `fetch` for each request:
- the `Request` gets the method, URL (on `origin`), headers and, for methods other than
  `GET`/`HEAD`, the body as a stream; its `signal` aborts when the client disconnects;
- the `Response` body is piped with backpressure (a slow client pauses the stream, so a
  `renderPage` body renders as fast as it is read) and cancelled on disconnect;
- `HEAD` sends the headers only; each `set-cookie` stays its own header;
- an unparsable request target is a 400; a throwing handler a 500 (`onError` sees it);
- the handler's second argument is a {@link NodeEnv}: `{ incoming, remoteAddress }`.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`DevApp`](#ssr-node-devapp) | A request handler: a Hono app, `productionServer`'s result, or `{ fetch }`. |
| [`DevServer`](#ssr-node-devserver) |  |
| [`DevServerContext`](#ssr-node-devservercontext) | What `gyralDevServer` hands the app factory with each freshly loaded module. |
| [`DevServerOptions`](#ssr-node-devserveroptions) |  |
| [`FetchHandler`](#ssr-node-fetchhandler) | A fetch handler: `productionServer(…).fetch`, a Hono app's `fetch`, or a plain function. |
| [`NodeEnv`](#ssr-node-nodeenv) | What `toNodeListener` passes as the handler's second argument: the Node request and the client's address. |
| [`NodeListener`](#ssr-node-nodelistener) | A Node `request` listener: `createServer(toNodeListener(app.fetch))`. |
| [`NodeListenerOptions`](#ssr-node-nodelisteneroptions) |  |

#### `DevApp`

```ts
interface DevApp {
    readonly fetch: (request: Request, env: NodeEnv) => Response | Promise<Response>;
}
```

A request handler: a Hono app, `productionServer`'s result, or `{ fetch }`.

#### `DevServer`

```ts
interface DevServer {
    /** `http://host:port/` the server listens on. */
    readonly url: string;
    readonly server: Server;
    readonly vite: ViteDevServer;
    /** Stops the HTTP server and Vite. */
    readonly close: () => Promise<void>;
}
```


#### `DevServerContext`

```ts
interface DevServerContext<S> {
    /**
     * For `renderPage({ components })` when the Vite config uses `gyralVitePreset({ components })`:
     * the loader and the tags it knows. Undefined otherwise.
     */
    readonly components: ComponentAssets | undefined;
    /** The value `state` created once, kept across module reloads. */
    readonly state: S;
}
```

What `gyralDevServer` hands the app factory with each freshly loaded module.

#### `DevServerOptions`

```ts
interface DevServerOptions<M, S> {
    /** The server module, from Vite's root (e.g. `/server/app.ts`), loaded per request. */
    readonly entry: string;
    /** Builds the request handler from the module just loaded. */
    readonly app: (module: M, context: DevServerContext<S>) => DevApp;
    /**
     * State that must outlive module reloads (an in-memory database, say): created once, from the
     * first module loaded, and passed to every `app` call.
     */
    readonly state?: (module: M) => S;
    /** Default: the `PORT` environment variable, else 5173. `0` picks a free port. */
    readonly port?: number;
    /** Default: Node's (all interfaces). */
    readonly host?: string;
    /** The HMR WebSocket's port, so several dev servers can run side by side. Default Vite's. */
    readonly hmrPort?: number;
    /** `toNodeListener`'s `origin`: the public origin when absolute URLs matter. */
    readonly origin?: string;
    /** More Vite settings (root, configFile, plugins, …), merged under the server settings. */
    readonly vite?: InlineConfig;
}
```


#### `FetchHandler`

```ts
type FetchHandler = (request: Request, env: NodeEnv) => Response | Promise<Response>;
```

A fetch handler: `productionServer(…).fetch`, a Hono app's `fetch`, or a plain function. Under
`toNodeListener` it also receives a {@link NodeEnv}; handlers that don't need it ignore it.

#### `NodeEnv`

```ts
interface NodeEnv {
    /** The Node request, for anything `Request` doesn't carry (socket, TLS details). */
    readonly incoming: IncomingMessage;
    /**
     * The peer's IP address (`req.socket.remoteAddress`), or `undefined` once the socket is gone.
     * Behind a proxy this is the proxy: read `X-Forwarded-For` only when the proxy is known.
     */
    readonly remoteAddress: string | undefined;
}
```

What `toNodeListener` passes as the handler's second argument: the Node request
and the client's address. `{ incoming }` is the shape Hono's Node adapter uses, so
`getConnInfo` from `@hono/node-server/conninfo` works unchanged.

#### `NodeListener`

```ts
type NodeListener = (req: IncomingMessage, res: ServerResponse) => void;
```

A Node `request` listener: `createServer(toNodeListener(app.fetch))`.

#### `NodeListenerOptions`

```ts
interface NodeListenerOptions {
    /**
     * The origin request URLs are built on, e.g. `https://example.com` behind a proxy. Default:
     * `http://` (`https://` on a TLS socket) plus the request's `Host` header, which the client
     * chooses: set it when the app writes absolute URLs (canonical links, redirects).
     */
    readonly origin?: string;
    /**
     * Called when the handler throws or the response body fails, before the 500 (or, once the
     * headers are out, before the connection is cut). Default: `console.error`.
     */
    readonly onError?: (error: unknown, request: Request) => void;
}
```

---

# @gyral/testing

> Gyral test helpers: pure update stepping, command helpers, fake drivers, virtual time, SSR page mounting, server rendering in Vitest browser tests.

Source: https://gyral.dev/docs/api/testing/

Gyral test helpers: pure update stepping, command helpers, fake drivers, virtual time, SSR page mounting, server rendering in Vitest browser tests.

```sh
npm install @gyral/testing
```

> **Writing code? Start from working code, not from this page.** [Testing](https://gyral.dev/docs/testing/). Adapt the closest example and check it, then look a name up here when you are about to call it.

Generated from the package's type declarations. Entry points: [`@gyral/testing`](#gyraltesting), [`@gyral/testing/vitest`](#gyraltestingvitest).

## `@gyral/testing`

### Functions

| Name | Summary |
| --- | --- |
| [`callsIn`](#testing-callsin) | The element method calls among the commands (`call(selector, method, ...args)`), in order: |
| [`collectErrors`](#testing-collecterrors) | Starts collecting every `GyralError` Gyral reports, so deliberate failures don't fail the test run. |
| [`commandsFor`](#testing-commandsfor) | The commands addressed to `driver` (matched by name, so fakes and real drivers agree). |
| [`fakeDriver`](#testing-fakedriver) | A recording driver for DOM-level tests: `el.drivers = { http: fakeDriver(http) }`. |
| [`focusTargetsIn`](#testing-focustargetsin) | The focus requests among the commands (`focus(selector, options)`), in order: |
| [`hydrated`](#testing-hydrated) | Waits until the page's Gyral components have rendered (see `settled()`): releases lazy islands if asked, then `await settled()`. |
| [`initial`](#testing-initial) | Runs `init` without a DOM. |
| [`inputsFor`](#testing-inputsfor) | The inputs of the commands addressed to `driver`; given a store, the messages the commands `send()` to it, in order (ADR 0013). |
| [`mount`](#testing-mount) | Creates `component` (a class from `define()` or a registered tag name), sets `props`, `attrs`, `drivers` and `stores`, appends it, and waits for its first render. |
| [`mountSsr`](#testing-mountssr) | Mounts server output: a full document (head + body) or a body fragment. |
| [`outputsIn`](#testing-outputsin) | The outputs the commands send to the parent component (`emit`, `outputs<O>()`), in order. |
| [`parse`](#testing-parse) | Runs the parser of intent `name` with `input` (only the fields the parser reads are needed: `{ value: '3' }`, `{ key: 'Enter' }`, `{ detail }`). |
| [`reject`](#testing-reject) | The message a command produces if its driver fails with `error` (already typed, i.e. |
| [`resetDocumentStores`](#testing-resetdocumentstores) | Tests only: forget the document default so each test starts clean. |
| [`resolve`](#testing-resolve) | The message a command produces if its driver succeeds with `output`. |
| [`run`](#testing-run) | Folds messages through `update`, collecting every command (including `init`'s). |
| [`step`](#testing-step) | Feeds one message through `update` without a DOM. |
| [`stepStore`](#testing-stepstore) | Feeds one message through a store's `update` without an instance. |
| [`subscriptionsFor`](#testing-subscriptionsfor) | The commands `spec.subscriptions` asks to keep running for `state` and `props` (ADR 0025), without a DOM: `subscriptionsFor(Clock.spec, { live: true })`. |
| [`viewOf`](#testing-viewof) | Calls a component's pure view without mounting, a DOM shim or consumer casts. |
| [`virtualTime`](#testing-virtualtime) | Replaces timers and `Date` with a virtual clock (ADR 0006, "Testing"). |

#### `callsIn`

```ts
function callsIn(commands: ReadonlyArray<Command<unknown>>): readonly CallInput[];
```

The element method calls among the commands (`call(selector, method, ...args)`), in order:


```ts
expect(callsIn(next.commands)).toEqual([{ selector: 'video', method: 'play', args: [] }]);
```


#### `collectErrors`

```ts
function collectErrors(): CollectedErrors;
```

Starts collecting every `GyralError` Gyral reports, so deliberate failures don't fail the
test run. Errors that aren't Gyral's are left alone. Call `stop()` when the test ends.

#### `commandsFor`

```ts
function commandsFor<I, M>(commands: ReadonlyArray<Command<M>>, driver: Driver<I, unknown> | Named): ReadonlyArray<Command<M> & {
    readonly input: I;
}>;
```

The commands addressed to `driver` (matched by name, so fakes and real drivers agree).

#### `fakeDriver`

```ts
function fakeDriver<I = unknown, O = unknown, E = unknown>(of: string | Driver<I, O, E>, optionsOrRun?: FakeOptions<I, O, E> | FakeRun<I, O>): FakeDriver<I, O, E>;
```

A recording driver for DOM-level tests: `el.drivers = { http: fakeDriver(http) }`.
Pass a real driver to copy its name and concurrency, or just a name. Failures pass
through unchanged unless you give `toError`, so `rejectNext(error)` takes the typed error.
A function as the second argument answers every call (`impl`):


```ts
el.drivers = { 'url-sync': fakeDriver<string | null, void>('url-sync', (q) => void urls.push(q)) };
```

Fakes go into `el.drivers` and `provideDrivers` as they are, with no cast.

#### `focusTargetsIn`

```ts
function focusTargetsIn(commands: ReadonlyArray<Command<unknown>>): readonly FocusTarget[];
```

The focus requests among the commands (`focus(selector, options)`), in order:


```ts
expect(focusTargetsIn(next.commands)).toEqual([{ selector: '#results' }]);
```


#### `hydrated`

```ts
function hydrated(page: MountedSsr | ParentNode, options?: HydratedOptions): Promise<void>;
```

Waits until the page's Gyral components have rendered (see `settled()`): releases lazy islands if asked, then `await settled()`. Islands still
deferred are left alone. It throws when a server-rendered custom element never upgraded
(import its module, or list it in `allowUndefined`). Given a `MountedSsr`, it also throws
when console errors/warnings or uncaught errors were recorded since mounting.

#### `initial`

```ts
function initial<S, M extends Tagged, P>(spec: ComponentSpec<S, M, P>, props?: P): Stepped<S, M>;
```

Runs `init` without a DOM. `props` defaults to `{}`.

#### `inputsFor`

```ts
function inputsFor<S, SM extends Tagged>(commands: ReadonlyArray<Command<unknown>>, store: Store<S, SM>): readonly SM[];
function inputsFor<I, M>(commands: ReadonlyArray<Command<M>>, driver: Driver<I, unknown> | Named): readonly I[];
```

The inputs of the commands addressed to `driver`; given a store, the messages the commands
`send()` to it, in order (ADR 0013).

#### `mount`

```ts
function mount<K extends keyof HTMLElementTagNameMap>(tag: K, options?: MountOptions<HTMLElementTagNameMap[K]>): Promise<Mounted<HTMLElementTagNameMap[K]>>;
function mount<E extends HTMLElement>(component: Constructor<E> | string, options?: MountOptions<E>): Promise<Mounted<E>>;
```

Creates `component` (a class from `define()` or a registered tag name), sets `props`,
`attrs`, `drivers` and `stores`, appends it, and waits for its first render.

#### `mountSsr`

```ts
function mountSsr(html: string, options?: MountSsrOptions): MountedSsr;
```

Mounts server output: a full document (head + body) or a body fragment. Call it before
importing component modules so elements upgrade and hydrate like on a real page load.
- Only `<head>` styles are applied: `<style>` inside Declarative Shadow DOM belongs to its
  shadow root and must not leak into the page.
- The store seed, named `<meta>`s and the managed head are restored, as the browser would
  see them.

#### `outputsIn`

```ts
function outputsIn<C extends WithOutputs>(commands: ReadonlyArray<Command<unknown>>, component: C): ReadonlyArray<OutputsOf<C>>;
function outputsIn<O extends Tagged = Tagged>(commands: ReadonlyArray<Command<unknown>>): readonly O[];
```

The outputs the commands send to the parent component (`emit`, `outputs<O>()`), in order.
Pass the component class to type them by its output union (`OutputsOf<typeof Item>`):


```ts
expect(outputsIn(next.commands, Item)).toEqual([{ _tag: 'Picked', id: 1 }]);
```

The outputs, typed by the union you name: `outputsIn<Out>(commands)`.

#### `parse`

```ts
function parse<S, M extends Tagged, P, N extends string, K extends N>(component: SpecOf<S, M, P, N>, name: K, input?: Partial<IntentInput>, options?: ParseOptions<NoInfer<S>, NoInfer<P>>): Parsed<M, K> | IntentRejected | undefined | Promise<Parsed<M, K> | IntentRejected | undefined>;
```

Runs the parser of intent `name` with `input` (only the fields the parser reads are needed:
`{ value: '3' }`, `{ key: 'Enter' }`, `{ detail }`). Returns what the parser returns: a
message, an `IntentRejected`, `undefined` (ignored or declined), or a promise of one.

#### `reject`

```ts
function reject<M>(command: Command<M>, error: unknown): M | undefined;
```

The message a command produces if its driver fails with `error` (already typed, i.e.
after the driver's `toError`). `undefined` when the command has no `onFailure`.

#### `resetDocumentStores`

```ts
function resetDocumentStores(): void;
```

Tests only: forget the document default so each test starts clean.

#### `resolve`

```ts
function resolve<M>(command: Command<M>, output: unknown): M | undefined;
```

The message a command produces if its driver succeeds with `output`.

#### `run`

```ts
function run<S, M extends Tagged, P>(spec: ComponentSpec<S, M, P>, messages: ReadonlyArray<NoInfer<StepMessage<M, P>>>, options?: NoInfer<RunOptions<S, P>>): Ran<S, M>;
```

Folds messages through `update`, collecting every command (including `init`'s).

#### `step`

```ts
function step<S, M extends Tagged, P>(spec: ComponentSpec<S, M, P>, state: NoInfer<S>, msg: NoInfer<StepMessage<M, P>>, props?: NoInfer<P>, stores?: readonly AnyStoreInstance[]): Stepped<S, M>;
```

Feeds one message through `update` without a DOM. Framework messages (`PropsChanged`,
`IntentRejected`, `StoreChanged`, `Hydrated`, `Errored`) without a reducer leave state unchanged, as in
the element. `stores` are the instances `ctx.read()` sees.

#### `stepStore`

```ts
function stepStore<S, M extends Tagged>(store: Store<S, M>, state: NoInfer<S>, msg: NoInfer<M>): Stepped<S, M>;
```

Feeds one message through a store's `update` without an instance.

#### `subscriptionsFor`

```ts
function subscriptionsFor<S, M extends Tagged, P>(spec: ComponentSpec<S, M, P>, state: NoInfer<S>, props?: NoInfer<P>): ReadonlyArray<Command<M>>;
```

The commands `spec.subscriptions` asks to keep running for `state` and `props` (ADR 0025),
without a DOM: `subscriptionsFor(Clock.spec, { live: true })`. A spec without the field gives
none. Assert their inputs with `inputsFor`, as for any commands.

#### `viewOf`

```ts
function viewOf<S, M extends Tagged, P, N extends string>(component: ComponentSpec<S, M, P, N> | GyralElementClass<S, M, P, Tagged, N>, state: NoInfer<S>, options?: ViewOptions<NoInfer<P>>): ChildValue;
```

Calls a component's pure view without mounting, a DOM shim or consumer casts. Use
`renderToString(viewOf(Component, state, { props, stores }), { dev: false })` for stable
HTML assertions. Hooks, native validity, focus and hydration need real-browser tests.

#### `virtualTime`

```ts
function virtualTime(): VirtualTime;
```

Replaces timers and `Date` with a virtual clock (ADR 0006, "Testing"). It patches the
platform rather than Gyral's runtime, so it covers drivers, debounces and retry delays
alike and does not depend on how the interpreter is implemented. Microtasks stay real,
so promises and the runtime keep working. Animation frames are faked only where they exist,
so model and driver tests can use it in a Node project.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`CollectedErrors`](#testing-collectederrors) | The failures collected so far; `stop()` removes the listeners. |
| [`FakeCall`](#testing-fakecall) | One recorded `run` of a fake driver. |
| [`FakeDriver`](#testing-fakedriver) |  |
| [`FakeOptions`](#testing-fakeoptions) |  |
| [`FakeRun`](#testing-fakerun) | What a fake answers each call with (`FakeOptions.impl`). |
| [`FocusTarget`](#testing-focustarget) | What a `focus()` command asks for: the selector and its options. |
| [`HydratedOptions`](#testing-hydratedoptions) |  |
| [`Mounted`](#testing-mounted) |  |
| [`MountedSsr`](#testing-mountedssr) |  |
| [`MountOptions`](#testing-mountoptions) |  |
| [`MountSsrOptions`](#testing-mountssroptions) |  |
| [`ParseOptions`](#testing-parseoptions) | What `parse` passes the parser besides the input. |
| [`Ran`](#testing-ran) |  |
| [`RunOptions`](#testing-runoptions) |  |
| [`StepMessage`](#testing-stepmessage) | Any message `update` accepts: the component's own, or a framework message. |
| [`Stepped`](#testing-stepped) | A reducer result, normalised: the new state plus the commands it asked for. |
| [`ViewOptions`](#testing-viewoptions) |  |
| [`VirtualTime`](#testing-virtualtime) | Controls time in a test. |
| [`WithOutputs`](#testing-withoutputs) | Anything carrying a component's output union: a `define()` class. |

#### `CollectedErrors`

```ts
interface CollectedErrors {
    readonly errors: readonly GyralError[];
    /** Stops collecting; later failures are reported as usual. */
    stop(): void;
}
```

The failures collected so far; `stop()` removes the listeners.

#### `FakeCall`

```ts
interface FakeCall<I, O> {
    readonly input: I;
    readonly signal: AbortSignal;
    /** Settles this call (only for fakes without `impl`). */
    readonly resolve: (output: O) => void;
    readonly reject: (error: unknown) => void;
    /** Streams a value into this call (DriverContext.emit); ignored once settled or aborted. */
    readonly emit: (output: O) => void;
    readonly settled: boolean;
}
```

One recorded `run` of a fake driver.

#### `FakeDriver`

```ts
interface FakeDriver<I, O, E> extends Driver<I, O, E> {
    readonly calls: ReadonlyArray<FakeCall<I, O>>;
    /** Inputs of every call so far. */
    readonly inputs: readonly I[];
    /** Settles the oldest unsettled, non-aborted call. Throws if there is none. */
    resolveNext(output: O): void;
    rejectNext(error: unknown): void;
    /** Streams a value into the newest call that is still running. Throws if there is none. */
    emitNext(output: O): void;
}
```


#### `FakeOptions`

```ts
interface FakeOptions<I, O, E> {
    /** Answer calls immediately. Without it, calls wait for `resolveNext`/`rejectNext`. */
    readonly impl?: FakeRun<I, O>;
    readonly concurrency?: Concurrency;
    readonly toError?: (cause: unknown) => E;
}
```


#### `FakeRun`

```ts
type FakeRun<I, O> = (input: I, ctx: DriverContext<O>) => O | Promise<O>;
```

What a fake answers each call with (`FakeOptions.impl`).

#### `FocusTarget`

```ts
interface FocusTarget extends FocusOptions {
    readonly selector: string;
}
```

What a `focus()` command asks for: the selector and its options.

#### `HydratedOptions`

```ts
interface HydratedOptions {
    /**
     * Custom element tags allowed to stay undefined (never upgraded). `gyral-stores` is always
     * allowed: in the browser it is a plain scoping element.
     */
    readonly allowUndefined?: readonly string[];
    /**
     * Release every lazy island first (`defer-hydration` + `data-gyral-hydrate`), as if each
     * one's trigger had fired. Default `false`: islands keep waiting.
     */
    readonly releaseIslands?: boolean;
}
```


#### `Mounted`

```ts
interface Mounted<E extends HTMLElement> {
    readonly el: E;
    /** The first match in the element's shadow root (or light DOM), or null. */
    $(selector: string): HTMLElement | null;
    /** Every match in the element's shadow root (or light DOM). */
    $$(selector: string): HTMLElement[];
    /** Sets a control's value as typing would, fires `input` and `change`, then waits. */
    type(selector: string, text: string): Promise<void>;
    /** Clicks the first match, then waits. */
    click(selector: string): Promise<void>;
    /** Waits until rendering, commands and messages have settled (`settled()`). */
    settled(): Promise<void>;
    /** Removes the element (and its overrides with it). */
    dispose(): void;
}
```


#### `MountedSsr`

```ts
interface MountedSsr {
    /** The element holding the server body (Declarative Shadow DOM already parsed). */
    readonly root: HTMLElement;
    /** Console errors/warnings and uncaught errors seen since mounting (see `hydrated`). */
    readonly problems: readonly string[];
    readonly unmount: () => void;
}
```


#### `MountOptions`

```ts
interface MountOptions<E extends HTMLElement> {
    /** Props, set as properties before the element connects. */
    readonly props?: PropsOf<E> & Readonly<Record<string, unknown>>;
    /** Attributes, set before the element connects. */
    readonly attrs?: Readonly<Record<string, string>>;
    /** Driver substitutions by name (`el.drivers`), set before the element connects. */
    readonly drivers?: DriverOverrides;
    /** Store instances by name (`el.stores`), set before the element connects. */
    readonly stores?: StoreOverrides;
    /** Query the element's light DOM instead of its shadow root (for `shadow: false`). */
    readonly light?: boolean;
    /** Where to append the element. Default `document.body`. */
    readonly parent?: ParentNode;
}
```


#### `MountSsrOptions`

```ts
interface MountSsrOptions {
    /** Restore the page-level store seed (`data-gyral-stores`). Default `true`. */
    readonly stores?: boolean;
    /** Copy `<meta name=…>` elements from the head (e.g. a CSRF token). Default `true`. */
    readonly metas?: boolean;
    /**
     * Copy the managed head (ADR 0019: elements marked `data-gyral-head`) right after the
     * document's `<title>`, as the server wrote it, so a test can check that the client's first
     * `setHead()` adopts it without writing. Default `true`.
     */
    readonly head?: boolean;
}
```


#### `ParseOptions`

```ts
interface ParseOptions<S, P> {
    /** Props as the component sees them. Default `{}`. */
    readonly props?: P;
    /** The state when the event fires. Default: the component's initial state for `props`. */
    readonly state?: S;
    /** Store instances `ctx.read` resolves (ADR 0013). */
    readonly stores?: readonly AnyStoreInstance[];
}
```

What `parse` passes the parser besides the input.

#### `Ran`

```ts
interface Ran<S, M> extends Stepped<S, M> {
    /** State after each message, in order. */
    readonly states: readonly S[];
}
```


#### `RunOptions`

```ts
interface RunOptions<S, P> {
    readonly props?: P;
    /** Store instances `ctx.read()` sees. */
    readonly stores?: readonly AnyStoreInstance[];
    /** Start from this state instead of `init(props)` (whose commands are then skipped). */
    readonly state?: S;
}
```


#### `StepMessage`

```ts
type StepMessage<M, P> = M | PropsChanged<P> | IntentRejected | StoreChanged | Hydrated | Errored;
```

Any message `update` accepts: the component's own, or a framework message.

#### `Stepped`

```ts
interface Stepped<S, M> {
    readonly state: S;
    readonly commands: ReadonlyArray<Command<M>>;
}
```

A reducer result, normalised: the new state plus the commands it asked for.

#### `ViewOptions`

```ts
interface ViewOptions<P> {
    readonly props?: P;
    readonly stores?: readonly AnyStoreInstance[];
}
```


#### `VirtualTime`

```ts
interface VirtualTime {
    /** Advances the clock, running due timers and the promise work between them. */
    advance(ms: number): Promise<void>;
    /** Runs every pending timer (and timers they schedule) until none remain. */
    runAll(): Promise<void>;
    /** Current virtual time in ms (`Date.now()` while installed). */
    now(): number;
    restore(): void;
}
```

Controls time in a test. Always `restore()` (for example in `afterEach`).

#### `WithOutputs`

```ts
interface WithOutputs {
    /** Type-only, as on `GyralElementClass`. */
    readonly outputs?: Tagged;
}
```

Anything carrying a component's output union: a `define()` class.

## `@gyral/testing/vitest`

### Functions

| Name | Summary |
| --- | --- |
| [`renderOnServer`](#testing-vitest-renderonserver) | The browser command: `browser: { commands: { renderOnServer } }` in vitest.config.ts, then in a browser test: |

#### `renderOnServer`

```ts
const renderOnServer: BrowserCommand<[ServerRenderRequest], string>
```

The browser command: `browser: { commands: { renderOnServer } }` in vitest.config.ts, then in
a browser test:


```ts
import { commands } from 'vitest/browser';
const page = mountSsr(await commands.renderOnServer({ module: '../src/counter.ts',
  export: 'Counter', props: { start: 3 } }));
await import('../src/counter.ts'); // hydrates in place
await hydrated(page);
```


### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`ServerRenderRequest`](#testing-vitest-serverrenderrequest) | What `renderOnServer` renders. |

#### `ServerRenderRequest`

```ts
interface ServerRenderRequest {
    /**
     * The module to load on the server: relative to the test file (`'../src/counter.ts'`), an
     * absolute path, a path from the project root (`'/src/app.ts'`) or a package specifier.
     */
    readonly module: string;
    /**
     * The export to render (default `'default'`):
     * - a `define()` class: renders its element, with `props` set as properties;
     * - a function: called with `props`; it may return (or resolve to) a template result, an
     *   HTML string or a `Response` (a full page from `@gyral/ssr`'s `renderPage`, an app's
     *   `fetch` handler…);
     * - a template result: rendered as is.
     */
    readonly export?: string;
    /** Props for a component class, or the argument of a function export. */
    readonly props?: Readonly<Record<string, unknown>>;
    /**
     * Development markers and checks (`render`'s `dev` option). Default: the build of core the
     * server loads (development in Vitest).
     */
    readonly dev?: boolean;
}
```

What `renderOnServer` renders. Everything is sent from the browser, so it must be JSON.

---

# @gyral/devtools

> Gyral devtools: an in-page timeline of messages, state, commands and stores (development builds).

Source: https://gyral.dev/docs/api/devtools/

Gyral devtools: an in-page timeline of messages, state, commands and stores (development builds).

```sh
npm install @gyral/devtools
```

> **Writing code? Start from working code, not from this page.** [Devtools](https://gyral.dev/docs/devtools/). Adapt the closest example and check it, then look a name up here when you are about to call it.

Generated from the package's type declarations. Entry points: [`@gyral/devtools`](#gyraldevtools).

## `@gyral/devtools`

### Functions

| Name | Summary |
| --- | --- |
| [`mountDevtools`](#devtools-mountdevtools) | Mounts the panel and starts listening. |

#### `mountDevtools`

```ts
function mountDevtools(options?: DevtoolsOptions): MountedDevtools;
```

Mounts the panel and starts listening. Events arrive in batches (one per microtask), so a
burst of messages renders once. Returns a handle to remove everything again.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`DevtoolsOptions`](#devtools-devtoolsoptions) |  |
| [`MountedDevtools`](#devtools-mounteddevtools) |  |

#### `DevtoolsOptions`

```ts
interface DevtoolsOptions {
    /** Start with the panel open. Default false. */
    readonly open?: boolean;
    /** Where to append the panel. Default document.body. */
    readonly parent?: Element;
    /** Toggle shortcut: a KeyboardEvent.code with Alt+Shift. Default 'KeyD' (Alt+Shift+D). */
    readonly shortcutCode?: string;
}
```


#### `MountedDevtools`

```ts
interface MountedDevtools {
    readonly panel: InstanceType<typeof DevtoolsPanel>;
    /** Removes the panel, the hook and the shortcut. */
    readonly unmount: () => void;
}
```

---

# Coming from Cycle.js

> What Gyral keeps from Cycle.js, what it changes and why, the counter side by side, and how Cycle.js concepts map to Gyral.

Source: https://gyral.dev/docs/coming-from-cyclejs/

Gyral is inspired by [Cycle.js](https://cycle.js.org), by André Staltz and the Cycle.js core
team. If you know Cycle.js, most of Gyral's ideas will be familiar. What's new is what they're
built on: custom elements, Shadow DOM, a small template layer of its own and plain messages
instead of streams.

## What stays: the loop and effects as data

- **Your app is pure.** In Cycle.js, `main(sources)` returns sinks; drivers do the side
  effects. In Gyral, `update` and `view` are pure and drivers run commands. Both can be tested
  without a DOM.
- **Model-View-Intent.** The same three parts, kept separate.
- **Effects as data.** A request is a description, not a call.
- **Fractal components.** Every component is a small app with the same shape as the whole.
- **Deterministic async tests.** Cycle's `@cycle/time` had virtual time; `@gyral/testing` has
  `virtualTime()`.

## What changes: no streams, parsed intent, the platform

| Cycle.js                                | What hurt                                      | Gyral                                         |
| --------------------------------------- | ---------------------------------------------- | --------------------------------------------- |
| Streams for everything                  | A steep learning curve; events and state mixed | Messages and reducers                         |
| xstream, RxJS and most.js adapters      | Three times the API surface                    | No stream library                             |
| `DOM.select('.cls').events('click')`    | Stringly typed, fragile, heavy delegation code | Typed `data-intent` names, parsed intents     |
| `isolate()` scopes                      | The most complex part of the codebase          | Shadow DOM                                    |
| Snabbdom virtual DOM                    | Diffing on every render                        | Templates that update only changed parts      |
| Sink proxies in `run()`                 | Circular wiring that was hard to follow        | Each element owns its loop                    |
| `@cycle/state` lenses, `makeCollection` | Awkward lists                                  | Child elements and `each()`                   |
| `@cycle/html`                           | Little server-rendering story                  | Declarative Shadow DOM that hydrates in place |
| Cycle-only components                   | No interop                                     | Standard custom elements                      |

## Side by side: the counter

Cycle.js, from its examples:

```js
// Cycle.js (xstream), not Gyral
function main(sources) {
  const action$ = xs.merge(
    sources.DOM.select('.decrement')
      .events('click')
      .map((ev) => -1),
    sources.DOM.select('.increment')
      .events('click')
      .map((ev) => +1),
  );
  const count$ = action$.fold((acc, x) => acc + x, 0);
  const vdom$ = count$.map((count) =>
    div([
      button('.decrement', 'Decrement'),
      button('.increment', 'Increment'),
      p('Counter: ' + count),
    ]),
  );
  return { DOM: vdom$ };
}

run(main, { DOM: makeDOMDriver('#main-container') });
```

Gyral:

```ts
// src/counter.ts
import { define, html } from '@gyral/core';

type Msg = { readonly _tag: 'Increment' } | { readonly _tag: 'Decrement' };

export const Counter = define<{ readonly count: number }, Msg>()('my-counter', {
  init: () => ({ count: 0 }),
  intent: {
    Increment: () => ({ _tag: 'Increment' }),
    Decrement: () => ({ _tag: 'Decrement' }),
  },
  update: {
    Increment: (s) => ({ count: s.count + 1 }),
    Decrement: (s) => ({ count: s.count - 1 }),
  },
  view: (s, i) => html`
    <button type="button" data-intent=${i.Decrement}>Decrement</button>
    <button type="button" data-intent=${i.Increment}>Increment</button>
    <p>Counter: <output>${s.count}</output></p>
  `,
});
```

The differences, line by line:

- `select('.decrement').events('click').map(ev => -1)` becomes a named intent. The view says
  which button means what with `data-intent=${i.Decrement}`; a typo is a compile error, not a
  silent no-op.
- `action$.fold(…)` becomes `update`: one reducer per message, exhaustive by type.
- `count$.map(count => div(…))` becomes `view`: the same idea, written as HTML.
- `run(main, { DOM: makeDOMDriver('#main-container') })` disappears. `<my-counter>` is a custom
  element; put it in any page, under any framework.

## Mapping Cycle.js concepts

| Cycle.js                                 | Gyral                                                                                    |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| `main(sources) → sinks`                  | `define()(tag, { init, intent, update, view })`                                          |
| `sources.DOM.select(…).events(…)`        | `data-intent` in the view, a parser in `intent`                                          |
| `fold` / reducer streams                 | `update`, one reducer per message                                                        |
| The DOM sink                             | `view`                                                                                   |
| Driver sinks (`HTTP`, `history`)         | [Commands](https://gyral.dev/docs/effects/) returned from `update`                                        |
| `HTTP.select('category')`                | `onSuccess` / `onFailure` mappers on the command                                         |
| `flatMapLatest`, `switchMap`, `debounce` | Concurrency lanes: `switch`, `exhaust`, `queue`, `merge`; `debounce()`                   |
| `isolate(Component)`                     | Shadow DOM, automatically                                                                |
| Props stream into a child                | [Props](https://gyral.dev/docs/components/#props) and `PropsChanged`                                      |
| Child sinks merged into the parent       | [Outputs](https://gyral.dev/docs/components/#child-components-and-outputs) with `outputs()` and `child()` |
| `makeCollection`                         | `each(items, key, row)` with child elements                                              |
| `@cycle/state`                           | Component state, plus [stores](https://gyral.dev/docs/stores/) for shared state                           |
| `@cycle/history`                         | [`@gyral/router`](https://gyral.dev/docs/routing/)                                                        |
| `@cycle/time`                            | `@gyral/time`, and `virtualTime()` in tests                                              |
| `@cycle/html`                            | [`@gyral/ssr`](https://gyral.dev/docs/server-rendering/)                                                  |
| `mockDOMSource`                          | `step()`, `run()` and fake drivers in [`@gyral/testing`](https://gyral.dev/docs/testing/)                 |

## The examples, ported

Gyral's acceptance suite is a port of the Cycle.js examples: hello world, the BMI
calculator, HTTP search, autocomplete, routing, nested folders, the isomorphic app and more.
Comparing an example in each is the fastest way to see the mapping in practice. See the
[examples](https://gyral.dev/examples/).

Gyral is a new implementation. Where ideas, APIs or example programs are adapted from Cycle.js,
the `NOTICE` file in Gyral's repository credits them under Cycle.js's MIT license.

---

# Design principles

> The beliefs behind Gyral, from "the platform is the framework" to "parse at boundaries", and what each one means for your code.

Source: https://gyral.dev/docs/principles/

These are the beliefs Gyral is built on. Each one explains a decision you'll meet in the API.
The full reasoning lives in the decision records in
[Gyral's repository](https://github.com/gyraljs/gyral/tree/v0.3.6/docs/design-docs).

## The platform is the framework

Custom elements, Shadow DOM, forms, `<dialog>`, popover, the Navigation and History APIs and
modern CSS come first. Gyral adds only what the platform lacks: a pure, testable application
loop.

That's why a component is a standard custom element, styles are plain CSS, links are `<a href>`
and forms are `<form>`. When the platform gains a feature, such as invoker commands or View
Transitions, Gyral uses it as an enhancement rather than building its own.

## Pure core, effects at the edges

`update` and `view` are pure functions. Side effects are described as data, as commands, and
carried out by drivers.

It's what makes a component testable without a browser, renderable on a server, and observable
in [devtools](https://gyral.dev/docs/devtools/): every change is a message, every effect a value.

## Parse at boundaries

Data is checked once, where it enters. Events become typed messages in the intent layer. Network
responses are decoded by the driver with a schema. Forms are validated by the same schema in the
browser and on the server. After the boundary, the model only ever sees valid data, so reducers
don't defend against impossible states.

## Thin layer, no walled garden

Every Gyral component works anywhere a custom element does: in a plain page, in another
framework, next to any other custom element, however it was built. There's no Gyral-only
component model to buy into, and nothing stops you from dropping down to the DOM, or to another
custom element, when you need to.

## No paradigm required

You don't need streams, a functional-effects library or decorators to use Gyral. The API is
plain TypeScript: functions, objects, unions and promises. Implementation choices stay
implementation details where they can: commands run on a small built-in runtime that no public
type exposes, so it can change without touching your code. A change that does reach your code
waits for a new minor version and comes with an upgrade guide.

## Semantic HTML and accessibility are correctness

A component that works with a mouse but not a keyboard is broken. Gyral's examples are judged on
element choice and on the accessibility tree, not only on behaviour, and its helpers exist to
keep accessible markup right on the server and in the browser: `invalid()`, `focus()`,
`?modal`, and form-state bindings that mean the same on both sides.

## Test in a real browser

Pure functions are tested with no DOM at all. Everything else is tested in a real browser, not a
simulated DOM: Gyral's own suite runs in Chromium with Vitest browser mode, including the
hydration of real server output against production builds.

## Enforce invariants, not intentions

Rules that matter become checks with error messages that explain the fix. In Gyral's own repo,
`@gyral/core` is checked to have no runtime dependencies, views can't bind event handlers (the
template compiler and the ESLint rules reject `@event` bindings), and every decision record is
indexed. This site follows the same rule: every TypeScript sample that names its file compiles
against the real packages, and every page passes accessibility checks in light and dark mode.

## Measure, then budget

Performance claims come from measurements. Bundle size is tracked per example with production
builds, and changes such as the devtools hook are measured before and after. Budgets follow
measurements, not the other way round: the [package guide](https://gyral.dev/docs/packages/#whats-inside)
publishes what the examples measure, not what they were meant to weigh.

---

# Coming from Lit

> Move a Lit component to Gyral's Model-View-Intent loop: explicit props, pure views, typed messages, keyed rows, drivers, stores and native hydration.

Source: https://gyral.dev/docs/coming-from-lit/

Gyral components are standard custom elements, so you can migrate one at a time alongside
your existing Lit elements. Gyral uses its own renderer. Its templates are not Lit
templates, and Lit directives do not work in them.

## A small component

In Lit, a click handler often mutates a reactive property and waits for the component's
update. In Gyral, intent names a message, a reducer returns state, and the view renders it:

```ts
// src/counter.ts
import { define, html } from '@gyral/core';

type State = { readonly count: number };
type Msg = { readonly _tag: 'Increment' };

export const Counter = define<State, Msg>()('my-counter', {
  init: () => ({ count: 0 }),
  intent: { Increment: true },
  update: { Increment: (s) => ({ count: s.count + 1 }) },
  view: (s, i) => html`
    <button type="button" data-intent=${i.Increment}>Increment</button>
    <output aria-live="polite">${s.count}</output>
  `,
});
```

There is no event closure in the template. `true` creates the tag-only message; a parser
extracts typed data for a message that needs it. Reducers and views are pure, while commands
describe work performed by drivers. `define` takes two calls: the first names the types, the
second the tag and the spec.

## Translate responsibilities

| Lit concept                         | Gyral equivalent                                                                                         |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `LitElement` subclass               | `define<State, Msg, Props>()(tag, spec)` returns a custom-element class                                  |
| Internal reactive fields / `@state` | Immutable model returned from `init` and `update`                                                        |
| Reactive properties / converters    | Declared `prop.string`, `number`, `boolean`, `json` or schema-validated `value`; read `ctx.props`        |
| Property-change lifecycle logic     | Optional `PropsChanged` reducer; keep external props out of state unless synchronization is needed       |
| `render()`                          | Pure `view(state, intents, ctx)` returning Gyral `html` or `svg`                                         |
| `@click=${handler}`                 | `data-intent=${i.Name}` plus a parser in `intent`                                                        |
| `repeat()`                          | `each(items, key, row, pick?)`, with pure rows and explicit changing inputs                              |
| `classMap` / `styleMap`             | Explicit attribute/CSS-variable bindings or an application helper; no matching built-in directive        |
| `live()` for controls               | Gyral's native live form bindings: `value`, `?checked`, `?selected` and textarea text                    |
| `ref()` / element work              | An explicit element hook, with a server half where markup is needed                                      |
| Reactive controller / observer      | A subscription driver for outside sources, or a lifecycle hook with `dispose` for element-owned work     |
| `@lit/task`                         | Commands, a driver, and loading/success/failure messages in the model                                    |
| `@lit/context`                      | Gyral stores listed in `stores` and read with `ctx.read(store)`, or props for parent-owned inputs        |
| `requestUpdate()`                   | Send a typed message or change a declared prop/store; no general manual update API                       |
| `updateComplete`                    | `await settled()` for the page's pending Gyral rendering                                                 |
| Lit SSR / hydration                 | `renderPage` or `renderToString` from `@gyral/ssr`, with Gyral seeds and native declarative shadow roots |

`settled()` waits for Gyral rendering and outputs, not pending network work or updates inside
a Lit element. Await those elements' own lifecycle promises separately. Props default to
kebab-case attribute names and do not automatically reflect properties back into attributes.
See [Components](https://gyral.dev/docs/components/) for validation, defaults and synchronization.

## Templates and directives

Import `html`, `svg`, `each`, `nothing` and hooks from Gyral. A template result from Lit is
not a Gyral child value. Render a Lit component by its custom-element tag instead:

```ts
// src/interop.ts
import { html } from '@gyral/core';

// Import the module defining vendor-chart separately before this template renders.
export const chart = (values: readonly number[]) =>
  html`<vendor-chart .values=${values}></vendor-chart>`;
```

Gyral's compiler checks its own template grammar. Avoid expressions in tag/attribute names,
event bindings, parser-repaired markup and promises in child holes. `each` rows cannot capture
changing state from the view; expose it through `pick`. Read [Views](https://gyral.dev/docs/views/) rather than
assuming every lit-html directive or binding rule transfers.

## Effects, styles and server rendering

Move fetches, timers and listeners out of the view. Return commands from `init`/reducers for
one-off work; use `subscriptions(state, props)` for sources that should keep running while
their inputs remain active. Gyral cancels their lanes on replacement or disconnect. The
[effects guide](https://gyral.dev/docs/effects/) shows expected failures and concurrency policies.

Move component styles into ``styles: css`...` `` or trusted CSS strings. Gyral shares native
constructable stylesheets; expose `part` names and custom properties as your public theme
contract. Existing third-party components keep their own style system.

On the server, register component definitions before rendering or use the component manifest.
Commands wait for the client; initial state, props and request-scoped stores are serialized
for hydration. Test edited controls and node identity under a production build. You can keep
Lit installed for your remaining Lit elements, but Gyral itself does not depend on it. See
[Server rendering](https://gyral.dev/docs/server-rendering/) and
[Using third-party components](https://gyral.dev/docs/third-party-components/).

For Lit's original contracts, see its official
[properties](https://lit.dev/docs/components/properties/),
[lifecycle](https://lit.dev/docs/components/lifecycle/) and
[controllers](https://lit.dev/docs/composition/controllers/) documentation.

---

# Gyral examples

> Gyral examples with their source, from a counter to a server-rendered app, plus gyral-shop.

Source: https://gyral.dev/examples/

## Basics

### Hello world

Two fields and a checkbox, and a greeting derived from state: input intents, reducers and ?checked, with valid and invalid input as plain values.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/hello-world
- Explained in: [Intent](https://gyral.dev/docs/intent/), [Views](https://gyral.dev/docs/views/#form-state)

`src/hello.ts`:

```ts
import { css, define, html } from '@gyral/core';

export interface State {
  readonly first: string;
  readonly last: string;
  readonly formal: boolean;
}

export type Msg =
  | { readonly _tag: 'First'; readonly value: string }
  | { readonly _tag: 'Last'; readonly value: string }
  | { readonly _tag: 'Formal'; readonly on: boolean };

/** Minimum last-name length before the formal greeting uses it. */
export const MIN_LAST = 3;

/**
 * Derived from state, never stored: the first name, or "LAST, First" when the formal greeting
 * is on and the last name is long enough. Raw, valid and invalid input are plain values in the
 * model, so no extra state is needed.
 */
export const greeting = ({ first, last, formal }: State): string =>
  formal && first.length > 0 && last.length >= MIN_LAST
    ? `${last.toUpperCase()}, ${first}`
    : first.trim();

export const Hello = define<State, Msg>()('gy-hello', {
  init: () => ({ first: '', last: '', formal: false }),
  intent: {
    // Text inputs fire on `input` and give `value`; checkboxes fire on `change` and give
    // `checked` (ADR 0001).
    First: ({ value }) => ({ _tag: 'First', value: value ?? '' }),
    Last: ({ value }) => ({ _tag: 'Last', value: value ?? '' }),
    Formal: ({ checked }) => ({ _tag: 'Formal', on: checked === true }),
  },
  update: {
    First: (s, m) => ({ ...s, first: m.value }),
    Last: (s, m) => ({ ...s, last: m.value }),
    Formal: (s, m) => ({ ...s, formal: m.on }),
  },
  view: (s, i) => html`
    <p>
      <label for="first">First name</label>
      <input id="first" type="text" autocomplete="given-name" data-intent=${i.First} />
    </p>
    <p>
      <label for="last">Last name</label>
      <input
        id="last"
        type="text"
        autocomplete="family-name"
        minlength=${MIN_LAST}
        aria-describedby="last-hint"
        data-intent=${i.Last}
      />
      <small id="last-hint">At least ${MIN_LAST} letters for the formal greeting.</small>
    </p>
    <p>
      <input id="formal" type="checkbox" ?checked=${s.formal} data-intent=${i.Formal} />
      <label for="formal">Formal greeting</label>
    </p>
    <hr />
    <output for="first last formal" aria-live="polite">Hello ${greeting(s)}</output>
  `,
  styles: css`…`,
});
```

## Effects, time and HTTP

### Seconds elapsed

A clock as a subscription: every() sends the time each second for as long as the component is on the page.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/seconds-elapsed
- Explained in: [Subscriptions](https://gyral.dev/docs/update/#subscriptions)

`src/seconds-elapsed.ts`:

```ts
import { css, define, html } from '@gyral/core';
import { every } from '@gyral/time';

export interface State {
  /** The wall-clock time of the first tick (ms). */
  readonly since: number | undefined;
  readonly seconds: number;
}

export type Msg = { readonly _tag: 'Tick'; readonly now: number };

/** ISO 8601 duration for `<time datetime>`, e.g. 75 → "PT75S". */
export const duration = (seconds: number): string => `PT${String(seconds)}S`;

// A clock subscription: `every` sends the time at once and then once a second, for as long as
// the component is in the page (ADR 0025). Seconds are counted from the first tick.
export const SecondsElapsed = define<State, Msg>()('gy-seconds-elapsed', {
  init: () => ({ since: undefined, seconds: 0 }),
  subscriptions: () => [every(1000, (now) => ({ _tag: 'Tick', now }))],
  update: {
    Tick: (s, m) => {
      const since = s.since ?? m.now;
      return { since, seconds: Math.round((m.now - since) / 1000) };
    },
  },
  view: (s) => html`
    <p>
      Seconds elapsed
      <output aria-live="off"><time datetime=${duration(s.seconds)}>${s.seconds}</time></output>
    </p>
  `,
  styles: css`…`,
});
```

### Random user

Randomness and HTTP as commands: a six-line random driver picks an id, then the user is fetched and decoded with a schema.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/http-random-user
- Explained in: [Effects and drivers](https://gyral.dev/docs/effects/)

`src/random-user.ts`:

```ts
import { css, define, html } from '@gyral/core';
import type { HttpError } from '@gyral/http';
import { randomInt } from './random.js';
import { fetchUser, USER_COUNT, type User } from './users.js';

export type State =
  | { readonly _tag: 'Idle' }
  | { readonly _tag: 'Loading'; readonly id: number }
  | { readonly _tag: 'Loaded'; readonly user: User }
  | { readonly _tag: 'Failed'; readonly message: string };

export type Msg =
  | { readonly _tag: 'GetRandom' }
  | { readonly _tag: 'Picked'; readonly id: number }
  | { readonly _tag: 'UserLoaded'; readonly user: User }
  | { readonly _tag: 'UserFailed'; readonly error: HttpError };

const describeError = (error: HttpError): string => {
  switch (error._tag) {
    case 'HttpStatusError':
      return `The server answered ${String(error.status)} ${error.statusText}.`;
    case 'HttpNetworkError':
      return 'Could not reach the server. Check your connection.';
    case 'HttpTimeoutError':
      return 'The server took too long to answer.';
    case 'HttpDecodeError':
      return 'The server sent a user we could not read.';
  }
};

export const RandomUser = define<State, Msg>()('gy-random-user', {
  init: () => ({ _tag: 'Idle' }),
  intent: {
    GetRandom: true,
  },
  update: {
    // Randomness is an effect: ask the random driver (src/random.ts), so tests can fix it.
    // Clicks while loading are ignored: any in-flight answer is "a random user".
    GetRandom: (s) =>
      s._tag === 'Loading'
        ? s
        : [s, [randomInt<Msg>(1, USER_COUNT, (id) => ({ _tag: 'Picked', id }))]],
    Picked: (_s, m) => [
      { _tag: 'Loading', id: m.id },
      [
        fetchUser<Msg>(
          m.id,
          (user) => ({ _tag: 'UserLoaded', user }),
          (error) => ({ _tag: 'UserFailed', error }),
        ),
      ],
    ],
    UserLoaded: (_s, m) => ({ _tag: 'Loaded', user: m.user }),
    UserFailed: (_s, m) => ({ _tag: 'Failed', message: describeError(m.error) }),
  },
  // Exposed to CSS as :state(loading) / :state(failed), on this host and for page styles.
  states: (s) => ({ loading: s._tag === 'Loading', failed: s._tag === 'Failed' }),
  view: (s, i) => html`
    <button type="button" data-intent=${i.GetRandom} aria-busy=${s._tag === 'Loading'}>
      Get random user
    </button>
    ${body(s)}
  `,
  styles: css`…`,
});

function body(s: State) {
  switch (s._tag) {
    case 'Idle':
      return html`<p role="status">Press the button to meet someone.</p>`;
    case 'Loading':
      return html`<p role="status">Loading user ${s.id}…</p>`;
    case 'Failed':
      return html`<p role="alert">${s.message}</p>`;
    case 'Loaded':
      return userCard(s.user);
  }
}

function userCard(user: User) {
  return html`<article aria-labelledby="user-name">
    <h2 id="user-name">${user.name}</h2>
    <dl>
      <dt>Email</dt>
      <dd><a href=${`mailto:${user.email}`}>${user.email}</a></dd>
      <dt>Phone</dt>
      <dd><a href=${`tel:${user.phone}`}>${user.phone}</a></dd>
      <dt>Website</dt>
      <dd><a href=${`https://${user.website}`} rel="noopener">${user.website}</a></dd>
      <dt>Company</dt>
      <dd>${user.company.name}</dd>
    </dl>
  </article>`;
}
```

### Search GitHub

Search as you type: debounce() and a switch lane cancel stale requests, and late answers for old queries are ignored.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/http-search-github
- Explained in: [Concurrency lanes](https://gyral.dev/docs/effects/#concurrency-lanes)

`src/search.ts`:

```ts
import { css, define, each, html, nothing } from '@gyral/core';
import type { HttpError } from '@gyral/http';
import { debounce } from '@gyral/time';
import { searchRepos, type Repo } from './github.js';

export type Results =
  | { readonly _tag: 'Idle' }
  | { readonly _tag: 'Searching' }
  | { readonly _tag: 'Found'; readonly repos: readonly Repo[] }
  | { readonly _tag: 'Failed'; readonly message: string };

export interface State {
  readonly query: string;
  readonly results: Results;
}

export type Msg =
  | { readonly _tag: 'Typed'; readonly query: string }
  | { readonly _tag: 'Search'; readonly query: string }
  | { readonly _tag: 'Found'; readonly query: string; readonly repos: readonly Repo[] }
  | { readonly _tag: 'SearchFailed'; readonly query: string; readonly error: HttpError };

export const DEBOUNCE_MS = 500;

const describeError = (error: HttpError): string =>
  error._tag === 'HttpStatusError' && error.status === 403
    ? 'GitHub rate limit reached. Try again in a minute.'
    : `Search failed (${error._tag}).`;

export const GithubSearch = define<State, Msg>()('gy-github-search', {
  init: () => ({ query: '', results: { _tag: 'Idle' } }),
  intent: {
    Typed: ({ value }) => ({ _tag: 'Typed', query: value ?? '' }),
    Search: ({ formData }) => {
      const query = formData?.get('q');
      return typeof query === 'string' ? { _tag: 'Search', query } : undefined;
    },
  },
  update: {
    Typed: (s, m) => [
      { ...s, query: m.query },
      // A 500 ms debounce: each keystroke cancels the pending timer.
      [debounce<Msg>(DEBOUNCE_MS, { _tag: 'Search', query: m.query })],
    ],
    Search: (s, m) => {
      const query = m.query.trim();
      if (query === '') return { query: m.query, results: { _tag: 'Idle' } };
      return [
        { query: m.query, results: { _tag: 'Searching' } },
        [
          searchRepos<Msg>(
            query,
            (repos) => ({ _tag: 'Found', query: m.query, repos }),
            (error) => ({ _tag: 'SearchFailed', query: m.query, error }),
          ),
        ],
      ];
    },
    Found: (s, m) =>
      m.query === s.query ? { ...s, results: { _tag: 'Found', repos: m.repos } } : s,
    SearchFailed: (s, m) =>
      m.query === s.query
        ? { ...s, results: { _tag: 'Failed', message: describeError(m.error) } }
        : s,
  },
  view: (s, i) => html`
    <search>
      <form data-intent=${i.Search}>
        <label for="q">Repository name</label>
        <input
          id="q"
          name="q"
          type="search"
          autocomplete="off"
          spellcheck="false"
          value=${s.query}
          data-intent=${i.Typed}
        />
      </form>
    </search>
    ${status(s.results)}
    ${
      s.results._tag === 'Found'
        ? html`<ol>
            ${each(s.results.repos, (r) => r.id, repoItem)}
          </ol>`
        : nothing
    }
  `,
  styles: css`…`,
});

function status(results: Results) {
  switch (results._tag) {
    case 'Idle':
      return html`<output for="q">Type to search.</output>`;
    case 'Searching':
      return html`<output for="q" aria-busy="true">Searching…</output>`;
    case 'Found':
      return html`<output for="q">${String(results.repos.length)} repositories</output>`;
    case 'Failed':
      return html`<p role="alert">${results.message}</p>`;
  }
}

function repoItem(repo: Repo) {
  return html`<li>
    <article>
      <h2><a href=${repo.html_url}>${repo.full_name}</a></h2>
      ${repo.description === null ? nothing : html`<p>${repo.description}</p>`}
      <p><data value=${repo.stargazers_count}>★ ${repo.stargazers_count.toLocaleString()}</data></p>
    </article>
  </li>`;
}
```

### Autocomplete

Wikipedia suggestions in a popover, with keyboard navigation through keydown intents and debounced requests.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/autocomplete-search
- Explained in: [Intent](https://gyral.dev/docs/intent/#trigger-events)

`src/autocomplete.ts`:

```ts
import { define, each, html, nothing, type Next } from '@gyral/core';
import { debounce, delay } from '@gyral/time';
import { popoverOpen } from './popover.js';
import { styles } from './styles.js';
import { suggest } from './wikipedia.js';

export const DEBOUNCE_MS = 300;

export interface State {
  readonly query: string;
  readonly suggestions: readonly string[];
  /** Index of the highlighted option, if any (aria-activedescendant). */
  readonly highlighted: number | undefined;
  readonly open: boolean;
  readonly status: 'idle' | 'loading' | 'error';
}

export type NavKey = 'ArrowDown' | 'ArrowUp' | 'Enter' | 'Escape';

export type Msg =
  | { readonly _tag: 'Typed'; readonly query: string }
  | { readonly _tag: 'Search'; readonly query: string }
  | { readonly _tag: 'Found'; readonly query: string; readonly titles: readonly string[] }
  | { readonly _tag: 'Failed'; readonly query: string }
  | { readonly _tag: 'Key'; readonly key: NavKey }
  | { readonly _tag: 'Pick'; readonly index: number }
  | { readonly _tag: 'Blurred' }
  | { readonly _tag: 'Dismiss' };

/** Long enough for a click on an option to land after the field loses focus. */
const BLUR_GRACE_MS = 150;

const NAV_KEYS: readonly string[] = ['ArrowDown', 'ArrowUp', 'Enter', 'Escape'];
const isNavKey = (key: string): key is NavKey => NAV_KEYS.includes(key);

const closed = (s: State): State => ({ ...s, open: false, highlighted: undefined });

/** Puts the chosen title in the field and closes the list (no new search). */
const select = (s: State, index: number): State => {
  const title = s.suggestions[index];
  return title === undefined ? s : { ...closed(s), query: title, suggestions: [] };
};

/** Arrow keys wrap around; the first press from "nothing highlighted" picks an end. */
export function move(s: State, delta: 1 | -1): State {
  const n = s.suggestions.length;
  if (n === 0) return s;
  const from = s.highlighted ?? (delta === 1 ? -1 : 0);
  return { ...s, open: true, highlighted: (from + delta + n) % n };
}

function onKey(s: State, key: NavKey): State {
  switch (key) {
    case 'ArrowDown':
      return move(s, 1);
    case 'ArrowUp':
      return move(s, -1);
    case 'Enter':
      return s.open && s.highlighted !== undefined ? select(s, s.highlighted) : s;
    case 'Escape':
      return closed(s);
  }
}

function onTyped(s: State, query: string): Next<State, Msg> {
  const next: State = { ...closed(s), query };
  if (query.trim() === '') return { ...next, suggestions: [], status: 'idle' };
  // Each keystroke restarts the timer: one search once typing pauses.
  return [next, [debounce<Msg>(DEBOUNCE_MS, { _tag: 'Search', query }, 'autocomplete')]];
}

function statusText(s: State): string {
  if (s.status === 'loading') return 'Searching…';
  if (s.status === 'error') return 'Suggestions are unavailable right now.';
  if (!s.open) return '';
  const n = s.suggestions.length;
  return `${String(n)} suggestion${n === 1 ? '' : 's'}. Use the up and down arrows to choose.`;
}

/** One suggestion; pure: its index, highlight and intent come through `pick`. */
const option = (title: string, [index, highlighted, pick]: readonly [number, boolean, string]) =>
  html`<li
    id="option-${String(index)}"
    role="option"
    aria-selected=${highlighted ? 'true' : 'false'}
    data-index=${index}
    data-intent=${pick}
  >
    ${title}
  </li>`;

export const Autocomplete = define<State, Msg>()('gy-autocomplete', {
  init: () => ({ query: '', suggestions: [], highlighted: undefined, open: false, status: 'idle' }),
  intent: {
    Typed: ({ value }) => ({ _tag: 'Typed', query: value ?? '' }),
    Key: ({ key, event }) => {
      if (key === undefined || !isNavKey(key) || (event as KeyboardEvent).isComposing) return;
      if (key === 'ArrowDown' || key === 'ArrowUp') event.preventDefault(); // keep the caret
      return { _tag: 'Key', key };
    },
    Blurred: true,
    Pick: ({ target }) => {
      const index = Number(target.getAttribute('data-index'));
      return Number.isInteger(index) ? { _tag: 'Pick', index } : undefined;
    },
  },
  update: {
    Typed: (s, m) => onTyped(s, m.query),
    Search: (s, m) =>
      m.query !== s.query
        ? s
        : [
            { ...s, status: 'loading' },
            [
              suggest<Msg>(
                m.query,
                (titles) => ({ _tag: 'Found', query: m.query, titles }),
                () => ({ _tag: 'Failed', query: m.query }),
              ),
            ],
          ],
    // Answers for an older query are ignored (the switch lane usually cancels them anyway).
    Found: (s, m) =>
      m.query !== s.query
        ? s
        : {
            ...s,
            suggestions: m.titles,
            open: m.titles.length > 0,
            highlighted: undefined,
            status: 'idle',
          },
    Failed: (s, m) => (m.query !== s.query ? s : { ...closed(s), status: 'error' }),
    Key: (s, m) => onKey(s, m.key),
    Pick: (s, m) => select(s, m.index),
    // Close when focus leaves the combobox, after a grace period so option clicks still land.
    Blurred: (s) => (s.open ? [s, [delay<Msg>(BLUR_GRACE_MS, { _tag: 'Dismiss' })]] : s),
    Dismiss: (s) => closed(s),
  },
  view: (s, i) => html`
    <div class="field">
      <label for="query">Wikipedia article</label>
      <span class="combo" data-intent=${i.Blurred} data-intent-on="focusout">
        <span class="keys" data-intent=${i.Key} data-intent-on="keydown">
          <input
            id="query"
            type="text"
            role="combobox"
            autocomplete="off"
            spellcheck="false"
            aria-autocomplete="list"
            aria-controls="suggestions"
            aria-expanded=${s.open ? 'true' : 'false'}
            aria-activedescendant=${
              s.highlighted === undefined ? nothing : `option-${String(s.highlighted)}`
            }
            value=${s.query}
            data-intent=${i.Typed}
          />
        </span>
        <ul
          id="suggestions"
          role="listbox"
          aria-label="Suggestions"
          ?hidden=${!s.open}
          ${popoverOpen(s.open)}
        >
          ${each(
            s.suggestions,
            (title) => title,
            option,
            (title) => {
              const index = s.suggestions.indexOf(title);
              return [index, index === s.highlighted, i.Pick] as const;
            },
          )}
        </ul>
      </span>
    </div>
    <p class="status" role="status">${statusText(s)}</p>
    <div class="field">
      <label for="other">Some field</label>
      <input id="other" type="text" />
    </div>
  `,
  styles,
});
```

### Custom driver

A canvas chart as a driver: one command draws, another streams the bars the user clicks.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/custom-driver
- Explained in: [Writing a driver](https://gyral.dev/docs/effects/#writing-a-driver)

`src/chart-driver.ts`:

```ts
// A custom driver (ADR 0006): a plain object that owns an imperative resource, here a
// <canvas> outside any component, and talks to components only through commands.
// It draws a bar chart with the 2D canvas API, so the example needs no charting dependency.
import { command, type Command, type Driver } from '@gyral/core';

export interface ChartData {
  readonly label: string;
  readonly values: readonly number[];
}

export type ChartInput =
  | { readonly _tag: 'Draw'; readonly data: ChartData }
  /** Streams the index of every bar the user clicks, until aborted. */
  | { readonly _tag: 'Clicks' };

export type ChartDriver = Driver<ChartInput, number | undefined>;

export interface ChartOptions {
  /** Driver name used for substitution (`el.drivers`). Default `'chart'`. */
  readonly name?: string;
  /** Where to look the canvas up. Default: `document`, resolved when a command runs. */
  readonly root?: () => ParentNode;
}

const PAD = 24;

/** Horizontal geometry of the bars, shared by drawing and hit-testing. */
export function layout(width: number, count: number): { readonly barWidth: number } {
  return { barWidth: (width - 2 * PAD) / Math.max(count, 1) };
}

/** The bar under canvas x-coordinate `x`, if any. */
export function barAt(x: number, width: number, count: number): number | undefined {
  const index = Math.floor((x - PAD) / layout(width, count).barWidth);
  return x >= PAD && index >= 0 && index < count ? index : undefined;
}

function draw(canvas: HTMLCanvasElement, data: ChartData): void {
  const ctx = canvas.getContext('2d');
  if (ctx === null) return;
  const { width, height } = canvas;
  const style = getComputedStyle(canvas);
  const bar = style.getPropertyValue('--chart-bar').trim() || 'steelblue';
  const ink = style.getPropertyValue('--chart-ink').trim() || style.color;
  const { barWidth } = layout(width, data.values.length);
  const max = Math.max(1, ...data.values);
  const plot = height - 2 * PAD;

  ctx.clearRect(0, 0, width, height);
  ctx.font = '12px system-ui, sans-serif';
  ctx.fillStyle = ink;
  ctx.fillText(data.label, PAD, PAD - 8);
  data.values.forEach((value, i) => {
    const h = (value / max) * plot;
    const x = PAD + i * barWidth;
    ctx.fillStyle = bar;
    ctx.fillRect(x + 2, PAD + plot - h, Math.max(barWidth - 4, 1), h);
    ctx.fillStyle = ink;
    ctx.fillText(String(i), x + barWidth / 2 - 3, height - 6);
  });
}

/** Creates a chart driver for the canvas matching `selector`. Nothing runs at import time. */
export function makeChartDriver(selector: string, options: ChartOptions = {}): ChartDriver {
  let last: ChartData = { label: '', values: [] };
  const find = (): HTMLCanvasElement => {
    const el = (options.root?.() ?? document).querySelector(selector);
    if (!(el instanceof HTMLCanvasElement)) throw new Error(`No canvas '${selector}' found`);
    return el;
  };

  return {
    name: options.name ?? 'chart',
    run: (input, { signal, emit }) => {
      const canvas = find();
      if (input._tag === 'Draw') {
        last = input.data;
        draw(canvas, input.data);
        return undefined;
      }
      // Streaming source (DriverContext.emit): one message per clicked bar.
      return new Promise<never>((_resolve, reject) => {
        const onClick = (event: MouseEvent): void => {
          const rect = canvas.getBoundingClientRect();
          const x = (event.clientX - rect.left) * (canvas.width / rect.width);
          const index = barAt(x, canvas.width, last.values.length);
          if (index !== undefined) emit(index);
        };
        const stop = (): void => {
          canvas.removeEventListener('click', onClick);
          reject(new DOMException('Aborted', 'AbortError'));
        };
        if (signal.aborted) {
          stop();
          return;
        }
        canvas.addEventListener('click', onClick);
        signal.addEventListener('abort', stop, { once: true });
      });
    },
  };
}

/** The page's chart: `<canvas id="clicks-chart">`. */
export const chart: ChartDriver = makeChartDriver('#clicks-chart');

/** Redraws the chart. Only the latest drawing matters, so the lane switches. */
export function drawChart(data: ChartData): Command<never> {
  return command(chart, { _tag: 'Draw', data }, { key: 'chart:draw', concurrency: 'switch' });
}

/** Streams clicked bar indexes as messages until the component disconnects. */
export function chartClicks<M>(toMsg: (bar: number) => M | undefined): Command<M> {
  return command(
    chart,
    { _tag: 'Clicks' },
    {
      onSuccess: (bar) => (bar === undefined ? undefined : toMsg(bar)),
      key: 'chart:clicks',
      concurrency: 'switch',
    },
  );
}
```

### Workload lab

Heavier work under the same rules: a module worker behind a driver that a subscription starts and cancels, timed steps, a booking form with retries, and a canvas grid with pointer capture.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/workload-lab
- Explained in: [Subscriptions](https://gyral.dev/docs/update/#subscriptions), [Writing a driver](https://gyral.dev/docs/effects/#writing-a-driver)

`src/solver.ts`:

```ts
import { command, define, html } from '@gyral/core';
import { solver } from './solver-driver.js';
import { controls } from './styles.js';

interface State {
  readonly job: number;
  readonly status: 'idle' | 'running' | 'done' | 'failed';
  readonly report: string;
}
type Msg =
  | { readonly _tag: 'Generate' }
  | { readonly _tag: 'Cancel' }
  | { readonly _tag: 'Solved'; readonly job: number; readonly checksum: number }
  | { readonly _tag: 'Failed'; readonly job: number; readonly error: string };
export const Solver = define<State, Msg>()('gy-solver', {
  init: () => ({ job: 0, status: 'idle', report: 'Worker idle' }),
  intent: { Generate: true, Cancel: true },
  subscriptions: (s) =>
    s.status === 'running'
      ? [
          command(
            solver,
            { id: s.job, iterations: 300_000 },
            {
              key: 'solver:job',
              concurrency: 'switch',
              onSuccess: (result) => ({
                _tag: 'Solved',
                job: result.id,
                checksum: result.checksum,
              }),
              onFailure: (error) => ({ _tag: 'Failed', job: s.job, error }),
            },
          ),
        ]
      : [],
  update: {
    Generate: (s) => ({ ...s, job: s.job + 1, status: 'running', report: 'Worker running' }),
    Cancel: (s) => ({ ...s, status: 'idle', report: 'Worker cancelled' }),
    Solved: (s, m) =>
      s.status === 'running' && m.job === s.job
        ? { ...s, status: 'done', report: `Worker result: ${String(m.checksum)}` }
        : s,
    Failed: (s, m) =>
      s.status === 'running' && m.job === s.job ? { ...s, status: 'failed', report: m.error } : s,
  },
  view: (s, i) => html`
    <div class="actions">
      <button type="button" data-intent=${i.Generate}>Generate in worker</button>
      <button type="button" data-intent=${i.Cancel} ?disabled=${s.status !== 'running'}>
        Cancel worker
      </button>
    </div>
    <output aria-live="polite">${s.report}</output>
  `,
  styles: controls,
});
```

## Components and shared state

### Nested BMI

Two instances of one slider component. Props go down, outputs come up, and the parent owns the values.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/bmi-nested
- Explained in: [Child components](https://gyral.dev/docs/components/#child-components-and-outputs)

`src/bmi-nested.ts`:

```ts
import { child, css, define, html } from '@gyral/core';
import { LabeledSlider } from './labeled-slider.js';

export interface State {
  readonly weight: number;
  readonly height: number;
}

export type Msg =
  | { readonly _tag: 'Weight'; readonly kg: number }
  | { readonly _tag: 'Height'; readonly cm: number };

export const bmiOf = ({ weight, height }: State): number =>
  Math.round(weight / (height / 100) ** 2);

/**
 * The parent owns both values and derives the BMI. Each slider is the same child component;
 * the two `data-intent` names tell their outputs apart, with no extra scoping step.
 */
export const BmiNested = define<State, Msg>()('gy-bmi-nested', {
  init: () => ({ weight: 70, height: 170 }),
  intent: {
    Weight: child(LabeledSlider, (out) => ({ _tag: 'Weight', kg: out.value })),
    Height: child(LabeledSlider, (out) => ({ _tag: 'Height', cm: out.value })),
  },
  update: {
    Weight: (s, m) => ({ ...s, weight: m.kg }),
    Height: (s, m) => ({ ...s, height: m.cm }),
  },
  view: (s, i) => html`
    <gy-labeled-slider
      id="weight"
      label="Weight"
      unit="kg"
      min="40"
      max="140"
      .value=${s.weight}
      data-intent=${i.Weight}
    ></gy-labeled-slider>
    <gy-labeled-slider
      id="height"
      label="Height"
      unit="cm"
      min="140"
      max="210"
      .value=${s.height}
      data-intent=${i.Height}
    ></gy-labeled-slider>
    <h2>BMI is <output>${bmiOf(s)}</output></h2>
  `,
  styles: css`…`,
});
```

### Nested folders

A folder that contains folders: a recursive component through child(() => Folder), each level owning its own children.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/nested-folders
- Explained in: [Child components](https://gyral.dev/docs/components/#child-components-and-outputs)

`src/folder.ts`:

```ts
import {
  child,
  css,
  define,
  each,
  html,
  nothing,
  outputs,
  prop,
  type GyralElementClass,
} from '@gyral/core';

export interface State {
  /** Ids of this folder's direct children. Each child owns its own subtree. */
  readonly children: readonly string[];
  readonly next: number;
}

export interface Props {
  readonly folderId: string;
  readonly removable: boolean;
}

export type FolderOutput = { readonly _tag: 'Removed' };

/** Typed `emit` for this component's outputs. */
const emit = outputs<FolderOutput>();

export type Msg =
  | { readonly _tag: 'Add' }
  | { readonly _tag: 'Remove' }
  | { readonly _tag: 'Child'; readonly id: string; readonly out: FolderOutput };

/** Stable pastel hue per id, so a folder keeps its color across renders. */
export function hueOf(id: string): number {
  let hue = 7;
  for (let n = 0; n < id.length; n += 1) hue = (hue * 31 + id.charCodeAt(n)) % 360;
  return hue;
}

/**
 * A folder renders folders of its own kind: recursion through the custom-element tag.
 * Each folder owns the list of its direct children (no single state tree with lenses per
 * level); a child removes itself by emitting `Removed` up one level.
 * Ids are paths (`1.2.1`), so making a new one is pure.
 */
/** One child folder; its intent name comes through `pick`, so the row stays pure. */
const subfolder = (id: string, intent: string) =>
  html`<li>
    <gy-folder folder-id=${id} removable data-intent=${intent}></gy-folder>
  </li>`;

// The explicit type lets `child(() => Folder, …)` refer to the constant being defined.
export const Folder: GyralElementClass<State, Msg, Props, FolderOutput> = define<
  State,
  Msg,
  Props,
  FolderOutput
>()('gy-folder', {
  props: {
    folderId: prop.string({ required: true }), // attribute "folder-id"
    // A boolean attribute: absent on the root folder means "not removable" (found by ui:check).
    removable: prop.boolean(),
  },
  init: () => ({ children: [], next: 1 }),
  intent: {
    Add: true,
    Remove: true,
    // Lazy source: `Folder` is still being defined here (recursion), so pass a function.
    Child: child(
      () => Folder,
      (out, el) => ({ _tag: 'Child', id: el.folderId, out }),
    ),
  },
  update: {
    Add: (s, _m, { props }) => ({
      children: [...s.children, `${props.folderId}.${String(s.next)}`],
      next: s.next + 1,
    }),
    Remove: (s) => [s, [emit({ _tag: 'Removed' })]],
    // FolderOutput has one variant (Removed); switch on m.out._tag when it grows.
    Child: (s, m) => ({ ...s, children: s.children.filter((id) => id !== m.id) }),
  },
  view: (s, i, { props }) => html`
    <details open style="--hue: ${hueOf(props.folderId)}">
      <summary>Folder ${props.folderId}</summary>
      <menu>
        <li><button type="button" data-intent=${i.Add}>Add folder</button></li>
        ${
          props.removable
            ? html`<li><button type="button" data-intent=${i.Remove}>Remove me</button></li>`
            : nothing
        }
      </menu>
      ${
        s.children.length === 0
          ? nothing
          : html`<ul>
              ${each(
                s.children,
                (id) => id,
                subfolder,
                () => i.Child,
              )}
            </ul>`
      }
    </details>
  `,
  styles: css`…`,
});
```

### Shared cart

A header badge, a product list and a cart panel, far apart on the page, sharing one store.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/shared-cart
- Explained in: [Shared state](https://gyral.dev/docs/stores/)

`src/cart.ts`:

```ts
import { defineStore } from '@gyral/core';

export interface Product {
  readonly sku: string;
  readonly name: string;
  readonly priceCents: number;
}

export interface Line extends Product {
  readonly qty: number;
}

export interface Cart {
  readonly lines: readonly Line[];
}

export type CartMsg =
  | { readonly _tag: 'Add'; readonly product: Product }
  | { readonly _tag: 'Remove'; readonly sku: string }
  | { readonly _tag: 'Clear' };

export const count = (cart: Cart): number => cart.lines.reduce((n, l) => n + l.qty, 0);
export const totalCents = (cart: Cart): number =>
  cart.lines.reduce((sum, l) => sum + l.priceCents * l.qty, 0);
export const money = (cents: number): string =>
  new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(cents / 100);

/** The shared cart: MVI without a view (ADR 0013). Components read it and send it messages. */
export const cart = defineStore<Cart, CartMsg>('cart', {
  init: () => ({ lines: [] }),
  update: {
    Add: (s, { product }) =>
      s.lines.some((l) => l.sku === product.sku)
        ? { lines: s.lines.map((l) => (l.sku === product.sku ? { ...l, qty: l.qty + 1 } : l)) }
        : { lines: [...s.lines, { ...product, qty: 1 }] },
    Remove: (s, { sku }) => ({ lines: s.lines.filter((l) => l.sku !== sku) }),
    Clear: () => ({ lines: [] }),
  },
});
```

## Routing, forms and the platform

### Routing

A typed route table, listen() streaming every location, setHead(), and a View Transition between pages.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/routing-view
- Explained in: [Routing](https://gyral.dev/docs/routing/)

`src/app.ts`:

```ts
import { command, css, define, html, nothing, type Head } from '@gyral/core';
import {
  listen,
  router,
  routes,
  setHead,
  type RouteLocation,
  type RouteMatch,
} from '@gyral/router';

/** The route table: pure, typed, and reusable on a server (ADR 0009). */
export const app = routes({ home: '/', about: '/about', contacts: '/contacts' });

type Route = RouteMatch<typeof app.table>;
type Name = Route['name'];

export interface State {
  /** `undefined` until the router delivers the current location. */
  readonly location: RouteLocation | undefined;
  readonly route: Route | undefined;
}

export type Msg =
  { readonly _tag: 'Routed'; readonly location: RouteLocation } | { readonly _tag: 'Back' };

interface Page {
  readonly title: string;
  readonly nav: string;
  readonly body: string;
}

const pages: Readonly<Record<Name, Page>> = {
  home: {
    nav: 'Home',
    title: 'Welcome to the routing example',
    body: 'Links below are plain anchors. The router captures same-origin clicks, updates history, and streams every location to this component as a message.',
  },
  about: {
    nav: 'About',
    title: 'About me',
    body: 'The current route is model state, derived from the location by matching it against a typed route table. The view is a pure function of that state.',
  },
  contacts: {
    nav: 'Contacts',
    title: 'Contact me',
    body: 'Try the browser back button, or the Back button below: both arrive here as the same Routed message.',
  },
};

const order: readonly Name[] = ['home', 'about', 'contacts'];

/**
 * The document head for a route: one pure function, so a server could reuse it (ADR 0019).
 * An unknown route is `noindex`; a known one names its canonical URL.
 */
export const pageHead = (route: Route | undefined, origin: string): Head => ({
  title: `${route === undefined ? 'Page not found' : pages[route.name].nav} — Gyral routing`,
  ...(route === undefined
    ? { robots: 'noindex' }
    : { canonical: new URL(route.path, origin).href }),
});

export const RoutingView = define<State, Msg>()('gy-routing-view', {
  init: () => ({ location: undefined, route: undefined }),
  // One subscription: the current location now, then every change (ADR 0009, ADR 0025).
  subscriptions: () => [listen((location) => ({ _tag: 'Routed', location }))],
  intent: {
    Back: true,
  },
  update: {
    Routed: (_s, { location }) => {
      const route = app.match(location.href);
      // A client-only app: the page's own origin is the canonical one.
      return [{ location, route }, [setHead(pageHead(route, new URL(location.href).origin))]];
    },
    // History back is a router input (the "History back and forward" recipe).
    Back: (s) => [s, [command(router, { _tag: 'Traverse', delta: -1 })]],
  },
  // Cross-fade between pages (an enhancement: skipped without support or with reduced motion).
  // The first location is not a page change, so it renders directly.
  viewTransition: (prev, next) =>
    prev.location !== undefined && prev.route?.name !== next.route?.name,
  view: (s, i) => {
    const page = s.route === undefined ? undefined : pages[s.route.name];
    return html`
      <header>
        <nav aria-label="Main">
          <ul>
            ${order.map(
              (name) =>
                html`<li>
                  <a
                    href=${app.href(name, {})}
                    aria-current=${s.route?.name === name ? 'page' : nothing}
                    >${pages[name].nav}</a
                  >
                </li>`,
            )}
          </ul>
        </nav>
      </header>
      <main>
        ${
          s.location === undefined
            ? nothing
            : page === undefined
              ? html`<h1>404 — page not found</h1>
                  <p>No route matches <code>${s.location.pathname}</code>.</p>`
              : html`<h1>${page.title}</h1>
                  <p>${page.body}</p>`
        }
        <p><button type="button" data-intent=${i.Back}>Back</button></p>
        <details>
          <summary>Location object</summary>
          <pre><code>${JSON.stringify(s.location, null, 2)}</code></pre>
        </details>
      </main>
    `;
  },
  styles: css`…`,
});
```

### Isomorphic app

Rendered on the server with Declarative Shadow DOM, hydrated in place, with one route prerendered and one rendered per request.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/isomorphic
- Explained in: [Server rendering](https://gyral.dev/docs/server-rendering/)

`src/app.ts`:

```ts
import { css, define, html, prop } from '@gyral/core';
import { listen, setHead, type RouteLocation } from '@gyral/router';
import { pageHead, site, titles } from './routes.js';

export interface Props {
  /** The request path, set by the server. On the client the router takes over. */
  readonly path?: string;
}

export interface State {
  readonly path: string;
}

export type Msg = { readonly _tag: 'Routed'; readonly location: RouteLocation };

const menu = (path: string) => html`
  <nav aria-label="Site">
    <ul>
      ${(['home', 'about'] as const).map((name) => {
        const href = site.href(name, {});
        return html`<li>
          <a href=${href} aria-current=${href === path ? 'page' : 'false'}>${titles[name]}</a>
        </li>`;
      })}
    </ul>
  </nav>
`;

const content = (path: string) => {
  switch (site.match(path)?.name) {
    case 'home':
      return html`<h1>${titles.home}</h1>
        <p>Welcome to our spectacular web page with nothing special here.</p>`;
    case 'about':
      return html`<h1>${titles.about}</h1>
        <p>This is the page where we describe ourselves.</p>
        <gy-iso-contact></gy-iso-contact>`;
    case undefined:
      return html`<h1>Page not found</h1>
        <p>Unknown page <code>${path}</code>.</p>`;
  }
};

export const App = define<State, Msg, Props>()('gy-iso-app', {
  props: { path: prop.string() },
  // Same on server and client.
  init: (props) => ({ path: props.path ?? '/' }),
  // The server never runs commands; after hydration the client subscribes to the location,
  // which streams the current one and every navigation (ADR 0012, ADR 0025).
  subscriptions: () => [listen((location) => ({ _tag: 'Routed', location }))],
  update: {
    // pageHead() also renders the server's head: one source for both (ADR 0019). The first
    // Routed after hydration finds the server's head already matching and writes nothing.
    Routed: (_s, m) => [{ path: m.location.pathname }, [setHead(pageHead(m.location.pathname))]],
  },
  view: (s) => html`
    <header>${menu(s.path)}</header>
    <main>${content(s.path)}</main>
  `,
  styles: css`…`,
});
```

### Register

A sign-up form that validates the same way with and without JavaScript, including a server-only check.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/register
- Explained in: [Forms](https://gyral.dev/docs/forms/#the-server-half)

`src/register.ts`:

```ts
import '../../shared/devtools.js'; // ?devtools opens the panel (dev only)
import {
  css,
  define,
  fieldErrors,
  form,
  html,
  invalid,
  prop,
  type FormFields,
  type IntentRejected,
} from '@gyral/core';
import { submitForm } from '@gyral/http';
import { RegisterForm } from './schema.js';

export interface State {
  /** Text to re-fill after a rejection. Never passwords: state is serialized into the page. */
  readonly values: FormFields;
  readonly errors: Readonly<Record<string, readonly string[]>>;
  readonly welcome: string | undefined;
  /** The name being registered while the JS-path request is in flight. */
  readonly pending: string | undefined;
}

export type Msg =
  // Passed client-side validation; `form` is the raw submission, posted to the server as is.
  | { readonly _tag: 'Register'; readonly name: string; readonly form: FormData }
  | { readonly _tag: 'Registered' }
  | { readonly _tag: 'Failed' };

export interface Props {
  /** Set by the server after a successful no-JS submission (Post/Redirect/Get). */
  readonly welcome: string | undefined;
}

const text = (values: FormFields, key: string): string => {
  const value = values[key];
  return typeof value === 'string' ? value : '';
};

// Client-side (form()) and server-side (submitForm → 422) rejections arrive the same way.
const rejected = (s: State, m: IntentRejected): State => ({
  ...s,
  values: m.values ?? s.values, // secret fields are never in m.values
  errors: fieldErrors(m.issues),
  pending: undefined,
});

interface FieldSpec {
  readonly name: string;
  readonly label: string;
  readonly type: string;
  readonly autocomplete: string;
  readonly minlength?: number;
}

const FIELDS: readonly FieldSpec[] = [
  { name: 'name', label: 'Name', type: 'text', autocomplete: 'username' },
  { name: 'email', label: 'Email', type: 'email', autocomplete: 'email' },
  {
    name: 'password',
    label: 'Password',
    type: 'password',
    autocomplete: 'new-password',
    minlength: 8,
  },
  { name: 'confirm', label: 'Repeat password', type: 'password', autocomplete: 'new-password' },
];

// invalid() writes aria-invalid on the server too (its server half), so no-JS users still get
// the error announced (ADR 0008 server half, view/02-bindings.md "Element hooks").
const fieldView = (s: State, f: FieldSpec) => {
  const errors = s.errors[f.name];
  return html`<p>
    <label for=${f.name}>${f.label}</label>
    <input
      id=${f.name}
      name=${f.name}
      type=${f.type}
      autocomplete=${f.autocomplete}
      minlength=${f.minlength}
      required
      value=${text(s.values, f.name)}
      aria-describedby=${`${f.name}-error`}
      ${invalid(errors)}
    />
    <span id=${`${f.name}-error`} class="error">${errors?.join(' ') ?? ''}</span>
  </p>`;
};

export const Register = define<State, Msg, Props>()('gy-register', {
  props: { welcome: prop.string() },
  init: (props) => ({ values: {}, errors: {}, welcome: props.welcome, pending: undefined }),
  intent: {
    Register: form(RegisterForm, (data, raw) => ({ _tag: 'Register', name: data.name, form: raw })),
  },
  update: {
    // Valid in the browser; the server still decides (it also stores the account).
    Register: (s, m) => [
      { ...s, errors: {}, pending: m.name },
      [
        submitForm('/', m.form, {
          onSuccess: () => ({ _tag: 'Registered' }),
          onFailure: () => ({ _tag: 'Failed' }),
        }),
      ],
    ],
    Registered: (s) => ({ values: {}, errors: {}, welcome: s.pending, pending: undefined }),
    Failed: (s) => ({
      ...s,
      errors: { '': ['Something went wrong. Please try again.'] },
      pending: undefined,
    }),
    IntentRejected: rejected,
  },
  view: (s, i) =>
    s.welcome === undefined
      ? html`<form data-intent=${i.Register} action="/" method="post">
          ${FIELDS.map((f) => fieldView(s, f))}
          <p class="error" role="alert">${s.errors['']?.join(' ') ?? ''}</p>
          <button ?disabled=${s.pending !== undefined}>Create account</button>
        </form>`
      : html`<p role="status">Welcome, <strong>${s.welcome}</strong>! Your account is ready.</p>`,
  styles: css`…`,
});
```

### Invoker commands

Buttons that send command and commandfor invokers to a list, with a fallback where browsers lack them.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/invoker-commands
- Explained in: [Intent](https://gyral.dev/docs/intent/#invoker-commands)

`src/shopping-list.ts`:

```ts
import { css, define, each, html } from '@gyral/core';

export interface State {
  readonly items: readonly string[];
  readonly next: number;
}

export type ListCommand = '--add' | '--clear';

export type Msg = { readonly _tag: 'Command'; readonly command: ListCommand };

const isListCommand = (c: string | undefined): c is ListCommand => c === '--add' || c === '--clear';

/**
 * Buttons send invoker commands to the list (gyral-czi.6): its `command` intent parses which
 * one. `show-modal` is a built-in command the browser handles with no JS at all.
 */
export const ShoppingList = define<State, Msg>()('gy-shopping-list', {
  init: () => ({ items: ['Milk', 'Bread'], next: 1 }),
  intent: {
    Command: ({ command }) =>
      isListCommand(command?.command) ? { _tag: 'Command', command: command.command } : undefined,
  },
  update: {
    Command: (s, m) => {
      switch (m.command) {
        case '--add':
          return { items: [...s.items, `Item ${String(s.next)}`], next: s.next + 1 };
        case '--clear':
          return { ...s, items: [] };
      }
    },
  },
  view: (s, i) => html`
    <menu>
      <li><button type="button" commandfor="list" command="--add">Add item</button></li>
      <li><button type="button" commandfor="list" command="--clear">Clear</button></li>
      <li><button type="button" commandfor="help" command="show-modal">Help</button></li>
    </menu>
    <section id="list" data-intent=${i.Command} data-intent-on="command" aria-labelledby="list-h">
      <h2 id="list-h">List (${s.items.length})</h2>
      <ul>
        ${each(
          s.items,
          (item) => item,
          (item) => html`<li>${item}</li>`,
        )}
      </ul>
    </section>
    <dialog id="help">
      <p>Each button sends a command to the element named by its <code>commandfor</code>.</p>
      <form method="dialog"><button>Close</button></form>
    </dialog>
  `,
  styles: css`…`,
});
```

### Animation

The model counts runs and CSS does the motion: no per-frame state, each run restarted with keyed().

- Source: https://github.com/gyraljs/gyral/tree/main/examples/animation
- Explained in: [Views](https://gyral.dev/docs/views/#lists)

`src/animation.ts`:

```ts
import { css, define, html, keyed } from '@gyral/core';

// The model only counts runs; the motion is a CSS animation the browser runs on its own
// (no per-frame state, no JS timer, no coordinates tweened in JS).

/** A keyframe: time (0..1), position in units of the travel distance, easing to the next stop. */
export interface Stop {
  readonly at: number;
  readonly x: number;
  readonly y: number;
  readonly ease: string;
}

/** The three legs of the original, in milliseconds: right, down, then a curve back home. */
const LEGS = [500, 500, 1600] as const;
export const DURATION_MS = LEGS[0] + LEGS[1] + LEGS[2];

const EASE_IN_CUBIC = 'cubic-bezier(0.32, 0, 0.67, 0)'; // tween.power3.easeIn
const EASE_OUT_CUBIC = 'cubic-bezier(0.33, 1, 0.68, 1)'; // tween.power3.easeOut
const ARC_STEPS = 12;

/** Inverse of easeInOutCubic: the fraction of the arc's time at which it reaches `progress`. */
const arcTime = (progress: number): number =>
  progress < 0.5 ? Math.cbrt(progress / 4) : 1 - Math.cbrt(2 * (1 - progress)) / 2;

const round = (n: number): number => Math.round(n * 1e4) / 1e4 || 0; // `|| 0` drops -0

/**
 * The original path as keyframe stops. The quarter circle (centre at (1, 0), from (1, 1) back to
 * (0, 0)) is sampled so its angle follows easeInOutCubic, like `tween.power3.easeInOut`.
 */
export function path(): readonly Stop[] {
  const right = LEGS[0] / DURATION_MS;
  const down = (LEGS[0] + LEGS[1]) / DURATION_MS;
  const stops: Stop[] = [
    { at: 0, x: 0, y: 0, ease: EASE_IN_CUBIC },
    { at: right, x: 1, y: 0, ease: EASE_OUT_CUBIC },
    { at: down, x: 1, y: 1, ease: 'linear' },
  ];
  for (let k = 1; k <= ARC_STEPS; k++) {
    const angle = (Math.PI / 2) * (1 + k / ARC_STEPS);
    stops.push({
      at: round(down + (1 - down) * arcTime(k / ARC_STEPS)),
      x: round(1 + Math.cos(angle)),
      y: round(Math.sin(angle)),
      ease: 'linear',
    });
  }
  return stops;
}

const offset = (n: number): string => `calc(var(--travel) * ${String(n)})`;

/** `@keyframes travel` for the stops, using the individual `translate` property. */
export function keyframes(stops: readonly Stop[]): string {
  const frames = stops.map(
    (s) =>
      `${(s.at * 100).toFixed(2)}% { translate: ${offset(s.x)} ${offset(s.y)}; ` +
      `animation-timing-function: ${s.ease}; }`,
  );
  return `@keyframes travel { ${frames.join(' ')} }`;
}

export interface State {
  /** How many times the animation was started. Each run gets a fresh element. */
  readonly runs: number;
}

export type Msg = { readonly _tag: 'Animate' };

/** One run's element; keyed by the run number, so each run gets a fresh one. */
const target = (run: number) => html`<div class=${run === 0 ? 'target' : 'target moving'}></div>`;

export const Animation = define<State, Msg>()('gy-animation', {
  init: () => ({ runs: 0 }),
  intent: { Animate: true },
  update: { Animate: (s) => ({ runs: s.runs + 1 }) },
  view: (s, i) => html`
    <button type="button" data-intent=${i.Animate}>Animate it!</button>
    <div class="stage" aria-hidden="true">
      ${
        // A new key per run replaces the element, which restarts the CSS animation.
        keyed(s.runs, target(s.runs))
      }
    </div>
  `,
  styles: css`…`,
});
```

### Animated letters

Letters you type grow in and shrink out. The model tracks which are present or leaving; CSS transitions animate.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/animated-letters
- Explained in: [Model and update](https://gyral.dev/docs/update/)

`src/letters.ts`:

```ts
import { css, define, each, html, type Next } from '@gyral/core';
import { delay } from '@gyral/time';

import { letterKeys } from './keyboard.js';

// The model only knows which letters are present or leaving; CSS transitions do the growing
// and shrinking, so there is no per-frame easing loop over the letters.

/** How long a letter takes to grow in or shrink out. The model waits this long to drop it. */
export const TRANSITION_MS = 600;

export interface Letter {
  readonly key: string;
  /** Shrinking out; removed from the model once the transition has had time to finish. */
  readonly leaving: boolean;
}

export interface State {
  readonly letters: readonly Letter[];
}

export type Msg =
  | { readonly _tag: 'Key'; readonly letter: string }
  | { readonly _tag: 'Gone'; readonly letter: string };

const byKey = (a: Letter, b: Letter): number => a.key.localeCompare(b.key);

const setLeaving = (s: State, letter: string, leaving: boolean): State => ({
  letters: s.letters.map((l) => (l.key === letter ? { ...l, leaving } : l)),
});

/** Toggles a letter: absent → added, present → leaving (dropped later), leaving → back. */
export function toggle(s: State, letter: string): Next<State, Msg> {
  const existing = s.letters.find((l) => l.key === letter);
  if (existing === undefined) {
    return { letters: [...s.letters, { key: letter, leaving: false }].toSorted(byKey) };
  }
  if (existing.leaving) return setLeaving(s, letter, false);
  return [
    setLeaving(s, letter, true),
    // One lane per letter: toggling it again restarts its own timer, nobody else's.
    [delay<Msg>(TRANSITION_MS, { _tag: 'Gone', letter }, { key: `leave:${letter}` })],
  ];
}

export const AnimatedLetters = define<State, Msg>()('gy-animated-letters', {
  // The original starts with just "A"; "GYRAL" shows the staggered entrance.
  init: () => ({ letters: ['A', 'G', 'L', 'R', 'Y'].map((key) => ({ key, leaving: false })) }),
  // Key presses stream in for as long as the component is in the page (ADR 0025).
  subscriptions: () => [letterKeys<Msg>((letter) => ({ _tag: 'Key', letter }))],
  update: {
    Key: (s, m) => toggle(s, m.letter),
    // Ignore a stale timer if the letter came back while it was shrinking.
    Gone: (s, m) => ({ letters: s.letters.filter((l) => l.key !== m.letter || !l.leaving) }),
  },
  view: (s) => html`
    <p id="hint">Press a letter key (A–Z) to add it, or press it again to remove it.</p>
    <ul aria-label="Letters" aria-describedby="hint">
      ${each(
        s.letters,
        (l) => l.key,
        (l) =>
          html`<li class=${l.leaving ? 'out' : 'in'} aria-hidden=${l.leaving ? 'true' : 'false'}>
            ${l.key}
          </li>`,
      )}
    </ul>
  `,
  styles: css`…`,
});
```

### Devtools demo

A small app that exercises the devtools panel: updates, a store and a command lane.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/devtools
- Explained in: [Devtools](https://gyral.dev/docs/devtools/)

`src/demo.ts`:

```ts
import { css, define, defineStore, html, send } from '@gyral/core';
import { delay } from '@gyral/time';

/** A shared store, so the timeline shows store messages too. */
export const tally = defineStore<{ readonly total: number }, { readonly _tag: 'Add' }>('tally', {
  init: () => ({ total: 0 }),
  update: { Add: (s) => ({ total: s.total + 1 }) },
});

export interface State {
  readonly count: number;
  readonly saving: boolean;
}

export type Msg =
  { readonly _tag: 'Increment' } | { readonly _tag: 'Save' } | { readonly _tag: 'Saved' };

/** Increment updates state and the store; Save runs a delayed command (a command lane). */
export const Demo = define<State, Msg>()('gy-devtools-demo', {
  init: () => ({ count: 0, saving: false }),
  stores: [tally],
  intent: {
    Increment: true,
    Save: true,
  },
  update: {
    Increment: (s) => [{ ...s, count: s.count + 1 }, [send(tally, { _tag: 'Add' })]],
    Save: (s) => [
      { ...s, saving: true },
      [delay<Msg>(400, { _tag: 'Saved' }, { key: 'save', concurrency: 'switch' })],
    ],
    Saved: (s) => ({ ...s, saving: false }),
  },
  view: (s, i, { read }) => html`
    <p>Count: <output>${s.count}</output> · Store total: <output>${read(tally).total}</output></p>
    <p>
      <button type="button" data-intent=${i.Increment}>Increment</button>
      <button type="button" data-intent=${i.Save}>${s.saving ? 'Saving…' : 'Save'}</button>
    </p>
  `,
  styles: css`…`,
});
```

## A whole application

[gyral-shop](https://github.com/gyraljs/gyral-shop) is a department store built with Gyral: catalog, search, cart, checkout, accounts and an admin area, server-rendered with forms that work without JavaScript, and four switchable themes. It runs at https://demo-shop.gyral.dev, reset every night.

---

# What you can build with Gyral

> What Gyral makes easy, shown as short recordings of examples: undo and replay, type-ahead without stale results, and pages that work before JavaScript.

Source: https://gyral.dev/what-you-can-build/

Gyral treats every interaction as data. That makes these easy. Each demo is a recording of an example in the Gyral repository; the text below describes what each recording shows.

## Undo, redo and replay

Undo, redo, a scrubbable timeline and replay in a few lines: every edit is a message kept as data, so history is a list and the picture is a fold over it.

The usual way: Undo is a feature you build: command objects, inverse operations and snapshots kept in sync with mutable state.

The recording: A heart is painted pixel by pixel. Six presses of Undo leave the removed pixels as dashed ghosts, Redo brings one back, the timeline slider scrubs back to an empty grid, and Replay repaints the whole session.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/undo-replay
- Explained in: [Model and update](https://gyral.dev/docs/update/)

## Type-ahead without stale results

Type-ahead that never shows results for something you are no longer typing: one word, concurrency: switch, cancels the request in flight.

The usual way: Each keystroke fires a fetch and whichever answer lands last wins; fixing it means AbortControllers, request ids and "is this still current?" checks.

The recording: One search box feeds two result panels backed by the same slow server. Typed slowly, both panels agree. Typed quickly, the panel without cancellation ends up showing results for "w" because that slow answer arrived last, while the panel using switch cancels the older requests and shows results for "work".

- Source: https://github.com/gyraljs/gyral/tree/main/examples/typeahead-race
- Explained in: [Effects and drivers](https://gyral.dev/docs/effects/#concurrency-lanes)

## Works before JavaScript loads

One page that works completely with JavaScript off, then checks as you type and submits without a reload once JavaScript loads: same markup, same schema on both sides.

The usual way: You pick one: a server-rendered form, or a client app that is blank until its bundle runs, and validation rules written twice.

Recording (JavaScript off): With JavaScript disabled, an RSVP form is filled in and sent. The server answers with the error "Grace already replied with that email" and keeps the typed values; a second reply goes through and the page says "You're on the list".

Recording (JavaScript on): The same page with JavaScript: "Enter a valid email address" appears while the email is still being typed, disappears once it is valid, and the reply is sent without reloading the page.

- Source: https://github.com/gyraljs/gyral/tree/main/examples/no-js-first
- Explained in: [Forms](https://gyral.dev/docs/forms/)