sygnal 5.3.7 → 6.0.0

package/llms.txt

@@ -0,0 +1,313 @@
+# Sygnal
+
+> Reactive component framework (Cycle.js Model-View-Intent, JSX views, xstream streams). `npm i sygnal`; Vite: `import sygnal from 'sygnal/vite'`, `plugins: [sygnal()]`; entry: `run(App)`. This file shows only the canonical forms. Strict mode (`sygnal-check --strict`, runtime `strict: true`) flags other forms as SYG5xx; forms 6.0 removed (positional views, `'A | SINK'` keys, `CHILD.select('Name')`, `.components`, `.peers`, `component()`) are SYG612: https://sygnal.js.org/guide/migrating-to-6/
+
+## 1. Mental model
+- A component is a pure view function plus static properties: `.intent` (WHEN: sources → named action streams), `.model` (WHAT: action → one reducer per sink), `.initialState`.
+- There is one state tree. A child sees its parent's whole state, or a slice with `state="key"`. A Collection item sees one array element.
+- Every side effect is a sink of a model entry (STATE, EVENTS, PARENT, EFFECT, custom drivers). JSX never has event handlers (`onClick`).
+- Streams are xstream, not RxJS. An intent's DOM selectors only see the component's own JSX, never a child component's.
+
+## 2. Component anatomy
+```jsx
+import { ABORT } from 'sygnal'
+function Counter({ state, context, label }) {  // 1st arg: parent props + state, context, children, slots
+  return (
+    <div className="counter">
+      <span>{label} {state.count} (x2 = {state.double})</span>
+      <button className="inc">+</button>
+      <button className="reset">reset</button>
+    </div>
+  )
+}
+Counter.initialState = { count: 0 }                    // root only: a child gets state from its parent (SYG405)
+Counter.calculated = { double: state => state.count * 2 } // or [['count'], fn]; read as state.double
+Counter.context = { total: state => state.count }        // itself + descendants: ({ context }) => context.total
+Counter.intent = ({ DOM }) => ({                          // sources: DOM STATE EVENTS CHILD props$ commands$ dispose$ + drivers
+  INC:   DOM.click('.inc'),
+  RESET: DOM.click('.reset'),
+})
+Counter.model = {
+  INC:   (state, data, next, props) => ({ ...state, count: state.count + 1 }),
+  RESET: (state) => (state.count === 0 ? ABORT : { ...state, count: 0 }),
+}
+Counter.onError = (error, { componentName }) => <div className="error">{componentName} failed</div>
+export default Counter
+```
+- Reducer `(state, data, next, props)`. `data` is the action stream's value. `next('ACTION', data?, delayMs = 10)` dispatches another action of this component `delayMs` after the call, whenever it is called: also later, from a timer or callback in an EFFECT (HTTP goes through `makeFetchDriver`, not `fetch` + `next()`). `props` holds the parent's props plus `state`, `context`, `children`, `slots`.
+- Model entry: a function is the STATE reducer. An object `{ STATE, EVENTS, PARENT, EFFECT, LOG, <DRIVER>: fn }` maps each sink to a `(state, data, next, props)` function whose return value goes to that sink. `<SINK>: true` forwards `data` as-is.
+- **Every sink of one entry sees the state from before this action**: EVENTS, PARENT, EFFECT and drivers never see what STATE returns. Compute the new value from `(state, data)` inside the sink: `INC: { STATE: s => ({ ...s, n: s.n + 1 }), PARENT: s => ({ n: s.n + 1 }) }`.
+- Built-in actions (model only): `BOOTSTRAP` (once, just after mount), `INITIALIZE` (automatic: sets initialState), `DISPOSE` (unmount). `HYDRATE` is not built in (6.0): SSR data comes from Vike `+data` / `hydrateState`. Declaration statics (`connections`, `resources`, `route`, `head`) are computed from state, with or without a model; a root that declares one needs `initialState` (SYG132). Also reserved as statics: `timers`, `uses`, `persist`, `viewTransitions` (§3).
+
+## 3. Canonical examples
+### State update, ABORT, set / toggle, controlled input
+```jsx
+import { ABORT, set, toggle } from 'sygnal'
+function AddTodo({ state }) {
+  return (
+    <div>
+      <input className="draft" aria-label="New todo" value={state.draft} />
+      <button className="add">Add</button>
+      <button className="help">?</button>
+      {state.showHelp && <p className="hint">Type, then Add</p>}
+    </div>
+  )
+}
+AddTodo.initialState = { draft: '', todos: [], nextId: 1, showHelp: false }
+AddTodo.intent = ({ DOM }) => ({
+  DRAFT: DOM.input('.draft').value(),   // a bound value={...} needs an input listener (SYG111)
+  ADD:   DOM.click('.add'),
+  HELP:  DOM.click('.help'),
+})
+AddTodo.model = {
+  DRAFT: set((state, draft) => ({ draft })),           // merges: ({ ...state, draft }); never set('draft') (SYG221)
+  ADD: (state) => {
+    const text = state.draft.trim()
+    if (!text) return ABORT                              // "no change" (returning the same `state` works too)
+    return { ...state, draft: '', nextId: state.nextId + 1, todos: [...state.todos, { id: state.nextId, text }] }
+  },
+  HELP: toggle('showHelp'),
+}
+```
+### Multi-sink entry + EVENTS between non-adjacent components
+```jsx
+import { event } from 'sygnal'
+function SaveButton({ state }) {
+  return <button className="save">{state.saving ? 'Saving' : 'Save'}</button>
+}
+SaveButton.intent = ({ DOM }) => ({ SAVE: DOM.click('.save') })
+SaveButton.model = {
+  SAVE: {
+    STATE:  (state) => ({ ...state, saving: true }),
+    EVENTS: event('DOC_SAVED', (state) => ({ id: state.id })),  // or event('RESET'), event('MODE', 'dark')
+  },
+}
+function Toast({ state }) {   // anywhere in the tree: EVENTS is a global bus
+  return <p className="toast">{state.lastSaved}</p>
+}
+Toast.intent = ({ EVENTS }) => ({ SAVED: EVENTS.select('DOC_SAVED') })  // emits the payload only
+Toast.model = { SAVED: (state, payload) => ({ ...state, lastSaved: payload.id }) }
+```
+### Child → parent (PARENT + CHILD.select), Collection, item removal
+```jsx
+import { Collection } from 'sygnal'
+function TaskItem({ state }) {
+  return (
+    <li className="task" data={{ id: state.id }}>
+      {state.title} <button className="pick">pick</button> <button className="remove">x</button>
+    </li>
+  )
+}
+TaskItem.intent = ({ DOM }) => ({ PICK: DOM.click('.pick'), REMOVE: DOM.click('.remove') })
+TaskItem.model = {
+  PICK:   { PARENT: (state) => ({ taskId: state.id }) },   // the parent receives exactly this value
+  REMOVE: () => undefined,                                   // a Collection item removes itself
+}
+function TaskList({ state }) {
+  return (
+    <div>
+      <p className="picked">{state.picked}</p>
+      <ul className="tasks">
+        <Collection of={TaskItem} from="tasks" />
+      </ul>
+    </div>
+  )
+}
+TaskList.initialState = { picked: null, tasks: [{ id: 1, title: 'Write' }, { id: 2, title: 'Test' }] }
+TaskList.intent = ({ CHILD }) => ({ PICKED: CHILD.select(TaskItem) })  // the function, not a string
+TaskList.model = { PICKED: (state, { taskId }) => ({ ...state, picked: taskId }) }
+```
+- `from` names an array field. Items are keyed by `.id` (by index if they have none). `filter={t => !t.done}`; `sort="title"`, `{ title: 'desc' }`, an array of those, or a compare function. Sorting and filtering only change what renders: the state array keeps its order, and an item's edit (`{ ...state, done: true }`) is written back to its element by key. Items render directly into the parent element, with no wrapper (`<Collection className>` is SYG612: put the class on your own `<ul>`). Switchable: `<Switchable of={{ home: Home, settings: Settings }} current={state.tab} />` (optional `state="slice"`); hidden pages stay alive, and `instance={key}` re-creates the current page with fresh state when the key changes (a router: `instance={state.route.path}`).
+### Behaviors (`uses`): shared state + actions
+- `TaskList.uses = { pager: pager({ pageSize: 10, next: '.newer', prev: '.older' }) }` adds `state.pager` (`{ page, pageSize, total }` + calculated `offset`, `pages`, `hasPrev`, `hasNext`) and the actions `pager.NEXT`, `pager.PREV`, `pager.GOTO`, `pager.SET_TOTAL`; a click on what `next`/`prev` name triggers them. Options set the slice's start values; the key must not also be in `initialState` (SYG127). Also from `'sygnal'`: `selection({ multi: true, item: '.pick', from: 'mails' })` (`data-id` on each item; `isSelected(state.sel, id)`) and `undo({ key: 'doc', undo: '.undo', redo: '.redo' })` (`state.history.canUndo`/`canRedo`; `coalesce: ['TYPE'], coalesceMs: 500` groups only typing, each other action is its own step; `key: ['todo', 'done']` records several keys as one step; `node_modules/sygnal/dist/guide/undo.md`).
+- Your own: `const disclosure = defineBehavior({ initialState: { open: false }, intent: ({ DOM }, { toggle }) => ({ TOGGLE: DOM.click(toggle) }), model: { TOGGLE: (slice) => ({ ...slice, open: !slice.open }) } })`, used as `uses = { more: disclosure({ toggle: '.more' }) }`. Its reducers and `calculated` get and return the slice (`state.more`), its action names have no key, and any sink works. Options: `persist: false` (UI state `persist()` never saves), `undoStep: ['DONE']` (its other actions form one gesture: one undo entry when `DONE` completes it).
+- The host names behavior actions with the key: an intent action `'more.TOGGLE': DOM.keydown(…)` replaces the behavior's trigger; a model entry `'more.TOGGLE': (state) => …` runs after the behavior's, on the full state; tests use `t.simulateAction('more.TOGGLE')`. Guide: `node_modules/sygnal/dist/guide/behaviors.md`
+### Forms with validation (the `form` behavior)
+- `Signup.uses = { form: form(schema, { values: { email: '', addresses: [{ id: 1, city: '' }] }, submit: 'SIGN_UP' }) }` (`form` from `'sygnal'`), any Standard Schema (zod, valibot, or `{ '~standard': { version: 1, vendor, validate } }`). Fields inside the `<form>` are matched by `name`, a path in `values` (array rows by id: `addresses.7.city`): no intent per field (SYG230: a name not in `values`).
+- View: `const f = state.form.fields`; `<input id={uid('email')} name="email" value={f.email.value} aria-invalid={f.email.invalid} aria-describedby={uid('email-error')} />`, `<p id={uid('email-error')}>{f.email.error}</p>`, a `<label for={uid('email')}>`. `f.x.error` is what to show (after blur or a submit); also `state.form.submitting`, `state.form.valid`, `state.form.error` (form-level).
+- An invalid submit shows every error and focuses the first invalid field; a valid one dispatches `SIGN_UP` with the schema's output: `SIGN_UP: { HTTP: (state, values) => ({ url, method: 'POST', json: values, ok: 'form.DONE', error: 'form.ERRORS' }) }`; `state.form.submitting` is `true` until the reply (a second submit meanwhile is dropped); a submit entry without `HTTP` (a wizard step's `NEXT: { PARENT: … }`) is done at once, no `form.DONE` needed; `form.ERRORS` puts a 422's `{ errors: { field: msg } }` or `{ errors: [{ path: ['items', 0, 'qty'], message }] }` (an index is the row's position in what was sent) on the fields and focuses the first; a reply with no field message shows in `state.form.error` (`Request failed (500)`); a host entry `'form.DONE': (state, body) => …` runs after the form's. Two forms in one component: `form: '.login'` on each (SYG237).
+- **The `form` slice lives in the host's state**, and a Switchable page (no `state=`) shares its parent's, so the values survive leaving the page and coming back, even when `instance=` re-creates it. When the form must start empty on each visit, say so: `form(schema, { values: EMPTY, submit: 'SAVE', resetOnShow: true })` starts over (start values; touched, errors and the submit cleared) each time the form is shown: the page shown again, the component mounted again. Off by default (a wizard step keeps its values). A start value that comes from state (a default category from the settings) goes in a `values` function of the host's state, called at each start: `values: (state) => ({ ...EMPTY, category: state.settings.defaultCategory })`. When removing a feature that fed a start value, keep `resetOnShow`.
+- Rows, inline (no child component): `state.form.values.addresses.map((row, i) => …)` with `const c = f['addresses.' + row.id + '.city']`, `name={c.name} value={c.value}`, ids `uid('city-' + row.id)`, `<button type="button" className="remove" data-id={row.id}>`; `'form.ADD': DOM.click('.add').mapTo({ field: 'addresses', value: { city: '' } })`, `'form.REMOVE': DOM.click('.remove').map((e) => ({ field: 'addresses', id: e.target.dataset.id }))`. Rows as components: `<Collection of={Row} from={{ get: (s) => s.form.values.addresses }} fields={f} />`, Row `REMOVE: { PARENT: (s) => ({ field: 'addresses', id: s.id }) }` + host `'form.REMOVE': CHILD.select(Row)`.
+- Async check: `check: { email: { request: (email) => ({ url: '/api/email-free', query: { email } }), error: (body) => !body.free && 'Taken' } }` (on blur; a submit waits for it; `f.email.pending`). Tests: `t.simulateEvent('[name="email"]', 'input', { value })`, `'focusout'`, `'submit'` on the form; `t.state.form.fields.email.error`. Guide (recipe first): `node_modules/sygnal/dist/guide/forms.md`; details `forms-reference.md`
+### Commands (parent → child), element commands, timers, persistence
+- `const player = createCommand()` (from `'sygnal'`); the parent passes it as a prop, `<Player commands={player} state="player" />`, and calls it from an EFFECT (side effect only, returns nothing): `PLAY: { EFFECT: () => player.send('play', data) }`. The child's intent listens with `PLAY: commands$.select('play')`, which emits `send()`'s data.
+- **ELEMENT** (built in, no driver) calls a method on an element of the sending instance's own view, after the render the action causes: `SUBMIT: { STATE: (s) => ({ ...s, errors: validate(s) }), ELEMENT: (s) => (validate(s).email ? { focus: '.email' } : ABORT) }`. The first key is the method (`focus blur select click scrollIntoView showModal show close showPopover hidePopover togglePopover`) and its value the target (a selector); other keys are options (`{ scrollIntoView: '.row', block: 'nearest' }`, `{ close: '.help', returnValue: 'done' }`); an array sends several; `{ focus: focusWithin('.title') }` (from `'sygnal'`) reaches into children and Collection items. `DOM.close('.help')` hears a dialog close. SYG640: no target; SYG641: unknown method. Tests: `t.commands('ELEMENT')`; `dom: 'real'` also runs them. Guide: `node_modules/sygnal/dist/guide/element-commands.md`
+- **Timers**, from state like `connections` (falsy stops, a changed spec restarts): `Clock.timers = (state) => ({ tick: state.running && { every: 1000, action: 'TICK' } })` (also `{ after: ms, action }`, `{ frame: 'FRAME' }`); `TICK` gets `{ n, t }`. Needs `run(App, { TIMER: makeTimerDriver() })` (SYG643 without it); no `setInterval`. Tests need no driver: fake timers, `await vi.advanceTimersByTimeAsync(ms)`, `t.timers()`. Guide: `node_modules/sygnal/dist/guide/timers.md`
+- **Persistence** (root only, SYG224): `App.persist = persist({ key: 'todo-app', pick: ['todos', 'filter'] })` (also `version`, `migrate: (old, fromVersion) => keys`, `omit`, `storage: 'local' | 'session' | { getItem, setItem, removeItem }`, `sync: true`, `debounceMs`) restores those keys into `initialState` before the first render and saves them after each change (100 ms debounce) as JSON `{ version, state }` (`format: 'plain'`: the picked keys alone, no `version`/`migrate`); `PERSIST: { clear: true }` in an entry removes the copy. Tests: `renderComponent(App, { storage: { 'todo-app': { version: 1, state: { todos: [] } } } })`, `await t.settle()`, `t.storage('todo-app')`. Guide: `node_modules/sygnal/dist/guide/persistence.md`
+### Third-party widgets (`defineWidget`) and web components
+- `defineWidget({ tag, mount(el, props, dispatch), update(instance, props), unmount(instance), events, commands })` (from `'sygnal'`) makes a JSX tag: `const DatePicker = defineWidget({ tag: 'input', mount: (el, props, dispatch) => flatpickr(el, { defaultDate: props.value, onChange: ([d]) => dispatch('pick', d) }), update: (fp, props) => fp.setDate(props.value, false), unmount: (fp) => fp.destroy(), events: ['pick'], commands: { open: (fp) => fp.open() } })`. Also `fallback` (SSR content), `hostProps` / `ownProps` (props on / kept off the host), `mount`'s 4th argument `error(e)` (a failure the library reports later).
+- View: `<label>Due <DatePicker className="due" value={state.due} /></label>` (the host element; the widget owns its content and keeps its instance across renders). Intent: `DUE: DOM.select('.due').events('pick').detail()` (`.detail(fn?)` = e.detail). Model: `OPEN: { ELEMENT: { open: '.due' } }` runs the widget's command (it wins over a native method of the same name).
+- List every dispatched name in `events` and name them yourself (`'pick'`, not `'change'`: SYG140/144); `update` gets the newest props when they change (without it, a change remounts); a throwing `mount`/`update` renders the component's `onError` fallback in its place (`onError` phase `'widget'`). Never `DOM.select(DatePicker)`: select its class (SYG143).
+- Tests: `t.widget('.due').dispatch('pick', date)`, `t.widget('.due').props.value`, `t.commands('ELEMENT')`; `dom: 'real'` mounts it (`.instance`). Guide: `node_modules/sygnal/dist/guide/widgets.md`
+- Web components (Web Awesome, Shoelace) are elements, no wrapper: render the tag (`<wa-rating className="food" label="Food" value={state.food} />`; props set properties: `withClear`, not `with-clear`; attributes via `attrs={{ name: 'stars' }}`) and select it by class: `DOM.select('.food').events('change').value(Number)`, library events with any name: `DOM.select('.food').events('wa-hover').detail()`. Guide: `node_modules/sygnal/dist/guide/web-components.md`
+### HTTP (makeFetchDriver + reply actions), latest response only
+```jsx
+import { ABORT, debounce } from 'sygnal'
+function Search({ state }) {
+  return <div><input className="q" aria-label="Search" value={state.query} /><p className="status">{state.status}</p><ul>{state.results.map(r => <li>{r.title}</li>)}</ul></div>
+}
+Search.initialState = { query: '', status: '', results: [] }
+Search.intent = ({ DOM }) => ({   // no intent line for the reply
+  TYPE:   DOM.input('.q').value(),
+  SEARCH: DOM.input('.q').value().compose(debounce(300)).filter(q => q !== ''),
+})
+Search.model = {
+  TYPE: {
+    STATE: (state, query) => (query === '' ? { ...state, query, status: '', results: [] } : { ...state, query }),
+    HTTP:  (state, query) => (query === '' ? { abort: 'RESULTS' } : ABORT),   // clearing cancels the request in flight
+  },
+  SEARCH: {
+    STATE: (state) => ({ ...state, status: 'Searching…' }),
+    HTTP:  (state, q) => ({ url: '/api/search', query: { q }, ok: 'RESULTS', error: 'FAILED', latest: true }),
+  },
+  RESULTS: (state, body) => ({ ...state, status: '', results: body.results }),   // ok: the parsed body
+  FAILED:  (state, { status, error }) => ({ ...state, status: status === 404 ? 'Not found.' : 'Search failed.', results: [] }),
+}
+```
+- main.js: `run(Search, { HTTP: makeFetchDriver() })` (import both from `'sygnal'`; options `baseUrl headers init timeoutMs`). Request: `{ url, ok, error, key, query, json, body, method (POST with json/body, else GET), headers, latest, timeoutMs, parse: 'auto' | 'json' | 'text' | 'response', init: { credentials, mode, cache, ... } }`; other keys (an id) aren't sent and come back on `request`. The `ok` action gets the parsed body; the `error` action gets `{ error, status, body, request }` (non-2xx: `status` + parsed `body`; network error or timeout: `status` undefined, a timeout has `error.name === 'TimeoutError'`). The reply reaches exactly the instance that sent it (two `<Search>`es, every Collection item), so no request ids. Never `HTTP.select`/`HTTP.errors` for your own request (SYG508), never `then`/`catch` keys (SYG610: not sent); an `ok`/`error` name with no model entry is SYG112. Don't call `fetch` in a component, intent or EFFECT. Guide: `node_modules/sygnal/dist/guide/http.md` (online: https://sygnal.js.org/guide/http/)
+- `latest: true`: a newer request in the same lane (`key`: a constant name, never an id or URL; default the `ok` action) from the same instance aborts the older ones once it is sent: their replies never arrive after that, but one that lands before it (while the newer input still waits out a debounce) does. `{ abort: 'RESULTS' }` (it names the lane: with a custom `key`, abort that key; or `{ abort: true, key }`) cancels without sending; a removed instance's requests are aborted. **Build the request from `(state, data)`**: sinks see the state before the action, so `SHOW: { STATE: (s, id) => ({ ...s, id }), HTTP: (s, id) => ({ url: '/api/q/' + id, ok: 'LOADED' }) }`, not `s.id`.
+- Other promise APIs: `driverFromAsync(fn)` takes the same reply actions: `{ value, ok: 'DONE', error: 'FAILED' }` calls `fn(value)`; `DONE` gets the result, `FAILED` `{ error, request }` (no `latest`/abort). One-off async work: `EFFECT: async (state, data, next, { signal }) => { ...; next('DONE', result) }` (rejection: SYG214; `signal` aborts on unmount; no concurrency control). A driver is any function `sink$ => source`. Page-wide events: `DOM.select('document' | 'body').events(type)`, CSS-filtered with `DOM.select('document').select('.overlay').events('click')`.
+### WebSocket / SSE (makeSocketDriver + connections)
+```jsx
+import { ABORT } from 'sygnal'
+function Chat({ state }) {
+  return <div><p className="status">{state.status}</p><ul>{state.messages.map(m => <li>{m.text}</li>)}</ul><input className="draft" aria-label="Message" value={state.draft} /><button className="send">Send</button><button className="leave">Leave</button></div>
+}
+Chat.initialState = { room: 'general', status: 'connecting', messages: [], draft: '' }
+Chat.connections = (state) => ({   // from state, diffed by name: new opens, falsy/removed closes, changed URL reconnects
+  room: state.room && { socket: `/ws/rooms/${state.room}`, message: 'RECEIVED', open: 'CONNECTED', close: 'DROPPED',
+    reconnect: { delayMs: 1000, maxDelayMs: 1000, jitter: false } },   // fixed 1 s retry (default: 500 ms doubling to 10 s, ±20%)
+})
+Chat.intent = ({ DOM }) => ({ DRAFT: DOM.input('.draft').value(), SEND: DOM.click('.send'), LEAVE: DOM.click('.leave') })
+Chat.model = {
+  DRAFT: (state, draft) => ({ ...state, draft }),
+  SEND: {
+    STATE: (state) => (state.draft.trim() ? { ...state, draft: '' } : ABORT),
+    WS:    (state) => (state.draft.trim() ? { to: 'room', json: { text: state.draft } } : ABORT),  // queued while (re)connecting
+  },
+  LEAVE:     (state) => ({ ...state, room: null, status: 'offline', messages: [] }),   // closes it: no DROPPED
+  RECEIVED:  (state, msg) => ({ ...state, messages: [...state.messages, msg] }),        // the JSON-parsed frame
+  CONNECTED: (state) => ({ ...state, status: 'online' }),                               // data: { reconnected }
+  DROPPED:   (state, { willReconnect }) => ({ ...state, status: willReconnect ? 'reconnecting' : 'offline' }),  // { code, reason, willReconnect }
+}
+```
+- main.js: `run(Chat, { WS: makeSocketDriver() })` (options `baseUrl reconnect queueLimit`). Without it the static opens nothing and nothing reports it. Spec keys: `socket` (a path gets ws:/wss: from the page) or `sse` (read-only; `events: { 'price-update': 'PRICE' }` for named events), `message open close error` (all optional reply actions, to this instance only), `reconnect` (`false` = never), `share` (default true: one socket per URL, ref-counted), `protocols`, `withCredentials`. `close` fires only for drops the app didn't cause; leaving, a URL change, unmount and dispose close silently, so no connection-generation ids. A room switch must `ABORT` when the room is unchanged (an unchanged connection fires no new `open`). `error` gets `{ error }`. `{ to, json | text | binary }` on a name this instance didn't declare, a closed-for-good or an SSE connection is SYG611. Use the static OR a model-sent `{ connections }`, never both (each is the whole set). Guide: https://sygnal.js.org/guide/sockets/
+### Reads that follow state: `resources`
+```jsx
+function Quote({ state }) {
+  const { status, data, error, refreshing } = state.quote  // status: 'idle' | 'loading' | 'success' | 'error'
+  const text = status === 'loading' ? 'Loading…' : status === 'error' ? `Failed (${error.status ?? 'network'})` : refreshing ? 'Updating…' : ''
+  return <div><button className="next">Next</button><button className="refresh">Refresh</button><p className="status">{text}</p><p className="text">{data?.text}</p></div>
+}
+Quote.initialState = { id: 1 }
+Quote.resources = { quote: (state) => state.id && `/api/quotes/${state.id}` }  // a URL or a request ({ url, query, … }); falsy = idle
+Quote.intent = ({ DOM }) => ({ NEXT: DOM.click('.next'), REFRESH: DOM.click('.refresh') })
+Quote.model = {
+  NEXT:    (state) => ({ ...state, id: state.id + 1 }),  // new request: 'loading' without data; the old one is aborted
+  REFRESH: { HTTP: { refresh: 'quote' } },               // same request: data kept, refreshing: true
+}
+```
+- `resources` is the form for data a component shows (reads derived from state); writes and click-triggered one-off requests keep reply actions (above). Needs `run(Quote, { HTTP: makeFetchDriver() })`. The core keeps `state.quote` (named by the resource; don't set it in initialState: it reads as `{ status: 'idle' }`) and writes it with the built-in `RESOURCE` action. When the request changes (by value) it is fetched and the older one aborted, so a stale reply is never shown: no ids, `latest`, ok/error actions or loading flags to write. `data` is the parsed body; `error` is the Error (`error.status`, `error.body` for a non-2xx). Falsy aborts and goes idle. TS: `quote: Resource<Quote>` in the state type.
+- **A component that reads `state.items` declares `items` in its own `.resources`**, even when another page (or its parent) declares the same request: without it `state.items` is undefined on a direct visit (or holds whatever another page loaded last), and a test that starts on the declaring page hides this. Each declaration fetches; with a `queryCache()` the repeat shows the cached data at once and identical requests in flight share one fetch.
+- **Refetch rule**: a new request (another id) is `'loading'` with no data; a refetch of the same request (`{ refresh: 'quote' }`, an invalidation, focus, polling) keeps `status`, `data` and `error` with `refreshing: true`, and a failed refetch keeps `data`. When the old value must not show (Refresh shows "Loading…"), treat `refreshing` as loading. `keepPrevious: true` on the request keeps the old data across a request change too (pagination). `ok: 'FOUND'` / `error: 'FAILED'` on the request also dispatch those actions after the write (append a page, fill a field).
+- Invalidation: tag reads `{ url, tags: ['quotes'] }`; a write with `invalidates: ['quotes']` (tags, a `'/api/quotes'` URL prefix, or a predicate) refetches the matching mounted reads after a 2xx, keeping their data; `{ invalidate: 'quotes' }` on the HTTP sink does it at once. Works with or without the cache. The refetch aborts the read already in flight, so a reply sent before the write never lands (no sequence numbers); a shared cache fetch from before never writes the cache.
+- `updates: 'item'` on a write (React Query's `setQueryData`): after a 2xx, before the `ok` action and `invalidates`, the reply becomes `state.item.data` and its cache entry at once, and the item's read in flight is aborted; `updates: { items: (list, reply) => newList }` derives the data. With `invalidates` the read then refetches keeping the written data (`refreshing`). An idle resource is skipped; the `ok` action still gets the reply.
+- Query cache (opt-in, its own export): `run(App, { HTTP: makeFetchDriver({ cache: queryCache({ staleTime: 30000, gcTime: 300000 }) }) })`. A request fetched before shows its cached data at once (`'success'`, `refreshing: true` while it revalidates; nothing is sent while younger than `staleTime`, default 0), identical requests in flight share one fetch, and stale mounted resources refetch on window focus and reconnect. Reply-action GETs use it with `cache: true` or `staleTime`. Per request: `retry: 3` or `{ count, delayMs }` (default 0; network errors, 408, 429, 5xx), `validate: schema` (Standard Schema: zod, valibot), `refetchEvery: 10000` (polling). `{ prefetch: '/api/quotes/2' }` on the sink warms the cache. SSR: `cache.set(request, data)`, `renderToString(App, { cache })`, `cache.dehydrate()` → `queryCache({ initial: snapshot })` (Vike: `pageContext.queryCache` from `+data`). Guide and recipes (list/detail + save, optimistic update, pagination, infinite list, save status): `node_modules/sygnal/dist/guide/resources.md` (online: https://sygnal.js.org/guide/resources/)
+- List/detail + save, cached: `items: (s) => s.view === 'list' && { url: '/api/items', staleTime: 2000 }`, `item: (s) => s.view === 'detail' && { url: '/api/items/' + s.id, staleTime: 2000 }` (declared only while shown; shown again: cached data at once, refetched once stale), `makeFetchDriver({ cache: queryCache() })` in main.js **and** `renderComponent(App, { http: { cache: queryCache() } })` in every test (a `staleTime` without a queryCache is SYG635), the save `{ url, method: 'PUT', json, ok: 'SAVED', error: 'SAVE_FAILED', updates: 'item', invalidates: '/api/items' }`, status `r?.status === 'loading' ? 'Loading…' : r?.refreshing ? 'Updating…' : ''`.
+- In a hidden Switchable page, resources and `connections` pause (fetches abort, sockets close) and resume on show; an entry with `background: true` (`{ url, background: true }`, `{ socket, background: true }`) stays live.
+### Router (makeRouter + route) and HEAD
+```jsx
+// src/routes.js: one module the views import
+import { makeRouter } from 'sygnal'
+export const router = makeRouter({ routes: { home: '/', task: '/tasks/:id', admin: '/admin', notFound: '*' } })  // first match wins
+export const { href } = router   // href('task', { id: 2 }, { tab: 'notes' }) → '/tasks/2?tab=notes'
+```
+```jsx
+// src/App.jsx; main.js: run(App, { ROUTER: router.driver, HEAD: makeHeadDriver({ titleTemplate: '%s · Tasks' }) })
+import { ABORT, Switchable } from 'sygnal'
+import { router, href } from './routes.js'
+function App({ state }) {
+  return <main><nav><a href={href('home')}>All</a></nav><Switchable of={{ home: Home, task: TaskPage, admin: Admin, notFound: NotFound }} current={state.route.name} instance={state.route.path} /></main>
+}
+App.route = 'ROUTE'                                    // ROUTE gets { name, params, query, hash, path } on start and every change
+App.initialState = { route: router.current(), user: null, draft: '', leaving: null }   // seeded: the first paint shows the right page
+App.head = (state) => ({ title: state.route.name === 'task' ? `Task ${state.route.params.id}` : 'Tasks' })   // { title, meta, link }
+App.model = {
+  ROUTE: {                                             // a guard: refuse the route and redirect
+    STATE:  (state, route) => (route.name === 'admin' && !state.user ? ABORT : { ...state, route, draft: '', leaving: null }),
+    ROUTER: (state, route) => (route.name === 'admin' && !state.user ? { to: 'home', replace: true } : ABORT),
+  },
+}
+TaskPage.model = {   // a page shares the parent's state: no initialState (SYG405)
+  EDIT:  { STATE: (state, draft) => ({ ...state, draft }), ROUTER: () => ({ block: 'CONFIRM_LEAVE' }) },   // unsaved changes
+  CONFIRM_LEAVE: (state, { proceed }) => ({ ...state, leaving: proceed }),   // a blocked attempt: { to, route, proceed }
+  LEAVE: { STATE: (state) => ({ ...state, leaving: null }), ROUTER: (state) => ({ ...state.leaving, block: false }) },
+  DONE:  { ROUTER: () => ({ to: 'home', block: false }) },
+}
+```
+- Links are plain `<a href={href(...)}>`, never click handlers: the driver intercepts same-origin left clicks at the document (not modified clicks, `target`, `download`, `rel="external"`, `data-router-ignore`, other origins). `params` and `query` values are strings; `href()` is typed from the route table (an unknown name or a missing param is a type error; SYG130/SYG131 at run time). `instance={state.route.path}` re-creates the page for `/tasks/1` → `/tasks/2`. Pages derive `resources` from `state.route.params`.
+- ROUTER commands: `{ to, params, query, hash, replace, scroll }`, `{ url }`, `{ back: true }`, `{ forward: true }`, `{ go: n }`, `{ block: 'ACTION' | false }` (also stops back/forward; `proceed` navigates anyway), `{ prefetch: 'task', params }` (calls `makeRouter({ prefetch })`). `route` is reserved for the declaration. A bad command is SYG620. The first declarer (the root) gets each route first, so keep guards there.
+- Options: `makeRouter({ routes, base: '/app', mode: 'hash', scroll, focus })`. SSR: `router.current(req.url)` in the seeded state; `renderToString(App, { head: list })` + `renderHead(list)`. Vike: `makeRouter({ routes, navigate })` with `navigate` from `'vike/client/router'`, registered in `pages/+drivers.js`. HEAD: a later-mounted component's title wins; `meta`/`link` merge; a model entry can also send `HEAD: (state, data) => ({ title })`. Guides: https://sygnal.js.org/guide/router/, https://sygnal.js.org/guide/head/
+
+## 4. API facts
+- **Child props**: `<Rating name="food" value={state.food} />` → `function Rating({ state, name, value })`; reducers read `props.name` (4th arg); intent gets the `props$` stream. Reserved: `state` (lens: `"key"` or `{ get, set }`), `children`, `slots`, `context`, `uid` (SYG106; an error in strict mode). Without `state=` a child shares its parent's whole state. A child rendered by tag (`<Stopwatch state="stopwatch" />`) has no `initialState`: its start values go in the parent's (`stopwatch: { ms: 0 }`); its own throws SYG405 and the parent renders its error fallback (a test rendering the child as the root doesn't show it). Test a child alone with `renderComponent(Child, { initialState, context: { lang: 'fr' } })` (the ancestors' context). `uid(name?)` (a view prop, also on reducers' `props`) is a stable per-instance id for `id`/`for`/`aria-*` pairs: `<label for={uid('email')}>`, `<input id={uid('email')} />`.
+- **A sliced child with its own start values**: `Editor.isolatedState = true` lets `<Editor state="draft" />` keep an `initialState`, used only while `state.draft` is `undefined` (an existing slice is kept; SYG425 warns when it lacks keys the `initialState` has). To start it from its `initialState` on every mount: `<Editor state="draft" resetState />`.
+- **CHILD.select(Comp)** emits exactly what the child's `PARENT` function returned, for every instance (Collection items too). Put an id in the payload.
+- **Extract a component without changing markup**: snapshot `t.html()` on the unchanged code first; move the elements verbatim into the child (a component adds no wrapper element and no attributes, so the HTML stays identical); props in, `PARENT` out; the parent drops its old selectors and uses `CHILD.select(Child)`; the snapshot must still match. Recipe: https://sygnal.js.org/guide/parent-child/#recipe-extract-a-component-without-changing-the-markup
+- **run(App, drivers = {}, { mountPoint = '#root', diagnostics, onError })** returns `{ sources, sinks, dispose, hmr }`. `onError: (error, { componentName, action, phase }) => …` reports every error to a tracker (reporting only; a component's `.onError` still picks the fallback). Phase `'patch'`: a DOM patch threw, the app's DOM stops updating and the mount point gets `data-sygnal-error="patch"` (show a reload banner). DOM, EVENTS, LOG and STATE are built in. `app.sources.STATE.stream` is the state stream; `app.dispose()` fires DISPOSE.
+- **ABORT**: from a STATE reducer, the state is unchanged (returning the identical `state` object also is: no emission, no render; except for an action triggered by an `input`/`change` event, which re-renders so a refused controlled field shows the state's value again); from any other sink, nothing is sent.
+- **React to a state change** (save a draft, reload when a filter changes): `SAVE: STATE.watch(state => state.text).compose(debounce(1000))` in intent emits the selected value each time it changes (compared structurally; `{ immediate: true }` emits the current one first; a Collection item watches its own state). Not `STATE.stream` + `dropRepeats()`.
+- **Shorthands**: `DOM.<event>('.sel')` = `DOM.select('.sel').events('<event>')` for every real DOM event name (`DOM.key`, `DOM.enter` never fire: SYG115). `blur`/`focus` don't bubble, but `DOM.blur('.field')` / `DOM.focus('.field')` work (listener on the element); for any field inside a container use the bubbling `DOM.focusout('.form')` / `DOM.focusin`. Escape anywhere: `DOM.keydown('document').key().filter(k => k === 'Escape')`. `preventDefault`: `DOM.select('form').events('submit', { preventDefault: true })`; a function picks the events: `DOM.select('document').events('keydown', { preventDefault: (e) => e.ctrlKey && e.key === 'z' })`. **Enriched streams** (chainable, optional mapper): `.value(fn?)` e.target.value; `.checked(fn?)` boolean; `.key(fn?)` e.key; `.target(fn?)`; `.data('id', Number)` reads `data-id` on the target or its nearest ancestor that has it (JSX: `data={{ id: 7 }}`). camelCase names map to kebab-case attributes: `.data('taskId')` reads `data-task-id` (`data={{ taskId }}`); a `data-task-id="1"` attribute works too, but a kebab key in the prop (`data={{ 'task-id': 1 }}`) throws a DOMException (SYG421).
+- **TypeScript**: `const intent = ({ DOM }: IntentSources<State>) => ({ ... })`, then `const C: Component<State, Props, {}, ActionsOf<typeof intent>, Calculated, Context, { PARENT: Payload }> = ({ state, context }) => ...` (root: `RootComponent<State, {}, Actions>`; unused parameters `{}`). Without `{ PARENT: Payload }` the parent's `CHILD.select(C)` is a `Stream<unknown>`. In JSX pass `state="slice"`, a lens, or nothing, plus the declared props. Register EVENTS names in `declare module 'sygnal' { interface SygnalEvents { DOC_SAVED: { id: string } } }` in a file that keeps `export {}` (without it the block replaces the 'sygnal' types: "has no exported member"): with an empty registry no event names are type-checked. Guide: https://sygnal.js.org/integration/typescript/
+- **xstream**: `xs.merge/combine/of/periodic/never/fromPromise`; methods `map mapTo filter startWith fold take drop last endWhen flatten compose remember replaceError debug`. From `'sygnal'`, used with `.compose(...)`: `debounce(ms) throttle(ms) delay(ms) dropRepeats() sampleCombine(other$) flattenConcurrently flattenSequentially`; plus `concat(a$, b$)`. **RxJS → xstream**: `pipe(a, b)` → chain `.a().b()` / `.compose(op)`; `switchMap(f)` → `.map(f).flatten()`; `mergeMap(f)` → `.map(f).compose(flattenConcurrently)`; `concatMap(f)` → `.map(f).compose(flattenSequentially)`; `debounceTime(ms)` → `.compose(debounce(ms))`; `throttleTime(ms)` → `.compose(throttle(ms))`; `distinctUntilChanged()` → `.compose(dropRepeats())`; `withLatestFrom(b$)` → `.compose(sampleCombine(b$))`; `combineLatest(a$, b$)` → `xs.combine(a$, b$)`; `merge` → `xs.merge`; `scan(f, seed)` → `.fold(f, seed)`; `skip(n)` / `first()` → `.drop(n)` / `.take(1)`; `takeUntil(b$)` → `.endWhen(b$)`; `tap(f)` → `.debug(f)`; `catchError(f)` → `.replaceError(f)`; `shareReplay(1)` → `.remember()`.
+- More (guides): View Transitions (`viewTransitions = ['MOVE']` + `makeViewTransitionDOMDriver`; `<Collection viewTransitionName="card" />` names each item `card-<id>`, so moves and reorders animate, also across Collections with the same prefix) https://sygnal.js.org/guide/view-transitions/; SSR: the first client render adopts the server's elements (focus and typed text kept) `node_modules/sygnal/dist/guide/ssr.md`; a component as a custom element (`defineElement`, `'sygnal/element'`) https://sygnal.js.org/reference/api/#sygnalelement; DevTools action log and "Copy as test" https://sygnal.js.org/integration/debugging/; app-level error reporting `node_modules/sygnal/dist/guide/error-boundaries.md`; Testing Library https://sygnal.js.org/integration/testing/#testing-with-testing-library; `controls()` element tokens, an alternative to class selectors https://sygnal.js.org/guide/controls/
+- Browser sources: `Card.browser = (state) => ({ seen: !state.seen && { intersection: '.cover', action: 'SEEN' }, dark: { media: '(prefers-color-scheme: dark)', action: 'DARK' } })` + `run(App, { BROWSER: makeBrowserDriver() })` (also `resize`, `storage`, `visibility`, `online`, `geolocation`; clipboard: `{ BROWSER: (s) => ({ copy: s.url, ok: 'COPIED', error: 'COPY_FAILED' }) }`; tests need no driver: `t.browser.intersect('.cover', true)`, `t.browser.media(query, true)`); `lazy(() => import('./Chart'), { when: 'visible' })` (or `'idle'`) defers the import. Guide: `node_modules/sygnal/dist/guide/browser-sources.md`
+- Long lists (from ~1,000 rows): `<VirtualCollection of={Row} from="rows" className="rows" estimateSize={32} aria-label="Rows" />` (Collection's props; it is itself the scroll container, a `div` with `role="list"`: give `.rows` a bounded height in CSS and put `className`, `role`, `aria-label` on it, never wrap it in your own scrolling `<ul>`; SYG430 means fix that height; only rows in view have components, so keep row state in the array); jump with `ELEMENT: (s, index) => ({ scrollToIndex: '.rows', index })` or `{ scrollToId: '.rows', id }`. Guide: `node_modules/sygnal/dist/guide/virtual-collections.md`
+- Reorderable list: `List.uses = { sort: sortable({ from: 'tasks', item: '.task', handle: '.grip' }) }` (mouse, touch, keyboard); items `<li className="task" data-id={state.id}><button className="grip" aria-label=… aria-describedby={context.sort.helpId}>` (context `sort: (s) => s.sort`; style from `context.sort.dragging` / `over` / `after`), host `<p id={state.sort.helpId} hidden>` instructions and `<p role="status" aria-live="assertive">{state.sort.message}</p>` (English defaults: "Dropped X at position 2 of 5.", "Reorder cancelled. X is back at position…"; a spec's exact wording: `messages: { lift, move, drop, cancel, stay }`, each `(label, position, count) => text`), save in `'sort.DROPPED': (state, { id, index, fromIndex }) => …` (the list is already reordered); two lists `from: ['todo', 'done']` + `data-list="todo"` on each container. HTML5 / file drops: `makeDragDriver`. Guide: `node_modules/sygnal/dist/guide/drag-and-drop.md`
+- UI parts (`import { dialog, popover, tooltip, tabs, tabsAttrs, accordion, accordionAttrs, disclosure, disclosureAttrs, Toaster } from 'sygnal/ui'`; native HTML, unstyled): behaviors over your own markup in `uses` (`Profile.uses = { profile: dialog({ dialog: '.profile', trigger: '.edit', close: '.cancel' }) }` → `state.profile.open`, `'profile.CLOSED'`; for tabs/accordion/disclosure spread `tabsAttrs(state.tabs, uid).tab('general')` etc. for roles, ids and ARIA), and `<Toaster />` once + `EVENTS: event('TOAST', { text, kind, timeoutMs })` from anywhere (needs `makeTimerDriver()`). Guides: `node_modules/sygnal/dist/guide/ui/overview.md` (and `ui/dialog.md`, `popover`, `tooltip`, `tabs`, `accordion`, `disclosure`, `toaster`)
+- Menu / Select / Combobox: `import { Select } from 'sygnal/ui/select'` (`sygnal/ui/menu`, `sygnal/ui/combobox`; each needs `@zag-js/vanilla` + its machine, e.g. `@zag-js/select@~1.45.0`): widget tags, `<Select className="size" label="Size" items={['S', 'M']} value={state.size} />` + `SIZE: DOM.select('.size').events('value-change').detail()` (Menu: `'select'`; Combobox also `'input-change'`), commands `{ open: '.size' }`. Escape hatch for one React/Preact component or a Zag machine: `fromReact(Comp, { events: { rate: 'onChange' } })` (`sygnal/react`) / `fromZag(menu, (api, props) => …, { events })` (`sygnal/zag`, `import * as menu from '@zag-js/menu'`) return widget tags; test them with `dom: 'real'`. Guides: `node_modules/sygnal/dist/guide/ui/menu.md` (`ui/select.md`, `ui/combobox.md`), `node_modules/sygnal/dist/guide/adapters.md`
+- Third-party libraries (tested recipes): charts (Chart.js, ECharts), rich text (Tiptap), code editor (CodeMirror), carousel (Embla), data grid (AG Grid) are `defineWidget` tags; TanStack Table v9 runs in the view as a pure function of state (`constructTable` per render, settings in state); icons: `lucide` data → SVG vnodes with a helper called in the view (`{icon(Plus)}`, not a component); i18n: i18next `getFixedT(locale)` once per locale in `App.context = { t }`, the locale in state saved with `persist()` (never `changeLanguage()`). Recipes: `node_modules/sygnal/dist/guide/recipes/overview.md` (and `recipes/charts.md`, `code-editor`, `rich-text`, `carousel`, `data-table`, `data-grid`, `icons`, `i18n`)
+
+## 5. Wiring rules (silent failures, and what catches them)
+- **Selectors are scoped to the component's own JSX.** A parent's `DOM.click('.remove')` never fires for `.remove` rendered by a child or a Collection item. Handle the event in the child and send it up with `PARENT` (read with `CHILD.select(Child)`) or `EVENTS`. Caught as SYG104; a selector the view never renders is SYG110. Events still bubble like in the browser: a listener on an element the parent rendered itself (`<div className="slot"><Child /></div>` with `DOM.click('.slot')`) hears clicks from inside the child, after the child's own listeners.
+- **Every intent action needs a model entry (SYG101), and every model entry needs a trigger (SYG102)**: an intent action, a built-in, or `next('X')`.
+- **EVENTS types must match exactly** between `event('X')` and `EVENTS.select('X')` (SYG105). `event()` is the sink entry itself: `EVENTS: () => event('X')` sends a function, which nothing receives (SYG116).
+- **Collection `from` must name an array field of the state** (SYG401). Over a calculated field it is read-only (item writes and removal are discarded): use `from="items"` with `sort=`/`filter=`.
+- **A controlled input needs an input listener**: `value={state.x}` plus `DOM.input('.x').value()`, otherwise a re-render resets the text (SYG111). `value={null}` clears the field; leaving `value` out makes it uncontrolled.
+- Also: reducers return the complete new state (`{ ...state, ... }`); never mutate (a mutated `state` returned as-is is ignored: SYG222); no side effects in views or STATE reducers (use EFFECT or a driver).
+
+## 6. Diagnostics
+- Format: `[Sygnal SYG104] Lane: <what is wrong>. <how to fix> https://sygnal.js.org/reference/errors#syg104`. Severities error/warn/info. 1xx wiring, 2xx model/state, 3xx streams (SYG301: RxJS operator on an xstream stream), 4xx components (Collection, Switchable, context), 5xx strict, 6xx drivers and setup, 7xx accessibility (static, in `sygnal-check` and the Vite dev checker: a clicked `div`, a form field without a label, `<img>` without `alt`, a button with no name; warn, also under `--strict`; `--a11y=error` makes them errors), 9xx internal.
+- `npx --no-install sygnal-check` runs the locally installed checker, never a download (a `create-sygnal-app` project already has the `sygnal-check` dev dependency; elsewhere `npm i -D sygnal-check`; still not installed? skip it and rely on the runtime diagnostics in the tests). It checks `src` statically; pass other paths instead, e.g. `npx --no-install sygnal-check pages --strict` (Vike). Use `--strict` for canonical forms, `--fix` to apply the mechanical rewrites (implies `--strict`), and `--json` / `--verbose` for output. `npx --no-install sygnal-check explain SYG104` explains a code and its fix. Suppress one line with `// sygnal-ignore SYG110`.
+- App graph: `npx --no-install sygnal-check --graph --json` (static), `t.inspect()` (test), `getDevTools()?.inspect()` (running dev app with `sygnal/devtools`, injected by `sygnal/vite`). All return the same `InspectGraph`: components, actions and their triggers, selectors (`matched`, `isolationHit`), EVENTS emitters/selectors, diagnostics.
+- Vite plugin in dev (`vite`, never `vite build`): runtime checks print warnings to the console; when `sygnal-check` is installed, the plugin also runs it on start and on every save (terminal + browser console). Stricter: `sygnal({ diagnostics: { mode: 'error', strict: true }, check: { strict: true } })`.
+- Without the plugin: `run(App, drivers, { diagnostics: 'warn' })` (`'collect'` → `getDiagnostics()`; `'error'` throws) and `import 'sygnal/diagnostics'` for the full checks. Runtime strict: `run(App, drivers, { diagnostics: { strict: true } })`, `configureStrict(true)` from `'sygnal/diagnostics'`, or `renderComponent(C, { strict: true })` (all need `'sygnal/diagnostics'`).
+
+## 7. Testing your change
+```js
+import { it, expect, afterEach } from 'vitest'
+import { renderComponent } from 'sygnal'
+import TaskList from './TaskList.jsx'
+let t
+afterEach(() => t?.dispose())
+it('picks, then removes a task', async () => {
+  t = renderComponent(TaskList, { strict: true })   // also: initialState, context, drivers, mockConfig, diagnostics, timeoutMs, settleMs, eventWaitMs
+  t.simulateEvent('.pick', 'click')                 // first match; bubbles; reaches child components too
+  await t.next(s => s.picked === 1)                 // a state emitted after this call
+  t.simulateEvent('.task[data-id="2"] .remove', 'click')
+  await t.next(s => s.tasks.length === 1)
+  await t.settle()                                  // nothing pending anywhere in the tree
+  expect(t.html()).not.toContain('Test')
+  t.expectNoDiagnostics()                           // throws on any warn/error diagnostic
+})
+```
+- `simulateEvent(sel, type, init?)`: init `{ value }`, `{ checked }`, `{ key: 'Enter' }`, `{ data: { id: 2 } }`; `'document'` targets `DOM.select('document')` listeners. Calls made before the component is ready are buffered (`await t.ready()` is optional). `sel` matches the rendered tree like the real DOM: tag, `.class`, `#id`, `[attr="v"]`, `:first-child`, `:last-child`, `:nth-child(n)`, `:nth-of-type(n)`, `:not()`, descendant and `>` (e.g. `.list:nth-child(2) .card:first-child .next`). If it matches nothing (after waiting up to 300ms for a render), the test fails with an error naming the selector (check `t.html()`, or select by attribute: `[data-id="3"]`); `{ allowMissing: true }` drops the event instead. `:has()`, `+`, `~` throw "unsupported selector syntax". `sel` is always a selector string, never an element (`t.query()` returns snapshots: select by attribute, `'.remove[data-id="2"]'`).
+- `t.next(pred)` matches only future states (right after `await t.ready()`, also those of the buffered calls). `t.waitForState(pred)` also matches states already recorded (e.g. the initial one), so use it only for a state that can't already exist. Both resolve after the whole tree has rendered. `await t.respond(…)` / `t.fail(…)` / `t.settle()` resolve once the state is there: assert on `t.state` next; a `t.next(pred)` after them waits for a further state and times out ("a state recorded before this next() call already matches"). `t.settle()` doesn't wait out a model `next('X', data, ms)` longer than its 20ms window: `await t.next(pred)` instead (timeout errors name the pending `next()`). `t.state` is the latest state (`t.states.at(-1)`), with current calculated fields (also after a child or Collection item writes); `t.states`, `t.emitted` (EVENTS sent) and `t.sinkValues('PARENT')` / `t.sinkValues('API')` (any sink, children's too) are live arrays. `t.html()` is serialised like `innerHTML` (text `Couldn't`, not `&#39;`) and throws before the first render: `await t.ready()` (or a `t.next`) first. Timer tests (debounce/delay): `vi.useFakeTimers()` before `renderComponent`, then `await t.ready()`; `await vi.advanceTimersByTimeAsync(ms)` moves time (e.g. 299 ms: nothing sent yet), and `t.next`/`t.waitForState`/`t.settle`/`t.ready` advance the fake clock themselves until they resolve, so no real waiting. Use it instead of sleeping out a real debounce. `vi.useRealTimers()` in `afterEach`.
+- `t.actions` logs every action of the tree, `{ type, data, component, instance, sinks, cause, at }` (`cause`: `'intent' | 'next' | 'reply' | 'built-in' | 'simulateAction' | 'behavior'`; `sinks`: those that produced a value): when "nothing happened", it shows whether the action ran and what it produced. `t.explain(s => s.count === 5)` returns the action that produced a state.
+- `t.simulateAction('LOADED', data)` pushes an action straight into intent → model (all sinks run). Use it for actions without a DOM trigger. **Drivers need no wiring in tests**: the HTTP fake is the real `makeFetchDriver` over an in-memory fetch, so every request stays pending until the test answers it. `t.requests('HTTP')` lists the requests as objects (a string URL is `{ url }`; never `{ abort }`/`{ refresh }`/`{ resources }` values). `await t.respond('HTTP', body, 'RESULTS')` delivers `body` as that request's `ok` action and resolves once it is reduced and rendered; `await t.fail('HTTP', 404 | error, target?)` sends `{ error, status, body, request }` to its `error` action. Target: an action or key name, a resource name, a URL, a partial request (`{ url: '/items/2' }`), or a predicate; none = the newest pending. A request superseded by `latest: true`, aborted or already answered isn't pending, and answering it **throws at the call**: `expect(() => t.respond('HTTP', {}, { query: { q: 'du' } })).toThrow()`. Identical requests (a resource refetch, a second click) match the same targets: `{ nth: 0 }` answers exactly `t.requests('HTTP')[0]` (`-1` the newest; with `request`, counting only its matches), and throws if it isn't pending. A call made while earlier input is still queued (a debounce) waits up to 1s for its request instead. Each send is its own request. The fake can't see `makeFetchDriver({ latest: true })` from main.js: write `latest: true` on the request.
+- Sockets need no driver either: a component with `connections` gets a fake `WS` sink running the real driver on in-memory sockets (`{ socketSink: 'SOCKET' }` for another name). Connections open by themselves; `renderComponent(C, { autoConnect: false })` holds them in `'connecting'` until `await t.open('WS')`. `await t.push('WS', { text: 'hi' })` is a server frame (SSE named event: `t.push('WS', data, { event: 'price-update' })`); `await t.drop('WS', { code: 1011 })` is a close the app didn't make (`close` fires, the retry runs on the test's timers: `await vi.advanceTimersByTimeAsync(1000)`); `t.sent('WS')` lists the `{ to, json }` values; `t.connections('WS')` the declared connections (`name`, `url`, `state`). They throw too when nothing matches.
+- Resources: each fetch is listed as `{ url, ...request, resource: 'quote' }` and answered by resource name, URL or partial request: `await t.respond('HTTP', { text: 'Hi' }, 'quote')`, `await t.fail('HTTP', 500, 'quote')`. A resource request is sent after the state changes; `t.respond` by resource name right after the `simulate*` call that changes it waits for that fetch. Cache: `renderComponent(C, { http: { cache: queryCache({ staleTime: 2000 }) } })` (any driver options); `t.cache('HTTP')` lists `{ key, age, stale, subscribers, data, tags }`; `t.focus()` / `t.online()` fire the refetch triggers; retries and `refetchEvery` run on the test's timers.
+- Router: `renderComponent(App, { router, url: '/tasks/2' })` runs the router's real driver over an in-memory history (a component that declares `route` needs the `router` option). `await t.navigate('/admin')` (as a link click) or `await t.navigate({ to: 'task', params: { id: 1 } })`, `await t.back()` / `t.forward()`, `t.location` (`{ path, search, hash, href }`), `t.sent('ROUTER')` (the commands, not the declarations); a `simulateEvent` click on an `<a>` goes through the router's link handling; `{ block }` stops all of them. HEAD: `t.head()` returns the merged `{ title, meta, link }` (`{ titleTemplate }` option).
+- TypeScript tests: `renderComponent` infers the state type; for a handle assigned in `beforeEach`, declare `let t: RenderResult<State>` (import the type from `'sygnal'`), not `any`. With the Vite plugin, Vitest gets `sygnal/diagnostics` in its setupFiles automatically; otherwise `import 'sygnal/diagnostics'` in the test.
+- Real DOM (state the user typed or clicked, focus, refs, any CSS selector): `renderComponent(C, { dom: 'real' })` (`'real'`, not `'jsdom'`) in a jsdom test (`// @vitest-environment jsdom`, `npm i -D jsdom`), same `t.*` API in ONE suite (no separate `run()` + jsdom suite). `simulateEvent` then dispatches real events on any CSS selector (`{ value }` types, `'click'` toggles a checkbox/radio and skips disabled buttons, `'focus'`/`'blur'` move focus).
+- Assert on elements: `t.query(sel)` / `t.queryAll(sel)` also work on the default mock DOM, as read-only snapshots of what the view rendered (`textContent`, `value`, `checked`, `disabled`, `getAttribute`, `classList`, `dataset`, `querySelector`, `closest`; `focus()` throws): `expect(t.query('input[name="plan"]:checked').value).toBe('team')`, `t.query('.save').disabled`, `t.queryAll('.row')`; with `dom: 'real'` they are real elements (`document.activeElement === t.query('input[name="city"]')`). Every wait (`ready`, `next`, `waitForState`, `settle`) resolves once its state is rendered, so query right after the `await` (before the first render, `t.query` throws: `await t.ready()`). `await t.next(a); await t.next(b)` also sees a `b` that arrived while the DOM showed `a`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sygnal",
-  "version": "5.3.7",
+  "version": "6.0.0",
   "description": "An intuitive framework for building fast and small components or applications based on Cycle.js",
   "main": "./dist/index.cjs.js",
   "types": "./dist/index.d.ts",
@@ -26,6 +26,52 @@
       "import": "./dist/jsx-dev-runtime.esm.js",
       "require": "./dist/jsx-dev-runtime.cjs.js"
     },
+    "./diagnostics": {
+      "types": "./src/extra/diagnostics/checks/public.d.ts",
+      "import": "./dist/diagnostics.esm.js",
+      "require": "./dist/diagnostics.cjs.js"
+    },
+    "./devtools": {
+      "types": "./src/devtools.d.ts",
+      "import": "./dist/devtools.esm.js",
+      "require": "./dist/devtools.cjs.js"
+    },
+    "./element": {
+      "types": "./src/element.d.ts",
+      "import": "./dist/element.esm.js",
+      "require": "./dist/element.cjs.js"
+    },
+    "./ui": {
+      "types": "./src/ui.d.ts",
+      "import": "./dist/ui.esm.js",
+      "require": "./dist/ui.cjs.js"
+    },
+    "./ui/menu": {
+      "types": "./src/ui-menu.d.ts",
+      "import": "./dist/ui-menu.esm.js",
+      "require": "./dist/ui-menu.cjs.js"
+    },
+    "./ui/select": {
+      "types": "./src/ui-select.d.ts",
+      "import": "./dist/ui-select.esm.js",
+      "require": "./dist/ui-select.cjs.js"
+    },
+    "./ui/combobox": {
+      "types": "./src/ui-combobox.d.ts",
+      "import": "./dist/ui-combobox.esm.js",
+      "require": "./dist/ui-combobox.cjs.js"
+    },
+    "./zag": {
+      "types": "./src/zag.d.ts",
+      "import": "./dist/zag.esm.js",
+      "require": "./dist/zag.cjs.js"
+    },
+    "./react": {
+      "types": "./src/react.d.ts",
+      "import": "./dist/react.esm.js",
+      "require": "./dist/react.cjs.js"
+    },
+    "./shims/globalthis": "./dist/shims/globalthis.cjs",
     "./vite": {
       "types": "./src/vite/plugin.d.ts",
       "import": "./dist/vite/plugin.mjs",
@@ -48,18 +94,15 @@
     },
     "./vike": {
       "types": "./src/vike/types.ts",
-      "import": "./dist/vike/+config.js",
-      "require": "./dist/vike/+config.cjs.js"
+      "default": "./dist/vike/config/+config.js"
     },
     "./vike/config": {
       "types": "./src/vike/types.ts",
-      "import": "./dist/vike/+config.js",
-      "require": "./dist/vike/+config.cjs.js"
+      "default": "./dist/vike/config/+config.js"
     },
     "./config": {
       "types": "./src/vike/types.ts",
-      "import": "./dist/vike/+config.js",
-      "require": "./dist/vike/+config.cjs.js"
+      "default": "./dist/vike/config/+config.js"
     },
     "./vike/onRenderHtml": {
       "import": "./dist/vike/onRenderHtml.mjs",
@@ -80,25 +123,32 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "llms.txt",
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "vitest run && npm run test:types && npm run test:browser",
-    "test:types": "npx tsc --project type-tests/tsconfig.json 2>&1 | grep '^type-tests/' && exit 1 || exit 0",
+    "test": "vitest run && npm run test:examples && npm run test:types && npm run test:browser && npm run test:perf-gate",
+    "test:perf-gate": "node scripts/perf-gate.mjs",
+    "test:examples": "node scripts/test-examples.mjs",
+    "test:recipes": "node scripts/test-recipes.mjs",
+    "test:types": "npx tsc --project tsconfig.json --noEmit && npx tsc --project type-tests/tsconfig.json",
     "test:browser": "npm test --prefix browser-tests",
     "test:watch": "vitest",
-    "build": "npx rollup -c && cp src/index.d.ts dist/index.d.ts",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && npx rollup -c && npx rollup -c rollup.config.dts.mjs && node scripts/copy-guides.mjs",
     "build:types": "npx rollup -c rollup.config.dts.mjs",
-    "build:all": "npm run build && npm run build:types",
+    "build:all": "npm run build",
     "build:devtools": "node devtools/build.mjs",
-    "start": "npx rollup -c -w"
+    "start": "npx rollup -c -w",
+    "prepublishOnly": "npm run build:all"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tpresley/sygnal.git"
   },
   "engines": {
-    "node": ">=12.0.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "keywords": [
     "cycle",
@@ -114,19 +164,62 @@
   },
   "homepage": "https://github.com/tpresley/sygnal#readme",
   "dependencies": {
-    "extend": "^3.0.2",
+    "@tanstack/virtual-core": "^3.17.11",
     "snabbdom": "^3.6.3",
     "xstream": "^11.14.0"
   },
+  "peerDependencies": {
+    "@zag-js/combobox": "~1.45.0",
+    "@zag-js/menu": "~1.45.0",
+    "@zag-js/select": "~1.45.0",
+    "@zag-js/vanilla": "~1.45.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@zag-js/combobox": {
+      "optional": true
+    },
+    "@zag-js/menu": {
+      "optional": true
+    },
+    "@zag-js/select": {
+      "optional": true
+    },
+    "@zag-js/vanilla": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.4",
     "@rollup/plugin-node-resolve": "^15.2.1",
     "@rollup/plugin-terser": "^0.4.3",
     "@rollup/plugin-typescript": "^11.1.6",
+    "@zag-js/combobox": "1.45.0",
+    "@zag-js/dialog": "1.45.0",
+    "@zag-js/menu": "1.45.0",
+    "@zag-js/select": "1.45.0",
+    "@zag-js/vanilla": "1.45.0",
+    "flatpickr": "4.6.13",
+    "jsdom": "^29.1.1",
+    "preact": "11.0.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "rollup": "^3.28.1",
     "rollup-plugin-dts": "^6.1.1",
     "tslib": "^2.6.2",
     "typescript": "^5.4.5",
-    "vitest": "^4.0.18"
+    "valibot": "^1.5.0",
+    "vitest": "^4.0.18",
+    "zod": "^4.6.5"
+  },
+  "overrides": {
+    "vite": "^7.3.6"
   }
 }