@orkestrel/scaffold 0.0.103 → 0.0.104

package/dist/host/guides/table.md

@@ -4,11 +4,10 @@
 > holding the rows given against it, and one lens of sort, filter, and page deciding which of them
 > the view shows.
 
-Nothing here renders, measures a pixel, reads a keyboard, or names a host type. **A grid, a report,
+The core renders nothing and names no host type. **A grid, a report,
 a terminal listing, and a CSV export are the same abstraction.** They all hold a set of records,
 order them, narrow them, and show a stretch of them. What differs is who draws the result, and
-drawing is the one part this package leaves out. The table owns values; the host owns everything a
-person looks at.
+drawing belongs to each host. The browser face binds native table elements to that same document.
 
 The row store is the source of truth, and it is the whole of it. Sort terms, filters, the picked
 keys, the opened keys, and the page are held; `view` and every tally are worked out on read, so no
@@ -21,7 +20,8 @@ copy. Table-owned refusals raise `TableError`, and each one names a caller mista
 
 ## Surface
 
-Everything in this guide is exported from `@orkestrel/table` ([`src/core`](../src/core)). The manager
+The core surface is exported from `@orkestrel/table` ([`src/core`](../src/core)); the native binding
+surface comes from `@orkestrel/table/browser` ([`src/browser`](../src/browser)). The manager
 classes and the key-set shell they compose are the module's internal declarations: they stay out
 of the barrel, so no consumer can construct one, and each constructor takes the table's emitter
 and closures over state `Table` keeps private, which is why they are internal rather than
