@orkestrel/scaffold 0.0.103 → 0.0.105

package/dist/host/guides/table.md

@@ -4,16 +4,15 @@
 > 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
 second copy of an answer can go stale. A write validates all of itself before any of it lands, and
-announces itself once it has.
+announces itself after it has.
 
 The core refuses rather than throws. Every guard returns `false` off-shape rather than throwing,
 every parser returns `undefined` on refusal, and every row the table hands back is a frozen owned
@@ -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.                                                                                                                                                             |
@@ -160,7 +362,7 @@ A `Shape` cell holds the constant's declared type.
 ### Guards
 
 Total `is*` guards over unknown input. None throws, none coerces, and each returns `false` for
-anything off-shape — including a hostile prototype, a symbol key, or a cyclic value.
+anything off-shape — including an unexpected prototype, a symbol key, or a cyclic value.
 
 In a guard table a `Shape` cell holds the type the guard narrows to.
 
@@ -202,7 +404,7 @@ lens-list operations, the cell gate, the comparison, the filter tests, the row p
 audit, and the wire projections. `computeKeys`, `matchesTerms`, `filterRows`, and `sortRows`
 propagate exceptions from supplied callbacks; `serializeTable` raises `SCHEMA` for a `meta` no clone
 can own. The other helpers are total over ordinary declared inputs, subject to the core's
-hostile-reflection boundary described later.
+reflection-failure boundary described later.
 
 | API              | Kind     | Summary                                                                                                                     |
 | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -233,7 +435,7 @@ row the table hands back is a live internal reference.
 | `cloneRow`    | function | Clones one row into an owned frozen snapshot.                                                                                                                   |
 | `cloneSchema` | function | Clones a whole schema into an owned frozen snapshot, freezing every nested column, choice list, choice, and `meta`; raises `SCHEMA` for a `meta` it cannot own. |
 
-`cloneRow` cannot fail for an ordinary row record, subject to the core's hostile-reflection boundary
+`cloneRow` cannot fail for an ordinary row record, subject to the core's reflection-failure boundary
 described later. `cloneSchema` can also fail when a column's `meta` holds something no clone can own, such as a
 record that refers back to itself. `meta` is typed as JSON and a cycle satisfies that type, so the
 refusal is a `TableError` coded `SCHEMA` rather than a silent partial copy. `createTable` never reaches
@@ -253,9 +455,9 @@ owned value rather than the caller's.
 | `parseTable` | function | Parses unknown wire data into an owned, structurally valid, semantically sound table schema.                           |
 | `parseRows`  | function | Parses unknown wire data into owned rows against one table schema, coercing a numeric string and `'true'` / `'false'`. |
 
-**Hostile reflection.** A TypeScript shape does not guarantee that reflection succeeds. An ordinary
+**Reflection failures.** A TypeScript shape does not guarantee that reflection succeeds. An ordinary
 helper or cloner may propagate a throw from a proxy trap or accessor. Guards and parsers contain that
-throw and refuse instead. This is the hostile-reflection boundary for the whole core.
+throw and refuse instead. This is the reflection-failure boundary for the whole core.
 
 ## Cells
 
@@ -780,7 +982,7 @@ the filter admits, so nothing here can drift out of step with what the table hol
   "page 1 of 1" over an empty list needs no separate case for it.
 - A page beyond the last one clamps to the last one. Narrowing the filter therefore moves the page
   on its own, and moving to page 9 of 3 shows page 3 rather than nothing.
