sygnal 5.3.7 → 6.0.0

package/dist/guide/behaviors.md

@@ -0,0 +1,312 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Behaviors
+
+A **behavior** is a piece of state, intent and model that several components share: a pager, a selection, an undo history, a disclosure. A component lists the behaviors it uses in its `uses` static, each under a state key. The behavior then runs on that slice of the component's state, and its actions are named after the key (`pager.NEXT`).
+
+Sygnal ships four behaviors: [`pager`](#pager), [`selection`](#selection), [`undo`](./undo.md) and [`form`](./forms.md). You write your own with [`defineBehavior`](#writing-a-behavior). The [UI parts](./ui/overview.md) in `sygnal/ui` (dialog, popover, tooltip, tabs, accordion, disclosure) are behaviors too.
+
+## Using a behavior
+
+`uses` maps a state key to a behavior, called with its options:
+
+```jsx
+TaskList.uses = { pager: pager({ pageSize: 10, next: '.newer', prev: '.older' }) }
+```
+
+This gives the component:
+
+- **state** at `state.pager`: the behavior's own state (`{ page, pageSize, total }`), with its calculated fields (`offset`, `pages`, `hasPrev`, `hasNext`) stored on the slice;
+- **actions** `pager.NEXT`, `pager.PREV`, `pager.GOTO` and `pager.SET_TOTAL`, which change only `state.pager`;
+- **triggers**: the behavior's intent listens to what its options name. Here a click on the `Newer` button dispatches `pager.NEXT`.
+
+The options that tell a behavior what to listen to take a CSS selector: `next: '.newer'` listens to clicks on the view's `<button className="newer">`. They take a [control](https://sygnal.js.org/guide/controls/) too.
+
+Options that name a key of the behavior's state (`pageSize` here) set its starting value.
+
+### Pager
+
+A page cursor over a list. The view slices the list with the calculated `offset`, and the buttons disable at the ends. In this demo, a stand-in server returns 23 tasks:
+
+```js live-server
+const tasks = Array.from({ length: 23 }, (_, i) => ({ id: i + 1, title: `Task ${i + 1}` }))
+
+export default {
+  'GET /api/tasks': () => ({ json: tasks }),
+}
+```
+
+```jsx live
+import { pager } from 'sygnal'
+
+export function TaskList({ state }) {
+  const { offset, pageSize, page, pages, hasPrev, hasNext } = state.pager
+  return (
+    <div>
+      <ul>
+        {state.tasks.slice(offset, offset + pageSize).map(task => <li>{task.title}</li>)}
+      </ul>
+      <nav>
+        <button className="older" disabled={!hasPrev}>Older</button>
+        <span className="page">Page {page + 1} of {pages}</span>
+        <button className="newer" disabled={!hasNext}>Newer</button>
+      </nav>
+    </div>
+  )
+}
+
+TaskList.initialState = { tasks: [] }
+TaskList.uses = { pager: pager({ pageSize: 10, next: '.newer', prev: '.older' }) }
+TaskList.model = {
+  BOOTSTRAP: { HTTP: () => ({ url: '/api/tasks', ok: 'LOADED' }) },
+  LOADED: (state, tasks) => ({ ...state, tasks, pager: { ...state.pager, total: tasks.length } }),
+}
+```
+
+| | |
+|---|---|
+| Options | `pageSize` (20), `page` (0), `total` (`null`: unknown), `next` and `prev` (what to listen to for clicks) |
+| State | `page`, `pageSize`, `total`; calculated `offset`, `pages` (`null` while `total` is unknown), `hasPrev`, `hasNext` |
+| Actions | `NEXT`, `PREV` (no change at the first and last page), `GOTO` (a page number, kept in range), `SET_TOTAL` (the item count) |
+
+Without a `total`, `NEXT` has no upper bound. Set it with an option, with `pager.SET_TOTAL`, or, as the `LOADED` reducer above does, by writing `state.pager.total` from a host reducer: the calculated fields follow.
+
+### Selection
+
+Single or multiple selection over a list, with a select-all toggle:
+
+```jsx live
+import { selection, isSelected } from 'sygnal'
+
+export function Inbox({ state }) {
+  const { count } = state.sel
+  return (
+    <div>
+      <label>
+        <input className="pick-all" type="checkbox" checked={count > 0 && count === state.mails.length} /> Select all
+      </label>
+      <button className="archive" disabled={count === 0}>Archive ({count})</button>
+      <ul>
+        {state.mails.map(mail => (
+          <li>
+            <label>
+              <input className="pick" type="checkbox" data-id={mail.id} checked={isSelected(state.sel, mail.id)} /> {mail.subject}
+            </label>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+Inbox.initialState = {
+  mails: [{ id: 1, subject: 'Lunch?' }, { id: 2, subject: 'Invoice' }, { id: 3, subject: 'Re: plans' }],
+}
+Inbox.uses = { sel: selection({ multi: true, item: '.pick', all: '.pick-all', from: 'mails' }) }
+Inbox.intent = ({ DOM }) => ({ ARCHIVE: DOM.click('.archive') })
+Inbox.model = {
+  ARCHIVE: (state) => ({
+    ...state,
+    mails: state.mails.filter(mail => !isSelected(state.sel, mail.id)),
+    sel: { ...state.sel, selected: [] },
+  }),
+}
+```
+
+| | |
+|---|---|
+| Options | `multi` (false: a click replaces the selection; true: it toggles the item), `item` (a selector for the element on each item), `attr` (the item element's attribute that holds its id, default `data-id`), `all` (a select-all toggle), `clear`, `from` (the host state key of the list, for select-all), `idField` (`'id'`) |
+| State | `selected` (the ids, as strings, in selection order); calculated `count` |
+| Actions | `SELECT` (an id, or a click on an item), `SELECT_ALL` (an array of ids, or every id of `state[from]`), `TOGGLE_ALL` (all selected → none, else all), `CLEAR` |
+
+Read the selection with `isSelected(state.sel, id)`. Ids compare as strings, so `isSelected(state.sel, 1)` and `isSelected(state.sel, '1')` agree.
+
+### Undo
+
+`undo({ key: 'doc' })` records the changes to `state.doc` and adds `history.UNDO` and `history.REDO`. See [Undo and Redo](./undo.md).
+
+### Sortable
+
+`sortable({ from: 'tasks', item: '.task', handle: '.grip' })` reorders `state.tasks` by mouse, touch and keyboard, announces each step in `state.sort.message` for a live region, and dispatches `sort.DROPPED` once per completed move. See [Drag and Drop](./drag-and-drop.md#sortable-lists).
+
+### Form
+
+`form(schema, { values, submit })` is a form with validation: `state.form` holds the values, errors and touched fields, the fields inside the form element are matched by `name`, and a valid submit dispatches the `submit` action with the validated values. See [Forms](./forms.md).
+
+## Writing a behavior
+
+`defineBehavior()` takes the same parts as a component, without a view: `initialState`, `intent`, `model`, `calculated` and `timers`. It returns a factory: call it with the options of one use.
+
+```js live-file=./behaviors/disclosure.js
+// behaviors/disclosure.js
+import { ABORT, defineBehavior } from 'sygnal'
+
+export const disclosure = defineBehavior({
+  initialState: { open: false },
+  intent: ({ DOM }, { toggle }) => ({ TOGGLE: DOM.click(toggle) }),
+  model: {
+    TOGGLE: (slice) => ({ ...slice, open: !slice.open }),
+    CLOSE:  (slice) => (slice.open ? { ...slice, open: false } : ABORT),
+  },
+  calculated: {
+    label: (slice) => (slice.open ? 'Hide details' : 'Show details'),
+  },
+})
+```
+
+- `initialState` is the slice a host starts with.
+- `intent` receives the host's sources (its DOM, `STATE`, `EVENTS`, `CHILD` and drivers) and the options. Name the actions without the key: the host sees `TOGGLE` as `more.TOGGLE` when it uses the behavior under `more`.
+- The `model` reducers receive the slice, not the host's state, and return the new slice. `ABORT` (or the slice itself) means no change. `next('CLOSE')` inside the behavior names its own action.
+- `calculated` fields are computed on the slice and stored on it (`state.more.label`).
+- A behavior's entries can use every sink a component can: `EVENTS`, `PARENT`, `EFFECT`, drivers.
+
+A host uses it like a first-party behavior:
+
+```jsx live
+// Product.jsx
+import { disclosure } from './behaviors/disclosure.js'
+
+export function Product({ state }) {
+  return (
+    <section>
+      <h2>{state.name}</h2>
+      <button className="toggle" aria-expanded={String(state.more.open)}>{state.more.label}</button>
+      {state.more.open && <p>{state.description}</p>}
+    </section>
+  )
+}
+
+Product.initialState = { name: 'Desk lamp', description: 'Warm light, three brightness levels.' }
+Product.uses = { more: disclosure({ toggle: '.toggle' }) }
+```
+
+`state.more` is `{ open: false, label: 'Show details' }` to begin with, and a click on the `.toggle` button dispatches `more.TOGGLE`. To start it open, pass the state key as an option: `disclosure({ toggle: '.toggle', open: true })`.
+
+Two components can use the same behavior, and so can every item of a [Collection](https://sygnal.js.org/guide/collections/): each instance gets its own slice. In a Collection item (or any child that gets its state from its parent), `state[key]` reads as the behavior's initial state until the first action writes it.
+
+### Options, the key, host state and timers
+
+Every model handler of a behavior gets the use's options and its key after the usual arguments: `(slice, data, next, props, options, key)`, and the intent gets `(sources, options, key)`. `props.state` is the host's whole state.
+
+Two more parts are for behaviors that reach past their slice:
+
+- **`HOST`**: a model entry `{ HOST: (state, data, next, props, options, key) => newState }` is a reducer on the host's whole state, for a behavior that edits a host field (reordering `state[options.from]`, say). `ABORT`, or the same state, means no change. An entry can have both: `STATE` runs first (on the slice), then `HOST` gets the whole state with that update applied; an `ABORT` from one keeps the other's change.
+- **`timers: (slice, options, key) => ({ name: spec })`** declares [timers](./timers.md) for the host, as the `timers` static does (the app needs `makeTimerDriver()`). The host sees them as `'<key>.<name>'`; a spec whose `action` names one of the behavior's actions is sent to that action (`'SHOW'` arrives as `'tip.SHOW'`), any other action name goes to the host as written. They run alongside the host's own `timers`.
+
+```js live-file=./behaviors/hoverDelay.js
+// behaviors/hoverDelay.js
+import { defineBehavior } from 'sygnal'
+
+export const hoverDelay = defineBehavior({
+  initialState: { pending: false, open: false },
+  intent: ({ DOM }, { target }) => ({ ENTER: DOM.mouseenter(target), LEAVE: DOM.mouseleave(target) }),
+  timers: (slice, { delay = 300 }) => ({ show: slice.pending && { after: delay, action: 'SHOW' } }),
+  model: {
+    ENTER: (slice) => ({ ...slice, pending: true }),
+    LEAVE: (slice) => ({ ...slice, pending: false, open: false }),
+    SHOW: (slice) => ({ ...slice, pending: false, open: true }),
+  },
+})
+```
+
+A host uses it with its own delay:
+
+```jsx live
+// Card.jsx
+import { hoverDelay } from './behaviors/hoverDelay.js'
+
+export function Card({ state }) {
+  return (
+    <div>
+      <button className="help">Help</button>
+      {state.tip.open && <p className="tip">Shown half a second after the pointer entered Help.</p>}
+    </div>
+  )
+}
+
+Card.uses = { tip: hoverDelay({ target: '.help', delay: 500 }) }
+```
+
+`state.tip.open` turns true half a second after the pointer enters `.help` (`tip.show` is the timer, `tip.SHOW` its action), and false when it leaves. A behavior that sends a driver request names its [reply actions](./http.md) with the key, so they reach its own model: `ok: key + '.LOADED'`.
+
+### Persisted state and undo steps
+
+Two markers say how a behavior's state relates to the app's data:
+
+- **`persist: false`**: the slice is UI state (an open menu, a drag in progress). A root's [`persist()`](./persistence.md) neither saves nor restores that `uses` key, whatever `pick` / `omit` say. This covers the root component's own `uses` only: the slice of a behavior on a sub-component or a Collection item is part of the data around it (`state.list.sort`, `state.lanes[0].sort`) and is saved with it. The behavior has to cope with a restored slice (sortable resets restored drag state when the host starts, and leaves the data as it is).
+- **`undoStep: ['DONE']`**: the actions that complete one undoable step. With the [`undo` behavior](./undo.md) on the same host, the behavior's other actions are steps of a gesture: their changes to the undo key aren't recorded, and `DONE` records the value from before the gesture as one entry. A gesture that ends without `DONE` (cancelled) records nothing, and so does one whose steps bring the value back to where it started: the same value, or an array or plain object with the same entries (compared one level deep, by identity; return the earlier entry objects, not copies, when a step puts them back). The order of the two in `uses` doesn't matter. A recorded change, UNDO or REDO in the middle of a gesture first records the value from before it. Only the behavior that started a gesture completes it: another gesture behavior's `DONE` on the same host doesn't record it. With `track` naming none of the behavior's actions, its gestures aren't recorded.
+
+[`sortable`](./drag-and-drop.md) declares both: `persist: false`, and `undoStep: ['DROPPED']`, so one drag is one undo step. It also tells `undo` (internally) when a drag ends without a drop, so a cancelled drag never leaves a step pending.
+
+## Extending a behavior's actions
+
+The host can trigger a behavior action, and add its own entry for one. Both use the namespaced name:
+
+```jsx live
+// Faq.jsx
+import { ABORT } from 'sygnal'
+import { disclosure } from './behaviors/disclosure.js'
+
+export function Faq({ state }) {
+  return (
+    <section>
+      <button className="toggle" aria-expanded={String(state.answer.open)}>{state.answer.label}</button>
+      {state.answer.open && <p>{state.text}</p>}
+      <p className="opened">Opened {state.opened} times</p>
+    </section>
+  )
+}
+
+Faq.initialState = { text: 'Yes, returns are free for 30 days.', opened: 0 }
+Faq.uses = { answer: disclosure({ toggle: '.toggle' }) }
+Faq.intent = ({ DOM }) => ({
+  // a behavior action triggered by the host: Escape closes the answer
+  'answer.CLOSE': DOM.keydown('document').key().filter(key => key === 'Escape'),
+})
+Faq.model = {
+  // runs after the behavior's own TOGGLE, on the full state with its update applied
+  'answer.TOGGLE': (state) => (state.answer.open ? { ...state, opened: state.opened + 1 } : ABORT),
+}
+```
+
+The merge rules:
+
+| Host adds | Effect |
+|---|---|
+| An intent action with a behavior's name (`'answer.CLOSE'`) | Triggers that action. If the behavior has its own trigger for it, the host's replaces it (see [keyboard shortcuts for undo](./undo.md#keyboard-shortcuts)). |
+| A STATE reducer for a behavior action (`'answer.TOGGLE'`) | Runs after the behavior's, on the full state with the behavior's update applied. Its `ABORT` keeps that update. |
+| An `EFFECT` for a behavior action | Runs after the behavior's `EFFECT`. |
+| A value sink (`EVENTS`, `PARENT`, a driver) for a behavior action | Replaces the behavior's value for that sink. |
+| A reducer for another action that changes `state[key]` | The slice's calculated fields are recomputed. |
+
+A behavior's [reply actions](./http.md) (`ok: 'LOADED'` on a request it sends) arrive under the name it gives; to reach its own model, it names them with its key (`ok: key + '.LOADED'`, see above).
+
+## Testing
+
+`simulateAction` takes the namespaced name, and [`t.actions`](https://sygnal.js.org/integration/testing/#action-log-tactions-and-texplain) lists behavior actions under it. A click on a behavior's trigger has the cause `'behavior'`:
+
+```jsx
+import { expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Faq } from './Faq.jsx'
+
+const t = renderComponent(Faq)
+t.simulateAction('answer.TOGGLE')
+await t.next(s => s.answer.open)
+expect(t.state.opened).toBe(1)
+expect(t.actions.at(-1)).toMatchObject({ type: 'answer.TOGGLE', cause: 'simulateAction', component: 'Faq' })
+t.dispose()
+```
+
+## SYG127
+
+A `uses` entry that can't work is [SYG127](https://sygnal.js.org/reference/errors/#syg127), an error:
+
+- the host's `initialState` already has the key (`initialState = { pager: … }` with `uses = { pager: … }`): set the behavior's values through its options instead;
+- the value isn't a behavior: a plain object, or the factory without the call (`uses = { pager }` instead of `pager()`);
+- an option the behavior never reads, usually a typo (`pager({ nxt: '.newer' })`). Only `sygnal-check` reports this one.
+
+`sygnal-check` follows `uses` entries to their `defineBehavior()` call in the same file or a relative import, and knows the first-party behaviors (the `sygnal/ui` parts too: an option typo such as `dialog({ clse: '.close' })` is SYG127), so its other rules ([SYG101](https://sygnal.js.org/reference/errors/#syg101), [SYG102](https://sygnal.js.org/reference/errors/#syg102), …) see the behavior's actions too. A behavior imported from a package is not checked. The dev checks report SYG127 once per component definition.
+
+## TypeScript
+
+`UsesState<typeof uses>` is the state a `uses` object adds and `UsesActions<typeof uses>` its namespaced actions, for a component's state and action types: `type State = { tasks: Task[] } & UsesState<typeof uses>`.

package/dist/guide/browser-sources.md

@@ -0,0 +1,203 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Browser Sources
+
+A component declares what it wants to watch in the browser as a function of its state, and gets each change as one of its own actions. There is no observer to create or listener to remove: while the declaration is there the source runs, and when it goes away the source stops.
+
+```jsx
+Card.browser = (state) => ({
+  seen: !state.seen && { intersection: '.cover', action: 'SEEN' },
+  dark: { media: '(prefers-color-scheme: dark)', action: 'DARK' },
+})
+```
+
+It is the same shape as [`timers`](./timers.md): a function of the state that returns named specs, compared with the previous result by name.
+
+## Setup
+
+Browser sources are run by `makeBrowserDriver()`, which you register when you start the app:
+
+```jsx
+import { run, makeBrowserDriver } from 'sygnal'
+import App from './App.jsx'
+
+run(App, { BROWSER: makeBrowserDriver() })
+```
+
+The key is yours to choose (`BROWSER` by convention): Sygnal finds the driver by the `browser` static it takes. One driver serves every component of the app. A component that declares `browser` in an app without the driver gets [SYG643](https://sygnal.js.org/reference/errors/#syg643) in development.
+
+`makeBrowserDriver()` has every source. An app that uses only a few can list them, so the others add no bytes:
+
+```jsx
+import { run, makeBrowserDriverWith, intersectionSource, mediaSource } from 'sygnal'
+import App from './App.jsx'
+
+run(App, { BROWSER: makeBrowserDriverWith(intersectionSource, mediaSource) })
+```
+
+A spec whose source the driver wasn't made with is [SYG664](https://sygnal.js.org/reference/errors/#syg664) in development. The sources are `intersectionSource`, `resizeSource`, `mediaSource`, `storageSource`, `visibilitySource`, `onlineSource`, `geolocationSource` and `clipboardSource`.
+
+## The browser static
+
+`browser` takes the state (with its calculated fields) and returns an object of named specs, or a falsy value for "not now". One key of a spec names its source (a spec has exactly one of them), and `action` names the action each event is delivered as:
+
+| Spec | Watches | Action data |
+|---|---|---|
+| `{ intersection: '.cover', action }` | The elements the selector matches in this component's view entering or leaving the viewport (`IntersectionObserver`). `true` instead of a selector: the component's root element. Options: `threshold`, `rootMargin` | `{ visible, ratio, index, dataset }` |
+| `{ resize: '.chart', action }` | The size of those elements' content box (`ResizeObserver`); `true`: the root element | `{ width, height, index, dataset }` |
+| `{ media: '(min-width: 800px)', action }` | A media query | `{ matches, media }` |
+| `{ storage: 'theme', action }` | A `localStorage` key (`area: 'session'`: `sessionStorage`; `json: true`: the value parsed), including writes from other tabs | `{ key, value }` (`null` when absent) |
+| `{ visibility: true, action }` | Whether the page is visible (another tab, a minimized window) | `{ visible }` |
+| `{ online: true, action }` | Whether the browser is online | `{ online }` |
+| `{ geolocation: true, action, error }` | The device's position (`watchPosition`; permission-gated). `true`, or the position options `{ enableHighAccuracy, maximumAge, timeout }` | `{ latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed, timestamp }` |
+
+`index` and `dataset` say which element the event is about when the selector matches several (its position among them, and a copy of its `data-*` attributes). Sources with a current value (`media`, `storage`, `visibility`, `online`) send it when they start, so the state is right from the first render after it; `intersection` and `resize` send what their observer reports for each element when it starts observing it. Elements that the selector matches later (a list that grows) are observed after the render that adds them, and removed ones are let go.
+
+Sygnal compares the result with the previous one, name by name, whenever the state changes:
+
+- a new name starts its source;
+- a name that is gone, or now falsy, stops it;
+- a spec that changed (another selector, another query) restarts it;
+- a spec that is the same as before keeps running.
+
+So, as with timers, `browser` is a description: return what should be watched now. A "load more when the end of the list is visible" or "fade in once" component turns its spec off with its state:
+
+```jsx
+export function Photo({ state }) {
+  return <img className={state.seen ? 'photo shown' : 'photo'} src={state.src} alt={state.alt} />
+}
+
+Photo.initialState = { src: '/cat.jpg', alt: 'A cat', seen: false }
+// watched until it has been seen once
+Photo.browser = (state) => ({
+  seen: !state.seen && { intersection: true, action: 'SEEN', threshold: 0.25 },
+})
+Photo.model = {
+  SEEN: (state, { visible }) => visible ? { ...state, seen: true } : state,
+}
+```
+
+Each [Collection](https://sygnal.js.org/guide/collections/) item declares its own sources, so `intersection: true` in an item component watches that item.
+
+## Commands: the clipboard and storage writes
+
+Reading or writing the clipboard is something a user asks for, not something to watch, so it is a command: a model entry sends it to the driver's sink, and the answer comes back as a reply action. The method is its `copy`, `paste`, `setItem` or `removeItem` key (in any order with `ok` and `error`); a value the method can't take (a `json` value with a BigInt or a cycle) fails like a refusal, through `error`:
+
+| Command | Does | Reply |
+|---|---|---|
+| `{ copy: text, ok, error }` | Writes `text` to the clipboard | `ok`: `{ text }` |
+| `{ paste: true, ok, error }` | Reads the clipboard's text | `ok`: `{ text }` |
+| `{ setItem: key, value, area, json }` | Writes a storage key (`json: true` stores `value` as JSON); this page's `storage` declarations of that key see the change (a write of the value already stored is silent, so a model that writes back what it reads settles; `storage` listeners of your own on `window` hear only other tabs, as in the browser) | `ok`: `{ key }` |
+| `{ removeItem: key, area }` | Removes a storage key | `ok`: `{ key }` |
+
+```jsx live
+export function ShareLink({ state }) {
+  return (
+    <div className="share">
+      <input readOnly value={state.url} aria-label="Link" />
+      <button className="copy">{state.copied ? 'Copied' : 'Copy link'}</button>
+      {state.error ? <p role="alert">{state.error}</p> : null}
+    </div>
+  )
+}
+
+ShareLink.initialState = { url: 'https://example.com/p/42', copied: false, error: null }
+ShareLink.intent = ({ DOM }) => ({ COPY: DOM.click('.copy') })
+ShareLink.model = {
+  COPY: { BROWSER: (state) => ({ copy: state.url, ok: 'COPIED', error: 'COPY_FAILED' }) },
+  COPIED: (state) => ({ ...state, copied: true, error: null }),
+  COPY_FAILED: (state, { message }) => ({ ...state, error: message }),
+}
+```
+
+The browser only allows the clipboard in a secure context (HTTPS or localhost), and usually only during a user action such as a click: send the command from the action the click causes, as above. Reading needs the user's permission (some browsers ask, Safari shows a paste menu), so always name an `error` action for `paste`.
+
+## Permissions and failures
+
+`geolocation` and the clipboard are permission-gated: the first use may show a prompt, and the user may say no. A source or command that fails (permission denied, the API is missing, the position timed out, storage is blocked) sends its `error` action with `{ code, message }` (geolocation) or `{ name, message }` (clipboard, storage). Without an `error` action the failure is [SYG665](https://sygnal.js.org/reference/errors/#syg665) in development and nothing else happens, so name one whenever the user can refuse:
+
+```jsx
+export function NearMe({ state }) {
+  if (state.error) return <p role="alert">Location unavailable: {state.error}</p>
+  if (!state.position) return <p>Finding you…</p>
+  return <p className="where">{state.position.latitude.toFixed(3)}, {state.position.longitude.toFixed(3)}</p>
+}
+
+NearMe.initialState = { position: null, error: null }
+NearMe.browser = (state) => ({
+  here: !state.error && { geolocation: { enableHighAccuracy: true }, action: 'POSITION', error: 'NO_POSITION' },
+})
+NearMe.model = {
+  POSITION: (state, position) => ({ ...state, position }),
+  NO_POSITION: (state, { message }) => ({ ...state, error: message }),
+}
+```
+
+Ask for a permission-gated source when the user can see why, for example only after they press "Use my location" (declare it while `state.locating` is true).
+
+## Storage and persist()
+
+`storage` reads and observes a key that something else owns: another tab, another part of the app, a third-party script. To keep a component's own state across reloads, use [`persist()`](./persistence.md) instead: it restores the state before the first render, saves it as it changes, migrates old versions and syncs tabs.
+
+## Hidden pages
+
+A component on a hidden [Switchable](https://sygnal.js.org/guide/switchable/) page keeps its state, but its sources stop while the page is hidden, and start again (sending their current value) when it is shown. A source that should keep running says so:
+
+```jsx
+Inbox.browser = () => ({
+  // keeps following the network while another page is shown
+  net: { online: true, action: 'NETWORK', background: true },
+})
+```
+
+When a component is removed, its sources stop; when the app is disposed, all of them do. During `renderToString` no driver runs, so nothing is watched on the server.
+
+`onlineStatus$` (the [PWA helpers](https://sygnal.js.org/integration/pwa/)) is the same information as a stream for an intent. The `online` source is the declaration form: driven by state, paused on hidden pages, and faked by `renderComponent`.
+
+## Testing
+
+`renderComponent` provides a fake browser driver (no `drivers` option needed): the real driver, over sources that touch no browser API. `t.browser` drives it, and each call resolves once the actions it caused are reduced and the tree rendered:
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Photo } from './Photo.jsx'
+
+it('shows the photo once it is seen, then stops watching', async () => {
+  const t = renderComponent(Photo)
+  await t.ready()
+  expect(t.browser.active()).toEqual([{ name: 'seen', intersection: true, action: 'SEEN', threshold: 0.25, component: 'Photo' }])
+
+  await t.browser.intersect(true, true)
+  expect(t.state.seen).toBe(true)
+  expect(t.browser.active()).toEqual([])
+  t.dispose()
+})
+```
+
+| Call | Effect |
+|---|---|
+| `t.browser.intersect(target, visible, data?)` | The declarations of that `intersection` target hear `{ visible, ratio: 1 or 0, index: 0, dataset: {} }` merged with `data`; `{ at: n }` in `data` picks the n-th of them (start order, from 0), e.g. one Collection item. Throws when nothing declares it |
+| `t.browser.resize(target, { width, height })` | The same for `resize` |
+| `t.browser.media(query, matches)` | The query matches now (or not) |
+| `t.browser.storage(key, value, area?)` | Another tab writes the key (a non-string is stored as JSON; `null` removes it). With only a key: the stored string |
+| `t.browser.visibility(visible)`, `t.browser.online(online)` | The page is visible / the network is up (or not) |
+| `t.browser.geolocation(coords)` | A position (accuracy 0, the rest `null` unless given); `{ code, message }` instead: a failure |
+| `t.browser.clipboard(text?)` | The clipboard's text (with an argument: sets it) |
+| `t.browser.deny('geolocation', 'clipboard')` | Those permissions are refused from now on (a running geolocation declaration fails with code 1) |
+| `t.browser.active()` | The running declarations: `{ name, ...spec, component }` |
+
+As with the real observers, an `intersection` declaration hears `{ visible: false, ratio: 0, index: 0, dataset: {} }` when it starts and a `resize` one `{ width: 0, height: 0, index: 0, dataset: {} }`, so a model that counts reports must ignore a first "not visible". The fake doesn't look for the elements under the mock DOM; with `renderComponent(C, { dom: 'real' })` a selector that matches no element of the component after it renders is [SYG668](https://sygnal.js.org/reference/errors/#syg668).
+
+The `browser` option sets the environment at the start: `renderComponent(Theme, { browser: { media: { '(prefers-color-scheme: dark)': true }, storage: { theme: '"dark"' }, online: false, deny: ['geolocation'] } })`. By default no media query matches, storage is empty, the page is visible and online, and nothing is denied. The commands (`copy`, `paste`, `setItem`, `removeItem`) run against the fake too. If the test passes its own browser driver in `drivers`, the fake stands down and `t.browser` throws (`browserSink` renames the fake's sink).
+
+## Diagnostics
+
+| Code | When |
+|---|---|
+| [SYG663](https://sygnal.js.org/reference/errors/#syg663) (error) | A spec the driver can't start (no known source key, no `action`, an `intersection` / `resize` target that is neither a selector nor `true`), or a command with an unknown method |
+| [SYG664](https://sygnal.js.org/reference/errors/#syg664) (error) | A spec whose source `makeBrowserDriverWith(...)` wasn't given |
+| [SYG665](https://sygnal.js.org/reference/errors/#syg665) (warning) | A source or command failed and names no `error` action |
+| [SYG668](https://sygnal.js.org/reference/errors/#syg668) (warning) | An `intersection` / `resize` entry has nothing to observe: no DOM source reached the driver, or (in `renderComponent` with `dom: 'real'`) its selector matches no element of the component |
+| [SYG643](https://sygnal.js.org/reference/errors/#syg643) (warning) | The component declares `browser`, but no browser driver is registered. `sygnal-check` reports it too when it can read the app's `run()` call |
+
+Deferred loading of a component when it scrolls into view is [`lazy(…, { when: 'visible' })`](https://sygnal.js.org/advanced/lazy-loading/#loading-when-visible-or-idle).