@@ -63,6 +63,208 @@ table.pagination.count // 2 — two pages of two
 table.view.map((row) => row.name) // ['Grace', 'Alan'] — page one, oldest first
 ```
 
+### Native binding
+
+These declarations belong to the browser entry.
+
+| API                     | Kind      | Shape                                                                                                                                                                                     | Summary                                                                                     |
+| ----------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `TableBinding`          | class     | `TableBindingInterface`                                                                                                                                                                   | Retains keyed native rows while projecting every core table manager.                        |
+| `TableBindingInterface` | interface | `{ element, document, destroyed, emitter } plus refresh, destroy`                                                                                                                         | Binds native table elements to a borrowed core document.                                    |
+| `TableBindingOptions`   | interface | `{ row?, detail?, scope?, describe?: { range?, sort? }, on?, error? }`                                                                                                                    | Configures row ownership, detail presentation, scoped controls, and event listeners.        |
+| `TableRange`            | interface | `{ first, last, count, page, pages, limit }`                                                                                                                                              | Describes the displayed page within the filtered rows.                                      |
+| `TableSortDescription`  | interface | `{ column, direction, priority, count }`                                                                                                                                                  | Describes a column's direction and one-based priority among active sort orders.             |
+| `TableExpansion`        | interface | `{ key, expanded }`                                                                                                                                                                       | Proposes one row's next expansion state in a cancelable expand request.                     |
+| `TableBindingEventMap`  | type      | `{ sort: readonly [event: CustomEvent<readonly TableOrder[]>]; expand: readonly [event: CustomEvent<readonly TableExpansion[]>]; render: readonly []; error: readonly [error: unknown] }` | Announces cancelable sorting and expanding, completed rendering, and failed DOM operations. |
+| `TableRenderHandler`    | type      | `(element: HTMLTableRowElement, row: TableRow) => void`                                                                                                                                   | Patches the contents of a retained row without moving or replacing that row.                |
+| `TableProjection`       | interface | `{ schema, rows }`                                                                                                                                                                        | Holds a validated native table projection for constructing a core document.                 |
+| `TableBindingErrorCode` | type      | `'STRUCTURE'`                                                                                                                                                                             | Names a native binding failure at its structure, rendering, or lifecycle boundary.          |
+| `TableBindingError`     | class     | `new (code: TableBindingErrorCode, message: string) => TableBindingError`                                                                                                                 | Represents a native table binding failure with a machine-readable code.                     |
+| `isTableBindingError`   | function  | `(value: unknown) => value is TableBindingError`                                                                                                                                          | Checks whether a caught value is a native table binding error.                              |
+| `createTableBinding`    | function  | `(element: HTMLTableElement, document: TableInterface, options?: TableBindingOptions) => TableBindingInterface`                                                                           | Creates a native table binding with one retained row owner.                                 |
+| `readTable`             | function  | `(element: HTMLTableElement) => TableProjection`                                                                                                                                          | Reads declared header metadata and explicit row keys into a validated core projection.      |
+| `readTableSchema`       | function  | `(element: HTMLTableElement) => TableSchema`                                                                                                                                              | Reads and validates explicit native header metadata.                                        |
+| `readTableRows`         | function  | `(schema: TableSchema, elements: readonly HTMLTableRowElement[]) => readonly TableRow[]`                                                                                                  | Reads explicit keys and declared direct cells against a core schema.                        |
+
+### Enhance authored rows
+
+Declare one body, a table identity-column name, explicit header column keys and cell kinds, and a
+stable key on every data row. Direct cells declare their columns; omitted cells stay absent. Text
+is preserved verbatim. Numbers and flags use the core parser. A native data element's value or a
+time element's datetime takes precedence over cell text. Choice headers carry their explicit
+choice array as JSON in data-table-choices. Nested tables supply no headers or controls to their parent.
+
+This browser example constructs the document before binding it.
+
+```ts
+import { createTable } from '@orkestrel/table'
+import { createTableBinding, readTable } from '@orkestrel/table/browser'
+
+const element = document.createElement('table')
+element.setAttribute('data-table-key', 'id')
+element.innerHTML =
+	'<caption>People</caption><thead><tr><th data-table-column="id" data-table-cell="text">Reference</th><th data-table-column="name" data-table-cell="text"><button data-table-sort="name">Name</button></th></tr></thead><tbody><tr data-table-key="ash"><td data-table-column="name">Ash</td></tr><tr data-table-key="cedar"><td data-table-column="name">Cedar</td></tr></tbody>'
+document.body.append(element)
+const projection = readTable(element)
+const table = createTable(projection.schema, { rows: projection.rows })
+const binding = createTableBinding(element, table)
+table.filter.set({ column: 'name', operator: 'contains', text: 'Ash' })
+binding.refresh()
+element.tBodies[0]?.rows.length // 1
+binding.destroy()
+element.tBodies[0]?.rows.length // 2: restored in core store order
+table.destroyed // false
+element.remove()
+```
+
+The binding validates the entire authored read before changing core rows. External inserts,
+removals, and cell edits reach the document; an invalid read emits error and writes nothing.
+Detached rows remain observed while their keys live. Authored mode owns cell values in the DOM;
+use the core managers for the view, and edit authored cells to change values. Model mode owns
+values in the document and requires an empty body and a row callback. That callback receives
+the retained row first and its value second. It only patches contents, and runs on creation or
+value change. Sort, selection, filtering, expansion, and pagination do not rerun it.
+
+A detail callback receives a generated row containing one spanning cell. Patch that cell's
+contents; the binding owns its placement and identity. Collapsed and off-view details are retained
+until their data key leaves the store. Render callbacks must return synchronously. A throw emits
+error without render success; refresh retries. Arbitrary callback effects are not rolled back.
+
+Native hooks use real controls: a header button with data-table-sort naming the column, a row
+checkbox with data-table-select, a row button with data-table-expand, and a scope checkbox with
+data-table-page. Scope defaults to the table. Use a scope dedicated to that table for an external
+controls. It selects or clears only current view keys; off-page selection stays selected.
+Sort clicks cycle ascending, descending, and absent, replacing the primary order. Programmatic
+multi-sort remains intact and is described on each sorted header button. The sort event carries
+a cancelable CustomEvent whose detail is the proposed order array; preventDefault vetoes before
+the document changes. A row expand button or the page expand button emits expand first, with a
+cancelable CustomEvent whose detail lists each key and its proposed expanded state; preventDefault
+leaves every key and row unchanged, so a host can run its own close transition and then clear the
+key through the document's expansion. The core managers remain the only owners of filters and paging.
+
+An external pager belongs inside the binding's dedicated scope. Use a select with
+`data-table-limit`, buttons with `data-table-move="previous"` and `data-table-move="next"`, and an
+authored `output` with `data-table-range`. A limit option's value is a positive integer; an empty
+value removes paging. Invalid values emit a binding error without changing pagination. Programmatic
+limit changes update the select; include an option for each limit your page uses. Native disabled
+states follow the bounds. A focused button that becomes disabled hands focus to the enabled
+opposite button, or to the named table when neither direction is available.
+
+The range output is cleared before filling on a later task. It fills initially and when the
+displayed range, filtered count, page, page count, or limit changes. Sorting, selection, expansion,
+and refresh alone don't repeat the sentence. Its implicit status role needs no added live role.
+The default is `1 to 2 of 3`, or `0 to 0 of 0` for an empty view. The `describe.range` callback
+receives one-based bounds, filtered count, page and page count, and the optional page limit.
+The `describe.sort` callback receives the column, direction, one-based priority, and active order
+count. Its default is `Sort priority 2 of 2, descending`. Formatter throws emit error without
+render success; refresh retries. Destroy cancels pending fills and restores control values still
+carrying the binding's last write, preserving caller edits.
+
+A button with `data-table-expand="page"` expands the visible keys, or collapses them when every
+visible key is expanded. Off-page expansion stays intact. The cancelable `expand` request lists
+only the keys whose state changes. The label stays authored;
+`aria-expanded` carries the state, and an empty view disables the button. Row controls continue
+to use bare `data-table-expand`. Detail rows and their identifiers survive collapse and paging.
+Nested tables supply none of these controls to the containing binding. The binding renders no
+numbered page window; presentation classes belong to the host.
+
+This scoped binding example customizes wording while retaining native control labels.
+
+```ts
+import { createTable } from '@orkestrel/table'
+import { createTableBinding, readTable } from '@orkestrel/table/browser'
+
+const scope = document.createElement('section')
+scope.innerHTML =
+	'<table data-table-key="id"><caption>Accounts</caption><thead><tr><th data-table-column="id" data-table-cell="text"><button data-table-sort="id">Account</button></th></tr></thead><tbody><tr data-table-key="ash"><td data-table-column="id">ash</td></tr><tr data-table-key="cedar"><td data-table-column="id">cedar</td></tr></tbody></table><nav aria-label="Account pages"><output data-table-range></output><select aria-label="Rows per page" data-table-limit><option value="1">1</option><option value="">All</option></select><button type="button" data-table-move="previous">Previous</button><button type="button" data-table-move="next">Next</button><button type="button" data-table-expand="page">Page details</button></nav>'
+document.body.append(scope)
+const element = scope.querySelector('table')
+if (element === null) throw new Error('Missing account table')
+const projection = readTable(element)
+const table = createTable(projection.schema, { rows: projection.rows, limit: 1 })
+const binding = createTableBinding(element, table, {
+	scope,
+	describe: {
+		range: ({ first, last, count }) => `${first}–${last} of ${count} accounts`,
+		sort: ({ priority, count, direction }) => `Order ${priority}/${count}: ${direction}`,
+	},
+	detail: (node, row) => {
+		const cell = node.cells[0]
+		if (cell !== undefined) cell.textContent = `Account ${row['id']}`
+	},
+})
+// Keep the binding while the page is mounted; release it before removing the scope.
+binding.destroy()
+table.destroy()
+scope.remove()
+```
+
+Rendering coalesces on a later task, including writes during callbacks. Rows and child controls
+retain identity across the view. Reorders use native state-preserving movement when available;
+focus is restored on fallback moves. When a focused row leaves the view, focus moves to the named
+table. An already focused external control keeps focus. Destroy disconnects scheduling, observers,
+and listeners, restores attributes still carrying the binding's values, removes details, and
+returns retained authored rows in core order while retaining a connected focused control. A caller's
+deliberate focus choice outside the row remains untouched. Model rows remain an inert final snapshot. The
+borrowed document stays live.
+
+The lower-level readers share the same validation boundary, and the row comparison ignores
+snapshot identity.
+
+```ts
+import {
+	TableBinding,
+	TableBindingError,
+	isTableBindingError,
+	readTableRows,
+	readTableSchema,
+} from '@orkestrel/table/browser'
+import { createTable, matchesTableRow } from '@orkestrel/table'
+
+const element = document.createElement('table')
+element.setAttribute('data-table-key', 'id')
+element.innerHTML =
+	'<thead><tr><th data-table-column="id" data-table-cell="text">Reference</th></tr></thead><tbody></tbody>'
+const schema = readTableSchema(element)
+const rows = readTableRows(schema, []) // []
+const table = createTable(schema, { rows })
+const binding = new TableBinding(element, table)
+binding.destroy()
+matchesTableRow({ id: 'ash' }, { id: 'ash' }) // true
+isTableBindingError(new TableBindingError('STRUCTURE', 'Missing identity')) // true
+```
+
+### Replace complete rows
+
+Replacement removes omitted optional cells while preserving the identity and its manager state.
+
+```ts
+import { createTable } from '@orkestrel/table'
+
+const table = createTable(
+	{
+		key: 'id',
+		columns: [
+			{ key: 'id', cell: 'text' },
+			{ key: 'name', cell: 'text' },
+		],
+	},
+	{ rows: [{ id: 'ash', name: 'Ash' }] },
+)
+table.selection.select('ash')
+table.rows.replace({ id: 'ash' }) // true
+table.rows.row('ash') // { id: 'ash' }
+table.selection.keys.has('ash') // true
+```
+
+### Row equality
+
+This helper belongs to the core entry.
+
+| API               | Kind     | Shape                                                       | Summary                                                                  |
+| ----------------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `matchesTableRow` | function | `(left: TableRow \| undefined, right: TableRow) => boolean` | Compares complete row values independently of their snapshot identities. |
+
 ### Rows, cells, and columns
 
 The document itself — what a table declares and what one row of it holds. All data, no behavior.
@@ -116,7 +318,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
 | `createTable`                | function  | `(schema: TableSchema, options?: TableOptions) => TableInterface`                                                       | Opens a table against a schema. The schema is copied, and the copy is what the table declares.                                                                                                    |
 | `TableOptions`               | interface | `{ on?, error?, rows?, comparators?, matchers?, limit? }`                                                               | Describes how to open a table — the listeners wired at construction and where a throw from one goes, the rows seeded into it, the per-column comparison and test replacements, and the page size. |
 | `TableEventMap`              | type      | `{ write, remove, sort, filter, select, expand, paginate, clear }`                                                      | Lists everything a table announces, mapping each event to the payload its listeners receive.                                                                                                      |
-| `RowManagerInterface`        | interface | `{} plus row, rows, add, update, move, remove`                                                                          | Manages the rows a table holds, in the order it holds them.                                                                                                                                       |
+| `RowManagerInterface`        | interface | `{} plus row, rows, add, update, replace, move, remove`                                                                 | Manages the rows a table holds, in the order it holds them.                                                                                                                                       |
 | `SortManagerInterface`       | interface | `{} plus order, orders, set, remove`                                                                                    | Manages the order a table reads its rows in.                                                                                                                                                      |
 | `FilterManagerInterface`     | interface | `{} plus filter, filters, set, remove`                                                                                  | Manages which rows a table keeps.                                                                                                                                                                 |
 | `SelectionManagerInterface`  | interface | `{ keys } plus select, clear, toggle`                                                                                   | Manages the rows somebody has picked.                                                                                                                                                             |
@@ -1257,14 +1459,22 @@ it either way.
 
 #### `RowManagerInterface`
 
-| Method   | Returns                   | Summary                                                                                                             |
-| -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `row`    | `TableRow` or `undefined` | Finds one row by key; `undefined` when the table holds no such key.                                                 |
-| `rows`   | `readonly TableRow[]`     | Reads every row the table holds, in its own order — unfiltered, unsorted, and unpaged.                              |
-| `add`    | `void`                    | Takes in one row or several, appending them in the order given. Every row is checked before any is admitted.        |
-| `update` | `boolean`                 | Writes over one row or several, each found by the key it carries. The cells given replace; the cells left out stay. |
-| `move`   | `boolean`                 | Moves one row to another place in the table's own order, counted from zero and clamped to the rows that exist.      |
-| `remove` | `void` or `boolean`       | Takes out every row, one row, or several. Selection and expansion drop the keys of the rows that went.              |
+| Method    | Returns                   | Summary                                                                                                             |
+| --------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `row`     | `TableRow` or `undefined` | Finds one row by key; `undefined` when the table holds no such key.                                                 |
+| `rows`    | `readonly TableRow[]`     | Reads every row the table holds, in its own order — unfiltered, unsorted, and unpaged.                              |
+| `add`     | `void`                    | Takes in one row or several, appending them in the order given. Every row is checked before any is admitted.        |
+| `update`  | `boolean`                 | Writes over one row or several, each found by the key it carries. The cells given replace; the cells left out stay. |
+| `replace` | `boolean`                 | Replaces complete rows under existing keys, removing omitted cells without moving identities.                       |
+| `move`    | `boolean`                 | Moves one row to another place in the table's own order, counted from zero and clamped to the rows that exist.      |
+| `remove`  | `void` or `boolean`       | Takes out every row, one row, or several. Selection and expansion drop the keys of the rows that went.              |
+
+#### `TableBindingInterface`
+
+| Method    | Returns | Summary                                                                           |
+| --------- | ------- | --------------------------------------------------------------------------------- |
+| `refresh` | `void`  | Reconciles and renders the document, retrying a failed renderer.                  |
+| `destroy` | `void`  | Releases listeners and restores owned attributes without destroying the document. |
 
 #### `SortManagerInterface`
 
@@ -1372,7 +1582,7 @@ table.count // 1
 These invariants hold across [`src/core`](../src/core) and this guide.
 
 1. **Documented surface equals exported surface.** Every row in the `## Surface` tables is a real
