sygnal 7.0.0 → 7.2.0-preview.0

package/dist/guide/renderers/react-native.md

@@ -0,0 +1,128 @@
+<!-- Generated from docs/src/content/docs/renderers by scripts/copy-guides.mjs; online: https://sygnal.js.org/renderers/ -->
+# React Native
+
+`sygnal/react-native` runs a Sygnal app on React Native. Your components, intents and models stay as they are. The view renders into a [host tree](./custom-targets.md), and the bridge shows that tree as React Native components. Native callbacks arrive as the DOM events your intents already listen for: `onPress` is a `click`, `onChangeText` an `input`.
+
+```js
+// index.js
+import { createElement } from 'react'
+import { registerRootComponent } from 'expo'
+import { SygnalView } from 'sygnal/react-native'
+import Tasks from './src/Tasks.jsx'
+
+registerRootComponent(() => createElement(SygnalView, { app: Tasks }))
+```
+
+`react` and `react-native` are optional peer dependencies: install them in the app, as Expo does. In a Sygnal component file, set the JSX source with a pragma comment (`/** @jsxImportSource sygnal */`), because the React Native Babel preset compiles JSX for React by default. The [write-once example](https://github.com/tpresley/sygnal/tree/main/examples/write-once) is an Expo app with its Metro config, run in the iOS simulator.
+
+## SygnalView
+
+| Prop | |
+|---|---|
+| `app` | the root component |
+| `drivers` | the app's other drivers (`DOM` is the bridge's) |
+| `runOptions` | [`run()`](https://sygnal.js.org/reference/api/) options |
+| `styles` | the native stylesheet (below) |
+| `defaultStyles` | `false`: drop `defaultNativeStyles` (the look of plain HTML tags) |
+| `components` | your own React Native components, by tag or primitive name |
+| `onNavigate(href, el)` | a link's default action: route with your router driver |
+| `style` | the root View's style (default `{ flex: 1 }`) |
+
+The app starts when the view mounts, and is disposed when it unmounts. For lower-level control, `createNativeHost(options)` returns `{ driver, Root, doc, stop }`: run the app with `run(App, { DOM: host.driver })`, render `<host.Root />` wherever you like, and call `host.stop()` before disposing.
+
+## What renders as what
+
+| Host element | React Native | Events it makes |
+|---|---|---|
+| `View`, and `div` / `section` / `ul` / `form` … | `View` | |
+| `Text`, and `span` / `p` / `label` / `h1` … | `Text` | `click` (`onPress`) when an intent listens for it |
+| `Pressable`, `button` | `Pressable` (direct text wrapped in `Text`) | `click` |
+| `TextInput`, `input`, `textarea` | `TextInput` | `input`, `keydown` Enter (submit key), `focus`, `blur`, `change` |
+| `Switch`, `input type="checkbox"` | `Switch` | `click`, `input`, `change` |
+| `Image`, `img` | `Image` | |
+| `ScrollView` | `ScrollView` | `scroll` |
+| `List` | `FlatList` over its children | `scroll` |
+| `select` | a `Pressable` that steps to the next option | `input`, `change` |
+| `a href` | `Text` | `click`, then `onNavigate(href)` |
+
+An HTML view runs too. A container whose children are all inline (a `<li>` holding a checkbox, a label and a button) becomes a row, the way a browser lays it out, and `defaultNativeStyles` gives headings, links, buttons and fields their usual look. The [primitives](./write-once.md) give you exact control instead.
+
+A target's own field tags, registered with [`registerFieldTags`](./custom-targets.md#your-own-tags), map by kind: `'text'` to `TextInput`, and `{ tag, kind: 'checkbox' }` to `Switch`.
+
+## Controlled fields
+
+A field's value comes from the app's state: `<Draft value={state.draft} />`. The bridge reads the value from the host element at the moment React renders the field, not before. React Native's own `TextInput` protocol (the native event count) then keeps the user's typing ahead of a render that hasn't seen it yet. The app's value wins whenever it differs, for example when the model clears the field after Add. You don't need anything extra for fast typing.
+
+A `Switch` is a real checkbox: a press toggles `checked`, then fires `click`, `input` and `change`. When an intent prevents the click (`preventDefault()`), the switch springs back.
+
+## Styles
+
+Inline styles are React Native style objects. The `styles` prop adds a stylesheet of `[selector, style]` rules for anything that depends on classes or structure. Its rules are compiled with `StyleSheet.create`:
+
+```js
+// nativeStyles.js
+export const nativeStyles = [
+  ['.task.done', { opacity: 0.5 }],
+  ['.toolbar', { flexDirection: 'row', justifyContent: 'space-between' }],
+  ['.toolbar .title', { fontSize: 20, fontWeight: '600' }],
+]
+```
+
+An element's style is its matching rules in order (after `defaultNativeStyles`), then its inline style. Flex layout keys work as in React Native. React Native doesn't inherit text styles from a `View`, so a View-like element's text keys (`color`, `fontSize`, …) style the `Text` that wraps its own direct text, and nested `Text` inherits as usual. Selectors support what the [host selectors](./custom-targets.md#painting) do: tags, classes, attributes, `:not()`, and descendant and child combinators.
+
+## Lists
+
+Put a `Collection` in a `List`:
+
+```jsx
+// Feed.jsx
+import { Collection } from 'sygnal'
+import { List } from 'sygnal/primitives'
+import Post from './Post.jsx'
+
+export default function Feed() {
+  return <List><Collection of={Post} from="posts" /></List>
+}
+```
+
+On native, the `List` is a `FlatList` over the Collection's items, so only the visible rows have native views. The limits:
+
+- **Every item stays mounted in Sygnal.** Each item component runs and keeps its state, as on the web. FlatList windows the native views only. Lists of a few thousand simple items are fine; for far more, page the data in your model (listen for `scroll` and its `detail.end`).
+- **`VirtualCollection` is web-only:** it measures DOM elements, which a host tree doesn't have.
+
+## Incremental rendering
+
+Every host element is a memoized React component, keyed by its host node and that node's revision. A mutation moves the revision of the node and its ancestors, so a change re-renders only the path to it:
+
+| A list of 100 items (303 elements) | Elements rendered | React commits |
+|---|---|---|
+| tap a counter at the top: full re-render | 303 | 1 |
+| tap a counter at the top: `sygnal/react-native` | 2 | 1 |
+| toggle item 51: full re-render | 303 | 1 |
+| toggle item 51: `sygnal/react-native` | 4 | 1 |
+
+These counts come from the library's tests, which use `onNodeRender` and `incremental: false` to compare. A descendant selector in the stylesheet (`.done .title`) makes a class change re-render that element's subtree too, since its descendants may now match differently.
+
+## Your own components
+
+`components` maps a tag (or a primitive name) to a function that returns a React element:
+
+```js
+// components.js
+import { createElement as h } from 'react'
+import { ActivityIndicator } from 'react-native'
+
+export const components = {
+  // <spinner size="large" /> in a Sygnal view
+  spinner: (el, _children, style) => h(ActivityIndicator, { size: el.size || 'small', style: style.view }),
+}
+```
+
+The function gets the host element, its children (already React elements), its computed style split into `{ view, text, all }`, and a context: `ctx.fire(el, type, init)` sends a DOM-shaped event, and `ctx.press(el)` sends a click with its default action. The tag renders as `<spinner>` on the web, so give the web a fallback or keep it in a native-only view.
+
+## Limits
+
+- **Expo Go, simulators and devices:** the bridge is plain JavaScript. A native build (`expo run:ios`) needs CocoaPods, as for any React Native app.
+- **Web-only features:** `Portal`, the [UI parts](../ui/overview.md), `VirtualCollection`, view transitions and the browser sources need the DOM.
+- **Gestures:** a press is a `click`; double clicks, hover and long-press aren't mapped. Use a `components` entry with your gesture library for more.
+- **Pickers:** React Native's core has no picker, so a `<select>` steps through its options on each press. Map `select` to a picker component through `components` for a real one.

package/dist/guide/renderers/terminal.md

@@ -0,0 +1,306 @@
+<!-- Generated from docs/src/content/docs/renderers by scripts/copy-guides.mjs; online: https://sygnal.js.org/renderers/ -->
+# Terminal Apps
+
+`sygnal/terminal` runs a Sygnal app in a terminal. Your components, intents and models stay the same. The view's HTML is painted as text, and key presses become the DOM events your intents already listen for.
+
+```jsx
+// terminal.jsx
+import { runTerminal } from 'sygnal/terminal'
+import Groceries from './Groceries.jsx'
+
+runTerminal(Groceries, {
+  styles: [
+    ['h1', { color: 'green', upper: true }],
+    ['.item.done label', { dim: true, after: ' ✓' }],
+  ],
+})
+```
+
+```
+GROCERIES
+Item [Milk, bread, …] Aisle [produce ▾] [Add]
+  • [ ] Apples (produce) [×]
+  • [x] Milk ✓ (dairy) [×]
+— 1 to buy · Show [all ▾] [Clear the cart]
+
+Tab move · Ctrl+C quit
+```
+
+`runTerminal` takes over the TTY. It switches to the alternate screen, reads raw keys, and redraws in place after every change. It keeps the focused line in view and follows resizes. Ctrl+C disposes the app and restores the terminal, and so does a crash or a `SIGTERM`. It runs in Node. Bundle your JSX first (the [examples](https://github.com/tpresley/sygnal/tree/main/examples/tui-tracker) use a Vite SSR build), or use any runner that compiles JSX with `jsxImportSource: 'sygnal'`.
+
+| Option | |
+|---|---|
+| `styles` | the terminal stylesheet (below) |
+| `drivers` | the app's other drivers (`DOM` and `TERMINAL` are the terminal's) |
+| `runOptions` | [`run()`](https://sygnal.js.org/reference/api/) options: `onError`, `diagnostics`, … |
+| `onNavigate(href, el)` | a link's default action: route with your router driver |
+| `footer` | the line under the app. Default: what the keys do on the focused element. A string, a function of the terminal, or `false` for none |
+| `mouse` | clicks, double clicks and the wheel (default `false`, so the terminal keeps its own text selection) |
+| `emojiWidth` | how many cells the terminal draws an emoji in. `'auto'` (default) asks the terminal at start: xterm.js-based terminals (VS Code's) draw 🐛 in one cell, most others in two |
+| `console` | `'buffer'` (default on a TTY: `console.log` output is kept, counted in the footer and written after the terminal is restored) or `'pass'` |
+| `color`, `alternateScreen` | default: on when stdout is a TTY |
+| `stdin`, `stdout` | default `process.stdin` / `process.stdout` |
+| `onExit(code)` | after Ctrl+C, a `TERMINAL` exit or `stop()` |
+
+It returns `{ app, terminal, stop }`.
+
+### Defaults
+
+| Default | Why | To change it |
+|---|---|---|
+| The mouse is off | the terminal keeps its own text selection (copying from the screen) | `mouse: true` |
+| Ctrl+D deletes forward and Ctrl+A goes to the line start in a text field | the readline keys of shells, Textual and prompt_toolkit, not EOF or select all | the `keydown` goes out first: a [`keymap()`](../inputs.md) shortcut (or a `keydown` intent that prevents the default) takes the key instead |
+| Cell widths come from Sygnal's own tables | no dependency: CJK and fullwidth text take two cells, combining marks and zero-width joiners none | `emojiWidth: 1` or `2` instead of asking the terminal |
+| `console` output is buffered on a TTY | a `console.log` drawn over the screen would scroll it | `console: 'pass'` |
+
+## Keys
+
+| Key | What it does |
+|---|---|
+| Tab / Shift+Tab, ↓ / ↑ | move focus: form fields, buttons, links, `[tabindex]`, and **any element your intents listen to clicks on**. A radio group is one stop, and so is a tab list with a roving `tabindex` |
+| typing | edits the focused text field at its caret (`beforeinput` and `input` events) |
+| ← / →, Home / End | move the caret (Shift selects; Alt or Ctrl moves by word); in a `<textarea>`, ↑ / ↓ move between lines |
+| Backspace, Delete | delete (with Alt or Ctrl: a word) |
+| Ctrl+A E B F D K U W, Alt+B F D | the readline keys in a text field: line start / end, back / forward, delete forward, kill to the end / start, delete a word |
+| Enter | in an `<input>`: submit its form; on a button, link, or clicked element: click it |
+| Space | toggle a checkbox, click a button |
+| Enter / Space on a `[tabindex]` element | click it, unless a component listens to `keydown` on it or an ancestor: an app that handles those keys itself (as it must in a browser, where such an element has no key action) gets one action, not two. App-wide listeners (`DOM.select('document')`, `keymap()`) don't count |
+| ← / → on a radio | check the next radio of its group |
+| F2 | a double click (a terminal has none) |
+| Escape | close the modal dialog, or the open popover |
+| any key | `keydown` / `keyup` on the focused element, or on the app's root |
+
+The footer always shows the keys for the focused element, for example `Enter open list · ←/→ change` on a `<select>`.
+
+Two consequences matter for app code. First, an element like todomvc's `<label>`, which only has a `DOM.dblclick('.todo label')` intent, is still reachable: the terminal knows your intents' selectors, so it adds that label to the focus order. Second, app-wide shortcuts work as on the web, through [`keymap()`](../inputs.md) or `DOM.select('document').events('keydown')`. A shortcut that takes a key prevents its default, so the focus doesn't also move.
+
+### Dropdowns
+
+A native `<select>` works as in a TUI toolkit's select widget:
+
+| Key | Closed | Open |
+|---|---|---|
+| Enter, Space, Alt+↓, F4 | open the option list | Enter / Space: choose the highlighted option (`input`, `change`) and close |
+| ↑ / ↓, Home / End, PageUp / PageDown | move the focus | move the highlight (disabled options are skipped) |
+| ← / → | the previous / next option, at once | |
+| a letter | the next option starting with it | highlight it |
+| Escape, Tab | | close without a change (Tab then moves on) |
+
+The list opens under the select (or above it near the bottom), over what is there. The chosen option has a `✓`:
+
+```
+Show ▸[open ▴]
+     ┌─────────┐
+     │▸open   ✓│
+     │ closed  │
+     │ all     │
+     └─────────┘
+```
+
+### Dialogs, popovers and details
+
+`<dialog>`, `[popover]` and `<details>` behave as in a browser. A closed dialog, a hidden popover and a closed `<details>`' content aren't drawn. `showModal()` (an `ELEMENT` command) draws the dialog centered over the page, with a border and its `aria-label` as the title, and dims the page under it. The focus moves into the dialog and Tab stays there. Escape sends `cancel` and then `close` (so `DOM.close(Confirm)` hears it), and the focus goes back to what opened the dialog. A `popovertarget` button toggles its popover, which is drawn under the button. `commandfor` / `command` buttons work too.
+
+```jsx
+// Issue.jsx
+import { controls } from 'sygnal'
+
+export const { Confirm, Delete } = controls({ Confirm: 'dialog', Delete: 'button' })
+
+export default function Issue({ state }) {
+  return (
+    <article>
+      <h2>{state.title}</h2>
+      {state.deleted ? <p>Deleted.</p> : <Delete>Delete</Delete>}
+      <Confirm aria-label="Confirm">
+        <p>Delete “{state.title}”?</p>
+        <button className="confirm-ok">Delete</button> <button className="confirm-cancel">Cancel</button>
+      </Confirm>
+    </article>
+  )
+}
+
+Issue.initialState = { title: 'Typo in the README', deleted: false }
+
+Issue.intent = ({ DOM }) => ({
+  ASK: DOM.click(Delete),
+  DELETE: DOM.click('.confirm-ok'),
+  CANCEL: DOM.click('.confirm-cancel'),
+})
+
+Issue.model = {
+  ASK: { ELEMENT: { showModal: Confirm } },
+  DELETE: { STATE: (state) => ({ ...state, deleted: true }), ELEMENT: { close: Confirm } },
+  CANCEL: { ELEMENT: { close: Confirm } },
+}
+```
+
+Escape closes the dialog without a model entry; listen with `DOM.close(Confirm)` when the app needs to know.
+
+### Mouse and paste
+
+With `mouse: true`, a click focuses and clicks what it lands on. It toggles a checkbox, opens a select or picks an option, and puts the caret where you clicked in a text field. A double click is a `dblclick`, and the wheel scrolls the box under the pointer. A paste (the terminal's bracketed paste) is one `paste` event and one insertion at the caret; an `<input>` gets its line breaks as spaces. Without bracketed paste, a pasted line break would submit the form.
+
+## Quitting
+
+Ctrl+C always quits. To quit from the app (a `q` key, a menu item), send `'exit'` to the `TERMINAL` sink, which `runTerminal` adds:
+
+```jsx
+// Tracker.jsx
+Tracker.intent = ({ DOM }) => ({ ...keymap(DOM, { q: 'QUIT' }) })
+Tracker.model = { QUIT: { TERMINAL: () => 'exit' } }
+```
+
+It also takes `{ exit: code }` (passed to `onExit`), `{ title: 'Tracker' }` (the window title) and `'bell'`.
+
+## The terminal stylesheet
+
+CSS doesn't reach a terminal, so each app gives the terminal a short list of `[selector, style]` rules. They're applied in order after a default sheet (bold headings, underlined links, a border on dialogs), and an inline `style={{ display: 'none' }}` or `hidden` attribute wins, as in a browser.
+
+| Key | |
+|---|---|
+| `display` | `'none'` hides; `'block'` / `'inline'` override the tag's default; `'flex'` with `flexDirection` |
+| `before`, `after` | text around the element's content |
+| `bold`, `dim`, `italic`, `underline`, `inverse` | text attributes |
+| `color`, `background` | `black red green yellow blue magenta cyan white gray`, or `brightRed`, … |
+| `upper` | the element's text in upper case |
+| `width`, `height` | a box's size in cells (columns / rows), or a percentage: `'40%'` of the space it is in, `height: '100%'` of the screen for the root |
+| `flex` | in a flex row or column: its share of the space left |
+| `border`, `borderColor` | `true` / `'single'`, `'round'`, `'double'`, `'heavy'`; the element's `aria-label` (or `title`) is drawn in the top border |
+| `padding` | cells inside the border: `1`, or `[vertical, horizontal]` |
+| `overflow` | with a height: `'auto'` / `'scroll'` scroll, with a scrollbar, keeping the focused element (and the caret) in view; `'hidden'` crops |
+| `gap` | cells between a flex row's items (default 1) |
+
+Use it for the parts of your CSS that change **what is shown**. todomvc hides the edit field unless its item is being edited:
+
+```js
+// terminal-styles.js
+export const todoStyles = [
+  ['.todo .edit', { display: 'none' }],
+  ['.todo.editing .edit', { display: 'inline' }],
+  ['.todo.editing .view', { display: 'none' }],
+  ['.todo.completed label', { dim: true, after: ' ✓' }],
+  ['.filters li', { display: 'inline' }],
+]
+```
+
+Selectors support what intents use: tag, `#id`, `.class`, `[attr]`, `[attr="v"]` (and `^=` `$=` `*=` `~=`), `:not(…)`, descendant and `>` combinators, and `a, b` lists. The state pseudo-classes are `:focus`, `:focus-within`, `:checked`, `:disabled`, `:open`, `:modal` and `:popover-open`.
+
+The layout is a line flow. Block elements start lines, inline content flows and wraps at the terminal's width, lists indent with bullets or numbers, and `<pre>` keeps its spaces. Form controls are drawn as `[text_]`, `[x]`, `(•)`, `[option ▾]`, `[Button]` and `[████░░] 60%` (a `<progress>`). A `<textarea>` is a box of its `rows`. The focused element shows inverse (or with `▸` in plain text), and a focused box's border turns heavy. Widths count terminal cells: CJK text takes two, combining marks none, and an emoji what the terminal uses (`emojiWidth`).
+
+### Full-screen layouts
+
+An element with a `width`, `height`, `border`, `padding` or scrolling `overflow` is a **box**, laid out in a rectangle of its own. A flex row whose items have a `width`, a `flex` share or a border puts them side by side, all as tall as the row. A flex column with a height gives its `flex` items the rows its other items leave. So a list beside a detail pane, with a status bar on the last row, is:
+
+```js
+// styles.js
+export const terminalStyles = [
+  ['main', { display: 'flex', flexDirection: 'column', height: '100%' }],
+  ['.split', { flex: 1, display: 'flex', flexDirection: 'row' }],
+  ['.issues', { width: '45%', border: 'round', overflow: 'auto' }],
+  ['.issues:focus-within', { borderColor: 'cyan' }],
+  ['.detail', { flex: 1, border: 'round', padding: [0, 1] }],
+  ['.status-bar', { inverse: true }],
+]
+```
+
+```
+TRACKER
+[Issues] [New issue] [Help]
+Filter [title, label, person] Show [open ▾]
+╭─ Issues ────────────────────────╮ ╭──────────────────────────────────────────╮
+│• #12 H Dark mode for the       ││ │ #14 Search ignores accents (2)           │
+│  settings page (2)             █│ │ open · medium · @dara · feature          │
+│• #13 L Typo in the README (2)  ││ │ [Show description]                       │
+│• ▸#14 M Search ignores accents ││ │ [Close] [Delete]                         │
+│  (2)                           ││ │                                          │
+╰─────────────────────────────────╯ ╰──────────────────────────────────────────╯
+Synced 32 shown / 40 ↑↓ issues · → detail · 3 help
+```
+
+The box keys come from the terminal stylesheet only, in cells: an inline web style (`style={{ flex: 1, padding: 8 }}`) doesn't make a box. `scrollIntoView()` (an `ELEMENT` command) scrolls an element's boxes to it.
+
+## Isolation still applies
+
+The terminal changes nothing about how components see the DOM. A `Collection` item's elements belong to the item, so the parent can't listen to a click on them or focus them by selector, in a terminal as in a browser. Listen in the item and send it up with `PARENT`, and focus an item's element from the parent with [`focusWithin`](../element-commands.md):
+
+```jsx
+// IssueRow.jsx
+IssueRow.intent = ({ DOM }) => ({ PICK: DOM.focus('.issue') })
+IssueRow.model = { PICK: { PARENT: (state) => state.id } }
+// the parent: SELECT: CHILD.select(IssueRow); ELEMENT: { focus: focusWithin('.issue[data-id="3"]') }
+```
+
+## sygnal/ui in a terminal
+
+Every [`sygnal/ui`](../ui/overview.md) part on native HTML works in a terminal: [dialog](../ui/dialog.md), [popover](../ui/popover.md), [tooltip](../ui/tooltip.md) (shown on focus under its trigger), [tabs](../ui/tabs.md), [accordion](../ui/accordion.md), [disclosure](../ui/disclosure.md) and the [Toaster](../ui/toaster.md). They read the document of the element they act on, so the same code runs on the terminal's tree, in a browser, and in a shadow root. The arrow keys move between tabs and between accordion triggers.
+
+The `dialog` behavior gives the confirm above its state, its trigger's ARIA and a refusable close:
+
+```jsx
+// Item.jsx
+import { dialog, dialogAttrs } from 'sygnal/ui'
+
+export function Item({ state, uid }) {
+  const a = dialogAttrs(state.ask, uid)
+  return (
+    <div>
+      <button className="delete" {...a.trigger}>Delete</button>
+      <dialog className="ask" {...a.dialog} role="alertdialog" aria-label="Confirm" aria-labelledby={undefined}>
+        <p {...a.description}>Delete it? This can't be undone.</p>
+        <button className="ok">Delete</button> <button className="cancel">Cancel</button>
+      </dialog>
+    </div>
+  )
+}
+
+Item.initialState = { deleted: false }
+Item.uses = { ask: dialog({ dialog: '.ask', trigger: '.delete', close: '.cancel' }) }
+Item.intent = ({ DOM }) => ({ DELETE: DOM.click('.ok') })
+Item.model = { DELETE: (state) => ({ ...state, deleted: true, ask: { ...state.ask, open: false } }) }
+```
+
+The box's title comes from `aria-label`, so the dialog keeps one here instead of a title element. Escape is the dialog's `CANCEL`, and the focus goes back to the trigger.
+
+Render `<Toaster />` once and pass `makeTimerDriver()` in `drivers` (`runTerminal(App, { drivers: { TIMER: makeTimerDriver() } })`). A toast is drawn at the top right and times out. The terminal has no `MutationObserver`, so the toast region doesn't move into an open modal dialog as it does in a browser: a toast that comes while a modal is open is drawn over it and still times out, but its Dismiss button can't take the focus until the dialog closes.
+
+## Testing
+
+`createTerminal()` is the same target without a TTY. Run the app on its driver, press keys, and compare frames as plain text:
+
+```js
+// Groceries.terminal.test.js
+import { it, expect } from 'vitest'
+import { createTerminal } from 'sygnal/terminal'
+import Groceries, { Name } from './Groceries.jsx'
+
+it('adds an item from the keyboard', async () => {
+  const term = createTerminal({ width: 60 })
+  const app = term.run(Groceries)
+  await term.settle()
+  term.focus(Name)
+  term.type('Eggs')
+  term.press('Enter')
+  await term.settle()
+  expect(term.frame()).toContain('[ ] Eggs')
+  app.dispose()
+})
+```
+
+`term.run(App, drivers, runOptions)` is `run()` with the terminal's `DOM` and `TERMINAL` drivers added; it returns the app. `await term.settle()` waits until the app is quiet: nothing scheduled in its runtime and no change to the tree for 20 ms, so element commands (`ELEMENT: { focus }`), delayed actions and a fake server with a short latency are done. It rejects after 2 s with the frame in the message; `term.settle({ timeout, quiet })` changes both. Under `vi.useFakeTimers()` it advances the clock.
+
+| | |
+|---|---|
+| `term.press(key, { shiftKey, ctrlKey, altKey })` | a key, by DOM key name (`'Enter'`, `'Tab'`, `'ArrowDown'`, `'Escape'`, `'F2'`, `' '`, `'a'`) |
+| `term.type(text)`, `term.paste(text)` | typing (a press per character), a paste |
+| `term.click(line, col, { detail })`, `term.wheel(line, col, rows)` | the mouse, at a cell of the current frame |
+| `term.frame()`, `term.render()` | the frame as text; `{ plain, ansi, focusLine, focus, caret, hits }` |
+| `term.focusables()`, `term.keyHint()` | the Tab order; the footer's key hint |
+| `term.run(App, drivers)`, `await term.settle()` | run the app; wait for it to go quiet |
+| `term.commands` | what the app sent its `TERMINAL` sink |
+
+`createTerminal({ width: 80, height: 24 })` gives the frame a screen's height, for full-screen layouts. Test the logic itself once with [`renderComponent`](https://sygnal.js.org/integration/testing/): it covers every target.
+
+## Lower-level pieces
+
+`createTerminal({ onFrame })` calls you with each new frame, if you want to draw it yourself (in a pane of a larger TUI, or over a socket). `paint(doc, { rules, width, height })` paints any [host document](./custom-targets.md), and `hitTest(frame, line, col)` finds the element at a cell. `parseKeys(chunk)` turns raw TTY input into key names, pastes and mouse events, and `stringWidth(text)` counts terminal cells.