-- `resize` keeps the first row the view was showing, so the page moves to wherever that row now
+- `resize` keeps the first row the view was showing, so the page moves to wherever that row
   falls. Resizing is a change of magnification, not a jump to the top.
 
 ```ts
@@ -942,11 +1144,11 @@ An event fires only when something actually moved: a write that changes nothing
 | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `write`    | the row's `key`             | Once per row admitted, written over, or moved to a different place, in the order the table wrote them. A listener that wants the row reads it back.                        |
 | `remove`   | the row's `key`             | Once per row taken out, in the order the table removed them. A `clear` is the exception; see its row.                                                                      |
-| `sort`     | every current `TableOrder`  | Whenever the term list's content changes, carrying the whole list as it now stands.                                                                                        |
-| `filter`   | every current `TableFilter` | Whenever the filter list's content changes, carrying the whole list as it now stands.                                                                                      |
+| `sort`     | every current `TableOrder`  | Whenever the term list's content changes, carrying the whole list as it stands.                                                                                            |
+| `filter`   | every current `TableFilter` | Whenever the filter list's content changes, carrying the whole list as it stands.                                                                                          |
 | `select`   | the picked `TableKey` set   | Whenever the picked set changes, carrying the whole set — including when removing rows pruned it.                                                                          |
 | `expand`   | the opened `TableKey` set   | Whenever the opened set changes, carrying the whole set — including when removing rows pruned it.                                                                          |
-| `paginate` | the `page` now shown        | Whenever the paged window moves: a `move`, a `resize`, and a clamp caused by a narrower filter or by rows leaving.                                                         |
+| `paginate` | the `page` shown            | Whenever the paged window moves: a `move`, a `resize`, and a clamp caused by a narrower filter or by rows leaving.                                                         |
 | `clear`    | nothing                     | On a completed `clear`. It is the whole announcement of that reset: no `remove`, no `sort`, no `filter`, no `select`, no `expand`, and no `paginate` is emitted beside it. |
 
 A payload is owned by the listener. `sort` and `filter` carry the whole axis because a single term is
@@ -1163,7 +1365,7 @@ a host can check against the same number the package checks against.
 They bind at the schema door and the value door, and which door a limit sits at is the whole story.
 
 **The schema door reports.** `auditTable` counts columns, choices, names, strings, total text, and
-total nodes — `meta` included, since it is retained like everything else — and returns one human
+total nodes — `meta` included, because it is retained like everything else — and returns one human
 diagnostic per breach. `createTable` raises `SCHEMA` carrying them and `parseTable` refuses the
 schema, so no over-budget schema is ever held.
 
@@ -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
@@ -1432,7 +1642,7 @@ These invariants hold across [`src/core`](../src/core) and this guide.
     whatever it reset, so a reset of ten thousand rows is one event. `destroy` called twice does what
     calling it once did; afterwards every write raises `DESTROYED` while every getter still answers
     what the table last held, and `destroyed` reports the fact so a host need not catch to learn it.
-16. **Guards are total and parsers refuse.** No `is*` throws for any input — hostile prototype,
+16. **Guards are total and parsers refuse.** No `is*` throws for any input — unexpected prototype,
     symbol key, cycle, or depth. No `parse*` throws; each returns `undefined` on refusal. A
     guard-valid value is never refused by its parser, and every parsed result satisfies its guard.
     `isTableSchema` is therefore semantic and not merely structural: it is the exact shape plus an
@@ -1491,7 +1701,7 @@ this package answers today through a mechanism it already exposes.
 | Grouping and aggregation     | out           | Group headers, subtotals, and rollups add a second row kind that is not a row, and a fold that is not a filter. `view` stays a flat list of the rows the table holds.                                                                                                                                                                                                                                                         |
 | Tree and hierarchical rows   | out           | A parent key would make `view` a traversal rather than a projection, and expansion would mean "show children" instead of "this row is open". Expansion here says only which rows are open.                                                                                                                                                                                                                                    |
 | Editing transactions         | out           | A staged edit set with commit and rollback is a second store beside the row store, and two writers that can disagree. A host that needs one holds the pending values and calls `update` once.                                                                                                                                                                                                                                 |
-| Undo and history             | out           | The table holds the rows now. A stack of everything before is a host concern with a host's retention policy, built over the same `update` and `remove` calls.                                                                                                                                                                                                                                                                 |
+| Undo and history             | out           | The table holds the rows. A stack of everything before is a host concern with a host's retention policy, built over the same `update` and `remove` calls.                                                                                                                                                                                                                                                                     |
 | Async data sources           | host          | Every read here is synchronous, so `view` is right the instant anything moves. Fetching, paging a server, and reconciling a response are the host's; it reads the lens and calls `add` or `clear`.                                                                                                                                                                                                                            |
 | Server-side paging           | seam          | `sort.orders()`, `filter.filters()`, `pagination.offset`, and `pagination.limit` are already the shape a query asks for, in the vocabulary `@orkestrel/database` uses.                                                                                                                                                                                                                                                        |
 | Row count budget             | out           | A table legitimately holds a million rows. The budgets bound one schema's declarations, which arrive from a wire; how many rows a host holds is the host's memory to spend.                                                                                                                                                                                                                                                   |
@@ -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
 
@@ -1536,7 +1746,7 @@ this package answers today through a mechanism it already exposes.
   `compareCells`, `admitsFilter`, `matchesFilter`, `filterRows`, `sortRows`, `auditTable`,
   `serializeTable`, `serializeRows`, and the budgets.
 - [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — every guard against
-  valid, off-shape, and hostile input, plus guard/parser soundness in both directions.
+  valid, off-shape, and untrusted input, plus guard/parser soundness in both directions.
 - [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseTable`, `parseRows`,
   the coercions, identity at the parse door, and the canonical byte-stable round trip.
 - [`tests/src/core/cloners.test.ts`](../tests/src/core/cloners.test.ts) — every clone is owned,

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`