-   barrel export of `src/core`, and every barrel export is a row — both directions, exhaustively.
+   barrel export of `src/core` or `src/browser`, and every barrel export is a row — both directions, exhaustively.
    The manager classes and the key-set shell are internal, so the parity suite's internal list names
    them and nothing else.
 2. **Documented methods equal interface methods.** Each `## Methods` table lists exactly its
@@ -1503,7 +1713,7 @@ this package answers today through a mechanism it already exposes.
 | CSV and spreadsheet export   | host          | `view` or `rows()` plus `schema.columns` is the whole input an exporter needs, and the file format, encoding, and download belong to the host that has a filesystem or a browser.                                                                                                                                                                                                                                             |
 | Cell-level selection         | out           | Selection holds row keys. A rectangular cell range is a second selection model with its own vocabulary, and no consumer has asked for one.                                                                                                                                                                                                                                                                                    |
 | Choice `meta`                | out           | `meta` is on `ColumnBase` alone, because a column carrier is what the first consumer asked for. The exact guard refuses it on `ColumnChoice` until one asks.                                                                                                                                                                                                                                                                  |
-| Browser binding              | `src/browser` | Binding a table to real elements — a grid, its headings, its scroll container — belongs in a future `src/browser`, taking a table and an element. Nothing renders in this round.                                                                                                                                                                                                                                              |
+| Browser binding              | `src/browser` | The browser entry binds native table rows and controls to a borrowed core document; the core remains host-independent.                                                                                                                                                                                                                                                                                                        |
 
 ## Tests
 

package/dist/host/guides/terminal.md

@@ -351,23 +351,23 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
 The stream guards, the cursor math behind the in-place re-render, and the per-field line projections
 the walk renders with ([`src/server`](../src/server)). All pure, all exported, all unit-tested.
 
-| API                     | Kind     | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `isInputStream`         | function | Checks whether `value` is a usable `InputStreamInterface` — a record with callable `on` / `off` `'data'` subscription methods. A total type guard: it never throws and returns `false` for anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`, or a fake TTY a test injects) to the exact slice the driver reads, never an assertion.                                                                                                                                                          |
-| `isReadable`            | function | Checks whether `value` is a Node `NodeJS.ReadableStream` — a total structural guard checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface` requires as its `input`. The non-TTY fallback narrows the resolved input stream through this before handing it to readline, never through an assertion, so a real piped `process.stdin` (or a `PassThrough` a test injects) crosses into the readline boundary honestly. Never throws; returns `false` for a minimal fake that isn't a full readable.        |
-| `supportsRawMode`       | function | Checks whether an input stream can be driven in raw mode — it reports `isTTY === true` and exposes a callable `setRawMode`. The `Terminal` probes this to choose its path: true selects the interactive raw-mode fields, with arrow-key navigation and a live re-render; false selects the `node:readline` line-input fallback, because a piped or non-terminal stream cannot enter raw mode. Total — never throws.                                                                                                                        |
-| `lineCount`             | function | Counts the terminal lines a rendered prompt `view` occupies — one more than its newline count, so a view with no newline is a single line and a view with N newlines spans N+1 lines. The basis of the in-place re-render: the driver records the line count of the view it wrote so the next redraw knows how far up to move the cursor before overwriting. Total; an empty string is one empty line.                                                                                                                                     |
-| `renderCursorUp`        | function | Returns the cursor-up control sequence that moves the cursor up `count` lines (`ESC[{count}A`), or the empty string when `count` is zero or negative, because no movement is needed and `ESC[0A` is a wasted write. The pure step the in-place re-render uses to climb back over the previous view before clearing it. Total.                                                                                                                                                                                                              |
-| `redrawPrefix`          | function | Returns the full reposition-and-clear prefix to write before re-rendering a prompt view in place — given the line count of the previous view, it moves the cursor up over those lines, returns it to column 0, and erases everything from there to the end of the screen, so the next view is drawn on a clean region and a taller previous view leaves no orphaned rows. Pure; the driver writes this immediately followed by the new view.                                                                                               |
-| `fieldToText`           | function | Projects any field the walk reads as a line of text into the `TextField` the text reducer takes — `text` itself, and the controls a terminal has no widget for: `number`, `date`, `time`, `datetime`, `color`, and one `file` entry. The label carries that control's format cue from `CONTROL_HINTS`, and a declared `default` becomes the line a bare return submits. The projection carries no rule, because the authoritative form still evaluates the answer this line binds; it exists only so one reducer covers every one of them. |
-| `valueToText`           | function | Projects one held answer into the text a read-only line shows — a scalar as itself, a boolean as `yes` / `no` (the word the confirm reducer commits), and a list joined by commas. Absence renders as nothing, because a locked field nobody has answered has nothing to show.                                                                                                                                                                                                                                                             |
-| `filterEnabled`         | function | Returns the choices a `select` or `checkbox` field actually offers — the form refuses a disabled choice's value at every door, including a fill, so the walk never puts one in front of the cursor. Pair with `filterDisabled` to tell the reader what was withheld.                                                                                                                                                                                                                                                                       |
-| `filterDisabled`        | function | Returns the choices a `select` or `checkbox` field shows but refuses — the complement of `filterEnabled`, rendered by `renderUnavailableLine` above the list so a reader sees why a declared choice is missing from it.                                                                                                                                                                                                                                                                                                                    |
-| `renderGroupHeader`     | function | Renders the section header the walk writes when it enters a new field group, painted by the `message` role.                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `renderLockedLine`      | function | Renders the read-only line a locked field shows — its label, the `LOCKED_MARK`, and the answer the form already holds. The walk writes this instead of a prompt, because the field is still validated and still submitted but must not be edited here.                                                                                                                                                                                                                                                                                     |
-| `renderSuggestionLine`  | function | Renders the line listing an open select's offered values above its text prompt — a suggestion list, because an open select admits an answer the list does not offer.                                                                                                                                                                                                                                                                                                                                                                       |
-| `renderUnavailableLine` | function | Renders the line naming the choices a field shows but refuses, written above the list the walk drives.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `renderNumberedList`    | function | Renders the numbered choice list the non-TTY fallback prints — a piped stream cannot navigate with arrow keys, so each offered choice is printed with the number the reader types back. One line per choice, with no trailing newline.                                                                                                                                                                                                                                                                                                     |
+| API                     | Kind     | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `isInputStream`         | function | Checks whether `value` is a usable `InputStreamInterface` — a record with callable `on` / `off` `'data'` subscription methods. A total type guard: it never throws and returns `false` for anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`, or a fake TTY a test injects) to the exact slice the driver reads, never an assertion.                                                                                                                                                                            |
+| `isReadable`            | function | Checks whether `value` is a Node `NodeJS.ReadableStream` — a total structural guard checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface` requires as its `input`. The non-TTY fallback narrows the resolved input stream through this before handing it to readline, never through an assertion, so a real piped `process.stdin` (or a `PassThrough` a test injects) crosses into the readline boundary honestly. Never throws; returns `false` for a minimal fake that isn't a full readable.                          |
+| `supportsRawMode`       | function | Checks whether an input stream can be driven in raw mode — it reports `isTTY === true` and exposes a callable `setRawMode`. The `Terminal` probes this to choose its path: true selects the interactive raw-mode fields, with arrow-key navigation and a live re-render; false selects the `node:readline` line-input fallback, because a piped or non-terminal stream cannot enter raw mode. Total — never throws.                                                                                                                                          |
+| `lineCount`             | function | Counts the terminal lines a rendered prompt `view` occupies — one more than its newline count, so a view with no newline is a single line and a view with N newlines spans N+1 lines. The basis of the in-place re-render: the driver records the line count of the view it wrote so the next redraw knows how far up to move the cursor before overwriting. Total; an empty string is one empty line.                                                                                                                                                       |
+| `renderCursorUp`        | function | Returns the cursor-up control sequence that moves the cursor up `count` lines (`ESC[{count}A`), or the empty string when `count` is zero or negative, because no movement is needed and `ESC[0A` is a wasted write. The pure step the in-place re-render uses to climb back over the previous view before clearing it. Total.                                                                                                                                                                                                                                |
+| `redrawPrefix`          | function | Returns the full reposition-and-clear prefix to write before re-rendering a prompt view in place — given the line count of the previous view, it moves the cursor up over those lines, returns it to column 0, and erases everything from there to the end of the screen, so the next view is drawn on a clean region and a taller previous view leaves no orphaned rows. Pure; the driver writes this immediately followed by the new view.                                                                                                                 |
+| `fieldToText`           | function | Projects any field the walk reads as a line of text into the `TextField` the text reducer takes — `text` itself, and the controls a terminal has no widget for: `number`, `date`, `time`, `datetime`, `color`, one `list` entry, and one `file` entry. The label carries that control's format cue from `CONTROL_HINTS`, and a declared `default` becomes the line a bare return submits. The projection carries no rule, because the authoritative form still evaluates the answer this line binds; it exists only so one reducer covers every one of them. |
+| `valueToText`           | function | Projects one held answer into the text a read-only line shows — a scalar as itself, a boolean as `yes` / `no` (the word the confirm reducer commits), and a list joined by commas. Absence renders as nothing, because a locked field nobody has answered has nothing to show.                                                                                                                                                                                                                                                                               |
+| `filterEnabled`         | function | Returns the choices a `select` or `checkbox` field actually offers — the form refuses a disabled choice's value at every door, including a fill, so the walk never puts one in front of the cursor. Pair with `filterDisabled` to tell the reader what was withheld.                                                                                                                                                                                                                                                                                         |
+| `filterDisabled`        | function | Returns the choices a `select` or `checkbox` field shows but refuses — the complement of `filterEnabled`, rendered by `renderUnavailableLine` above the list so a reader sees why a declared choice is missing from it.                                                                                                                                                                                                                                                                                                                                      |
+| `renderGroupHeader`     | function | Renders the section header the walk writes when it enters a new field group, painted by the `message` role.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `renderLockedLine`      | function | Renders the read-only line a locked field shows — its label, the `LOCKED_MARK`, and the answer the form already holds. The walk writes this instead of a prompt, because the field is still validated and still submitted but must not be edited here.                                                                                                                                                                                                                                                                                                       |
+| `renderSuggestionLine`  | function | Renders the line listing an open select's offered values above its text prompt — a suggestion list, because an open select admits an answer the list does not offer.                                                                                                                                                                                                                                                                                                                                                                                         |
+| `renderUnavailableLine` | function | Renders the line naming the choices a field shows but refuses, written above the list the walk drives.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `renderNumberedList`    | function | Renders the numbered choice list the non-TTY fallback prints — a piped stream cannot navigate with arrow keys, so each offered choice is printed with the number the reader types back. One line per choice, with no trailing newline.                                                                                                                                                                                                                                                                                                                       |
 
 ### The server constants
 
@@ -385,6 +385,7 @@ A `Shape` cell holds the constant's declared type.
 | `CLEAR_DOWN`             | const | `string`                                          | Erases from the cursor down to the end of the screen (`ESC[J`) — wipes the whole previous view, which a `select` or `checkbox` can spread over several lines, in one write before the new view is rendered, so a redraw never leaves orphaned rows behind.                                                                                                                                                                                                                    |
 | `CONTROL_HINTS`          | const | `Readonly<Partial<Record<FieldControl, string>>>` | Holds the format cue appended to a field's label for each control the walk reads as a line of text — the terminal has no date picker, no color well, and no file chooser, so the accepted shape is stated instead. A control with no entry needs none: `text` and `editor` accept any line, `password` masks one, and `confirm`, `select`, and `checkbox` are answered by key rather than by format. The form's own rules still decide whether the typed value is acceptable. |
 | `FILE_HINT`              | const | `string`                                          | Holds the instruction a `file` field with `multiple` shows before its entries — one path per line, and a blank line ends the list.                                                                                                                                                                                                                                                                                                                                            |
+| `LIST_HINT`              | const | `string`                                          | Holds the instruction a `list` field shows before its entries — one entry per line, and a blank line ends the list.                                                                                                                                                                                                                                                                                                                                                           |
 | `SUGGESTION_LEAD`        | const | `string`                                          | Holds the lead on the line listing an open `select`'s offered values, which a typed answer can ignore.                                                                                                                                                                                                                                                                                                                                                                        |
 | `UNAVAILABLE_LEAD`       | const | `string`                                          | Holds the lead on the line listing the choices a `select` or `checkbox` shows but refuses, so a reader sees why one is missing from the list it heads.                                                                                                                                                                                                                                                                                                                        |
 | `LOCKED_MARK`            | const | `string`                                          | Holds the mark on a locked field's line — the walk renders its value and moves on, because the form refuses an edit there.                                                                                                                                                                                                                                                                                                                                                    |
@@ -561,9 +562,10 @@ These invariants hold across `src/core`, `src/server`, and this guide.
    carries no `name` with the raw sequence preserved, so the driver cannot crash on a stray byte.
    `KeyEvent.name` is therefore optional and absence is `undefined`: an undecoded key has no name
    rather than an empty one, and every reducer reads it as a key it does not consume.
-10. **Every control reaches a reducer.** `text`, `number`, `date`, `time`, `datetime`, `color`, and
-    each `file` entry are read as one line of text through `fieldToText`, which appends that
-    control's format cue to the label; `password`, `confirm`, `editor`, `select`, and `checkbox`
+10. **Every control reaches a reducer.** `text`, `number`, `date`, `time`, `datetime`, `color`, each
+    `list` entry, and each `file` entry are read as one line of text through `fieldToText`, which
+    appends that control's format cue to the label; a `list` reads one entry per line until a blank
+    one and keeps its declared `default` when none is typed; `password`, `confirm`, `editor`, `select`, and `checkbox`
     each drive their own reducer. An open select is a suggestion list plus a typed line, because
     `open` means the answer need not come from the list. A disabled choice is named on an
     unavailable line and never offered, since the form refuses its value at every door. A `hidden`