@orkestrel/scaffold 0.0.119 → 0.0.121

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -1,10 +1,10 @@
1
1
  # Table
2
2
 
3
- > The environment-agnostic tabular document: a `TableSchema` declaring the columns, a `Table`
3
+ > The environment-agnostic tabular document: a `GridSchema` declaring the columns, a `Grid`
4
4
  > holding the rows given against it, and one lens of sort, filter, and page deciding which of them
5
5
  > the view shows.
6
6
 
7
- The core renders nothing and names no host type. **A grid, a report,
7
+ The core renders nothing and names no host type. **A table, a report,
8
8
  a terminal listing, and a CSV export are the same abstraction.** They all hold a set of records,
9
9
  order them, narrow them, and show a stretch of them. What differs is who draws the result, and
10
10
  drawing belongs to each host. The browser face binds native table elements to that same document.
@@ -15,8 +15,8 @@ second copy of an answer can go stale. A write validates all of itself before an
15
15
  announces itself after it has.
16
16
 
17
17
  The core refuses rather than throws. Every guard returns `false` off-shape rather than throwing,
18
- every parser returns `undefined` on refusal, and every row the table hands back is a frozen owned
19
- copy. Table-owned refusals raise `TableError`, and each one names a caller mistake.
18
+ every parser returns `undefined` on refusal, and every row the grid hands back is a frozen owned
19
+ copy. Grid-owned refusals raise `GridError`, and each one names a caller mistake.
20
20
 
21
21
  ## Surface
22
22
 
@@ -26,19 +26,19 @@ subclasses. They validate declared members and refuse transparent proxies and un
26
26
  The core surface is exported from `@orkestrel/table` ([`src/core`](../src/core)); the native binding
27
27
  surface comes from `@orkestrel/table/browser` ([`src/browser`](../src/browser)). The manager
28
28
  classes and the key-set shell they compose are the module's internal declarations: they stay out
29
- of the barrel, so no consumer can construct one, and each constructor takes the table's emitter
30
- and closures over state `Table` keeps private, which is why they are internal rather than
29
+ of the barrel, so no consumer can construct one, and each constructor takes the grid's emitter
30
+ and closures over state `Grid` keeps private, which is why they are internal rather than
31
31
  published. Every other declaration is reachable from the barrel, so a consumer holds the
32
32
  mechanisms the package uses on itself.
33
33
 
34
- ### Open a table
34
+ ### Open a grid
35
35
 
36
- Open a table, narrow it, order it, and read the rows to draw:
36
+ Open a grid, narrow it, order it, and read the rows to draw:
37
37
 
38
38
  ```ts
39
- import { createTable } from '@orkestrel/table'
39
+ import { createGrid } from '@orkestrel/table'
40
40
 
41
- const table = createTable(
41
+ const grid = createGrid(
42
42
  {
43
43
  label: 'People',
44
44
  key: 'id',
@@ -58,36 +58,36 @@ const table = createTable(
58
58
  },
59
59
  )
60
60
 
61
- table.filter.set({ column: 'name', operator: 'contains', text: 'a' })
62
- table.sort.set({ column: 'age', direction: 'descending' })
61
+ grid.filter.set({ column: 'name', operator: 'contains', text: 'a' })
62
+ grid.sort.set({ column: 'age', direction: 'descending' })
63
63
 
64
- table.count // 3 — every name holds a lowercase 'a'
65
- table.pagination.count // 2 — two pages of two
66
- table.view.map((row) => row.name) // ['Grace', 'Alan'] — page one, oldest first
64
+ grid.count // 3 — every name holds a lowercase 'a'
65
+ grid.pagination.count // 2 — two pages of two
66
+ grid.view.map((row) => row.name) // ['Grace', 'Alan'] — page one, oldest first
67
67
  ```
68
68
 
69
69
  ### Native binding
70
70
 
71
71
  These declarations belong to the browser entry.
72
72
 
73
- | Name | Kind | Signature | Summary |
74
- | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
75
- | `TableBinding` | class | `new (element: HTMLTableElement, document: TableInterface, options?: TableBindingOptions) => TableBindingInterface` | Retains keyed native rows while projecting every core table manager. |
76
- | `TableBindingInterface` | interface | `{ element, document, destroyed, emitter, refresh(), destroy() }` | Binds native table elements to a borrowed core document. |
77
- | `TableBindingOptions` | interface | `{ row?, detail?, scope?, describe?, on?, error? }` | Configures row ownership, detail presentation, scoped controls, and event listeners. |
78
- | `TableRange` | interface | `{ first, last, count, page, pages, limit }` | Describes the displayed page within the filtered rows. |
79
- | `TableSortDescription` | interface | `{ column, direction, priority, count }` | Describes a column's direction and one-based priority among active sort orders. |
80
- | `TableExpansion` | interface | `{ key, expanded }` | Proposes one row's next expansion state in a cancelable expand request. |
81
- | `TableBindingEventMap` | type | `{ readonly sort: readonly [event: CustomEvent<readonly TableOrder[]>]; readonly expand: readonly [event: CustomEvent<readonly TableExpansion[]>]; readonly render: readonly []; readonly error: readonly [error: unknown]; }` | Announces cancelable sorting and expanding, completed rendering, and failed DOM operations. |
82
- | `TableRenderHandler` | type | `(element: HTMLTableRowElement, row: TableRow) => void` | Patches the contents of a retained row without moving or replacing that row. |
83
- | `TableProjection` | interface | `{ schema, rows }` | Holds a validated native table projection for constructing a core document. |
84
- | `TableBindingErrorCode` | type | `'STRUCTURE'` | Names a native binding failure at its structure, rendering, or lifecycle boundary. |
85
- | `TableBindingError` | class | `new (code: TableBindingErrorCode, message: string) => TableBindingError` | Represents a native table binding failure with a machine-readable code. |
86
- | `isTableBindingError` | function | `(value: unknown) => value is TableBindingError` | Checks whether a caught value is a native table binding error. |
87
- | `createTableBinding` | function | `(element: HTMLTableElement, document: TableInterface, options?: TableBindingOptions) => TableBindingInterface` | Creates a native table binding with one retained row owner. |
88
- | `readTable` | function | `(element: HTMLTableElement) => TableProjection` | Reads declared header metadata and explicit row keys into a validated core projection. |
89
- | `readTableSchema` | function | `(element: HTMLTableElement) => TableSchema` | Reads and validates explicit native header metadata. |
90
- | `readTableRows` | function | `(schema: TableSchema, elements: readonly HTMLTableRowElement[]) => readonly TableRow[]` | Reads explicit keys and declared direct cells against a core schema. |
73
+ | Name | Kind | Signature | Summary |
74
+ | ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
75
+ | `TableBinding` | class | `new (element: HTMLTableElement, document: GridInterface, options?: TableBindingOptions) => TableBindingInterface` | Retains keyed native rows while projecting every core grid manager. |
76
+ | `TableBindingInterface` | interface | `{ element, document, destroyed, emitter, refresh(), destroy() }` | Binds native table elements to a borrowed core document. |
77
+ | `TableBindingOptions` | interface | `{ row?, detail?, scope?, describe?, on?, error? }` | Configures row ownership, detail presentation, scoped controls, and event listeners. |
78
+ | `GridRange` | interface | `{ first, last, count, page, pages, limit }` | Describes the displayed page within the filtered rows. |
79
+ | `GridSortDescription` | interface | `{ column, direction, priority, count }` | Describes a column's direction and one-based priority among active sort orders. |
80
+ | `GridExpansion` | interface | `{ key, expanded }` | Proposes one row's next expansion state in a cancelable expand request. |
81
+ | `TableBindingEventMap` | type | `{ readonly sort: readonly [event: CustomEvent<readonly GridOrder[]>]; readonly expand: readonly [event: CustomEvent<readonly GridExpansion[]>]; readonly render: readonly []; readonly error: readonly [error: unknown]; }` | Announces cancelable sorting and expanding, completed rendering, and failed DOM operations. |
82
+ | `GridRenderHandler` | type | `(element: HTMLTableRowElement, row: GridRow) => void` | Patches the contents of a retained row without moving or replacing that row. |
83
+ | `GridProjection` | interface | `{ schema, rows }` | Holds a validated native table projection for constructing a core document. |
84
+ | `TableBindingErrorCode` | type | `'STRUCTURE'` | Names a native binding failure at its structure, rendering, or lifecycle boundary. |
85
+ | `TableBindingError` | class | `new (code: TableBindingErrorCode, message: string) => TableBindingError` | Represents a native table binding failure with a machine-readable code. |
86
+ | `isTableBindingError` | function | `(value: unknown) => value is TableBindingError` | Checks whether a caught value is a native table binding error. |
87
+ | `createTableBinding` | function | `(element: HTMLTableElement, document: GridInterface, options?: TableBindingOptions) => TableBindingInterface` | Creates a native table binding with one retained row owner. |
88
+ | `readTable` | function | `(element: HTMLTableElement) => GridProjection` | Reads declared header metadata and explicit row keys into a validated core projection. |
89
+ | `readTableSchema` | function | `(element: HTMLTableElement) => GridSchema` | Reads and validates explicit native header metadata. |
90
+ | `readTableRows` | function | `(schema: GridSchema, elements: readonly HTMLTableRowElement[]) => readonly GridRow[]` | Reads explicit keys and declared direct cells against a core schema. |
91
91
 
92
92
  ### Enhance authored rows
93
93
 
@@ -100,7 +100,7 @@ choice array as JSON in data-table-choices. Nested tables supply no headers or c
100
100
  This browser example constructs the document before binding it.
101
101
 
102
102
  ```ts
103
- import { createTable } from '@orkestrel/table'
103
+ import { createGrid } from '@orkestrel/table'
104
104
  import { createTableBinding, readTable } from '@orkestrel/table/browser'
105
105
 
106
106
  const element = document.createElement('table')
@@ -109,14 +109,14 @@ element.innerHTML =
109
109
  '<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>'
110
110
  document.body.append(element)
111
111
  const projection = readTable(element)
112
- const table = createTable(projection.schema, { rows: projection.rows })
113
- const binding = createTableBinding(element, table)
114
- table.filter.set({ column: 'name', operator: 'contains', text: 'Ash' })
112
+ const grid = createGrid(projection.schema, { rows: projection.rows })
113
+ const binding = createTableBinding(element, grid)
114
+ grid.filter.set({ column: 'name', operator: 'contains', text: 'Ash' })
115
115
  binding.refresh()
116
116
  element.tBodies[0]?.rows.length // 1
117
117
  binding.destroy()
118
118
  element.tBodies[0]?.rows.length // 2: restored in core store order
119
- table.destroyed // false
119
+ grid.destroyed // false
120
120
  element.remove()
121
121
  ```
122
122
 
@@ -174,7 +174,7 @@ numbered page window; presentation classes belong to the host.
174
174
  This scoped binding example customizes wording while retaining native control labels.
175
175
 
176
176
  ```ts
177
- import { createTable } from '@orkestrel/table'
177
+ import { createGrid } from '@orkestrel/table'
178
178
  import { createTableBinding, readTable } from '@orkestrel/table/browser'
179
179
 
180
180
  const scope = document.createElement('section')
@@ -184,8 +184,8 @@ document.body.append(scope)
184
184
  const element = scope.querySelector('table')
185
185
  if (element === null) throw new Error('Missing account table')
186
186
  const projection = readTable(element)
187
- const table = createTable(projection.schema, { rows: projection.rows, limit: 1 })
188
- const binding = createTableBinding(element, table, {
187
+ const grid = createGrid(projection.schema, { rows: projection.rows, limit: 1 })
188
+ const binding = createTableBinding(element, grid, {
189
189
  scope,
190
190
  describe: {
191
191
  range: ({ first, last, count }) => `${first}–${last} of ${count} accounts`,
@@ -198,7 +198,7 @@ const binding = createTableBinding(element, table, {
198
198
  })
199
199
  // Keep the binding while the page is mounted; release it before removing the scope.
200
200
  binding.destroy()
201
- table.destroy()
201
+ grid.destroy()
202
202
  scope.remove()
203
203
  ```
204
204
 
@@ -222,7 +222,7 @@ import {
222
222
  readTableRows,
223
223
  readTableSchema,
224
224
  } from '@orkestrel/table/browser'
225
- import { createTable, matchesTableRow } from '@orkestrel/table'
225
+ import { createGrid, matchesGridRow } from '@orkestrel/table'
226
226
 
227
227
  const element = document.createElement('table')
228
228
  element.setAttribute('data-table-key', 'id')
@@ -230,10 +230,10 @@ element.innerHTML =
230
230
  '<thead><tr><th data-table-column="id" data-table-cell="text">Reference</th></tr></thead><tbody></tbody>'
231
231
  const schema = readTableSchema(element)
232
232
  const rows = readTableRows(schema, []) // []
233
- const table = createTable(schema, { rows })
234
- const binding = new TableBinding(element, table)
233
+ const grid = createGrid(schema, { rows })
234
+ const binding = new TableBinding(element, grid)
235
235
  binding.destroy()
236
- matchesTableRow({ id: 'ash' }, { id: 'ash' }) // true
236
+ matchesGridRow({ id: 'ash' }, { id: 'ash' }) // true
237
237
  isTableBindingError(new TableBindingError('STRUCTURE', 'Missing identity')) // true
238
238
  ```
239
239
 
@@ -242,9 +242,9 @@ isTableBindingError(new TableBindingError('STRUCTURE', 'Missing identity')) // t
242
242
  Replacement removes omitted optional cells while preserving the identity and its manager state.
243
243
 
244
244
  ```ts
245
- import { createTable } from '@orkestrel/table'
245
+ import { createGrid } from '@orkestrel/table'
246
246
 
247
- const table = createTable(
247
+ const grid = createGrid(
248
248
  {
249
249
  key: 'id',
250
250
  columns: [
@@ -254,31 +254,29 @@ const table = createTable(
254
254
  },
255
255
  { rows: [{ id: 'ash', name: 'Ash' }] },
256
256
  )
257
- table.selection.select('ash')
258
- table.rows.replace({ id: 'ash' }) // true
259
- table.rows.row('ash') // { id: 'ash' }
260
- table.selection.keys.has('ash') // true
257
+ grid.selection.select('ash')
258
+ grid.rows.replace({ id: 'ash' }) // true
259
+ grid.rows.row('ash') // { id: 'ash' }
260
+ grid.selection.keys.has('ash') // true
261
261
  ```
262
262
 
263
263
  ### Row equality
264
264
 
265
265
  This helper belongs to the core entry.
266
266
 
267
- | Name | Kind | Signature | Summary |
268
- | ----------------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ |
269
- | `matchesTableRow` | function | `(left: TableRow \| undefined, right: TableRow) => boolean` | Compares complete row values independently of their snapshot identities. |
267
+ | Name | Kind | Signature | Summary |
268
+ | ---------------- | -------- | --------------------------------------------------------- | ------------------------------------------------------------------------ |
269
+ | `matchesGridRow` | function | `(left: GridRow \| undefined, right: GridRow) => boolean` | Compares complete row values independently of their snapshot identities. |
270
270
 
271
271
  ### Rows, cells, and columns
272
272
 
273
- The document itself — what a table declares and what one row of it holds. All data, no behavior.
274
-
275
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
273
+ The document itself — what a grid declares and what one row of it holds. All data, no behavior.
276
274
 
277
275
  | Name | Kind | Signature | Summary |
278
276
  | -------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
279
- | `TableKey` | type | `string` | Represents a row's identity — a `string`, carried in the cell the schema's `key` names. |
280
- | `TableCell` | type | `string \| number \| boolean` | Represents every value a cell can hold — a `string`, a `number`, or a `boolean`. |
281
- | `TableRow` | type | `Readonly<Record<string, TableCell>>` | Represents one row, keyed by column. A column nobody has filled has no key here. |
277
+ | `GridKey` | type | `string` | Represents a row's identity — a `string`, carried in the cell the schema's `key` names. |
278
+ | `GridCell` | type | `string \| number \| boolean` | Represents every value a cell can hold — a `string`, a `number`, or a `boolean`. |
279
+ | `GridRow` | type | `Readonly<Record<string, GridCell>>` | Represents one row, keyed by column. A column nobody has filled has no key here. |
282
280
  | `ColumnCell` | type | `'text' \| 'number' \| 'flag' \| 'choice'` | Names what a column's cells hold — the discriminant that fixes the column's options, its comparison, and the filters that apply to it. |
283
281
  | `ColumnChoice` | interface | `{ value, label, help? }` | Represents one value a `choice` column offers — `value` is stored, `label` is read, and `help` explains. |
284
282
  | `ColumnBase` | interface | `{ key, label?, help?, hidden?, meta? }` | Describes what every column carries, whatever its cells hold — the name a row's cell uses, the text a reader sees, whether a host draws the column, and the metadata a host attaches to it. |
@@ -286,177 +284,165 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
286
284
  | `NumberColumn` | interface | `{ cell }` | Represents a column of numbers, compared by magnitude. |
287
285
  | `FlagColumn` | interface | `{ cell }` | Represents a column of yes-or-no answers, compared false before true. |
288
286
  | `ChoiceColumn` | interface | `{ cell, choices }` | Represents a column drawn from a declared list, compared by the order that list declares. It requires `choices`. |
289
- | `TableColumn` | type | `TextColumn \| NumberColumn \| FlagColumn \| ChoiceColumn` | Represents any column a schema can declare — the union discriminated on `cell`. |
290
- | `TableSchema` | interface | `{ name?, label?, help?, key, columns }` | Holds everything a table declares about itself — how the table is described, which column carries row identity, and the columns it declares, in the order it declares them. |
287
+ | `GridColumn` | type | `TextColumn \| NumberColumn \| FlagColumn \| ChoiceColumn` | Represents any column a schema can declare — the union discriminated on `cell`. |
288
+ | `GridSchema` | interface | `{ name?, label?, help?, key, columns }` | Holds everything a grid declares about itself — how the grid is described, which column carries row identity, and the columns it declares, in the order it declares them. |
291
289
 
292
290
  ### The lens
293
291
 
294
- The axes a table reads its rows through, and the slots that replace what a column's cell fixes.
295
-
296
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
292
+ The axes a grid reads its rows through, and the slots that replace what a column's cell fixes.
297
293
 
298
- | Name | Kind | Signature | Summary |
299
- | ---------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
300
- | `TableTerm` | interface | `{ column }` | Represents one entry of a lens list — the `column` it names. A sort term and a filter each hold one, which is why the two share a list engine. |
301
- | `TableDirection` | type | `'ascending' \| 'descending'` | Names which way a column sorts. A column nobody has sorted carries no term at all. |
302
- | `TableOrder` | interface | `{ column, direction }` | Represents one column's place in the sort — the `column` and its `direction`. The list is read left to right. |
303
- | `FilterOperator` | type | `'contains' \| 'between' \| 'equals'` | Names how a filter tests a cell — the operator each filter carries. |
304
- | `ContainsFilter` | interface | `{ column, operator, text }` | Keeps the rows whose cell holds this `text` somewhere inside it. |
305
- | `BetweenFilter` | interface | `{ column, operator, minimum, maximum }` | Keeps the rows whose cell falls between `minimum` and `maximum`, both included, compared the way the column compares. |
306
- | `EqualsFilter` | interface | `{ column, operator, value }` | Keeps the rows whose cell holds exactly this `value`. |
307
- | `TableFilter` | type | `ContainsFilter \| BetweenFilter \| EqualsFilter` | Represents any filter a table can hold — the union discriminated on `operator`. |
308
- | `CellComparator` | type | `(left: TableCell \| undefined, right: TableCell \| undefined) => number` | Compares two cells of one column, replacing what its `cell` fixes. Always describes ascending order; direction is applied afterwards. |
309
- | `CellMatcher` | type | `(cell: TableCell \| undefined, filter: TableFilter) => boolean` | Tests one column's cell against a filter, replacing what its `cell` fixes. Receives every filter the table holds against that column. |
294
+ | Name | Kind | Signature | Summary |
295
+ | ---------------- | --------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
296
+ | `GridTerm` | interface | `{ column }` | Represents one entry of a lens list — the `column` it names. A sort term and a filter each hold one, which is why the two share a list engine. |
297
+ | `GridDirection` | type | `'ascending' \| 'descending'` | Names which way a column sorts. A column nobody has sorted carries no term at all. |
298
+ | `GridOrder` | interface | `{ column, direction }` | Represents one column's place in the sort — the `column` and its `direction`. The list is read left to right. |
299
+ | `FilterOperator` | type | `'contains' \| 'between' \| 'equals'` | Names how a filter tests a cell — the operator each filter carries. |
300
+ | `ContainsFilter` | interface | `{ column, operator, text }` | Keeps the rows whose cell holds this `text` somewhere inside it. |
301
+ | `BetweenFilter` | interface | `{ column, operator, minimum, maximum }` | Keeps the rows whose cell falls between `minimum` and `maximum`, both included, compared the way the column compares. |
302
+ | `EqualsFilter` | interface | `{ column, operator, value }` | Keeps the rows whose cell holds exactly this `value`. |
303
+ | `GridFilter` | type | `ContainsFilter \| BetweenFilter \| EqualsFilter` | Represents any filter a grid can hold — the union discriminated on `operator`. |
304
+ | `CellComparator` | type | `(left: GridCell \| undefined, right: GridCell \| undefined) => number` | Compares two cells of one column, replacing what its `cell` fixes. Always describes ascending order; direction is applied afterwards. |
305
+ | `CellMatcher` | type | `(cell: GridCell \| undefined, filter: GridFilter) => boolean` | Tests one column's cell against a filter, replacing what its `cell` fixes. Receives every filter the grid holds against that column. |
310
306
 
311
- ### The table
307
+ ### The grid
312
308
 
313
309
  The entity, its managers, its factory, its contract, and the error it raises.
314
310
 
315
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
316
-
317
- | Name | Kind | Signature | Summary |
318
- | ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
319
- | `Table` | class | `new (schema: TableSchema, options?: TableOptions) => TableInterface` | Holds a schema, its rows, and the lens through which they are read, implementing `TableInterface` exactly. |
320
- | `TableInterface` | interface | `{ emitter, schema, rows, sort, filter, selection, expansion, pagination, view, count, destroyed, clear(), destroy() }` | Represents a table: what it declares, the rows it holds, and the lens it reads them through. |
321
- | `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. |
322
- | `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. |
323
- | `TableEventMap` | type | `{ readonly write: readonly [key: TableKey]; readonly remove: readonly [key: TableKey]; readonly sort: readonly [orders: readonly TableOrder[]]; readonly filter: readonly [filters: readonly TableFilter[]]; readonly select: readonly [keys: ReadonlySet<TableKey>]; readonly expand: readonly [keys: ReadonlySet<TableKey>]; readonly paginate: readonly [page: number]; readonly clear: readonly []; }` | Lists everything a table announces, mapping each event to the payload its listeners receive. |
324
- | `RowManagerInterface` | interface | `{ row(), rows(), add(), update(), replace(), move(), remove() }` | Manages the rows a table holds, in the order it holds them. |
325
- | `SortManagerInterface` | interface | `{ order(), orders(), set(), remove() }` | Manages the order a table reads its rows in. |
326
- | `FilterManagerInterface` | interface | `{ filter(), filters(), set(), remove() }` | Manages which rows a table keeps. |
327
- | `SelectionManagerInterface` | interface | `{ keys, select(), clear(), toggle() }` | Manages the rows somebody has picked. |
328
- | `ExpansionManagerInterface` | interface | `{ keys, expand(), clear(), toggle() }` | Manages the rows somebody has opened up. |
329
- | `PaginationManagerInterface` | interface | `{ page, limit, offset, count, move(), resize() }` | Manages which stretch of the filtered rows the view shows. |
330
- | `TableError` | class | `new (code: TableErrorCode, message: string, context?: JSONRecord) => TableError` | Represents an error raised by the table domain — a machine-readable `code` and optional structured `context`. |
331
- | `TableErrorCode` | type | `'SCHEMA' \| 'COLUMN' \| 'KEY' \| 'CELL' \| 'DESTROYED'` | Names the reason a `TableError` carries — the machine-readable code a `catch` branches on. |
332
- | `isTableError` | function | `(input: unknown) => input is TableError` | Determines whether a caught value is a table error, so a `catch` branches on `code` without an assertion. |
333
-
334
- `TableInterface`'s readonly data members stay here, in its `Shape` cell, rather than in
311
+ | Name | Kind | Signature | Summary |
312
+ | ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
313
+ | `Grid` | class | `new (schema: GridSchema, options?: GridOptions) => GridInterface` | Holds a schema, its rows, and the lens through which they are read, implementing `GridInterface` exactly. |
314
+ | `GridInterface` | interface | `{ emitter, schema, rows, sort, filter, selection, expansion, pagination, view, count, destroyed, clear(), destroy() }` | Represents a grid: what it declares, the rows it holds, and the lens it reads them through. |
315
+ | `createGrid` | function | `(schema: GridSchema, options?: GridOptions) => GridInterface` | Opens a grid against a schema. The schema is copied, and the copy is what the grid declares. |
316
+ | `GridOptions` | interface | `{ on?, error?, rows?, comparators?, matchers?, limit? }` | Describes how to open a grid — 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. |
317
+ | `GridEventMap` | type | `{ readonly write: readonly [key: GridKey]; readonly remove: readonly [key: GridKey]; readonly sort: readonly [orders: readonly GridOrder[]]; readonly filter: readonly [filters: readonly GridFilter[]]; readonly select: readonly [keys: ReadonlySet<GridKey>]; readonly expand: readonly [keys: ReadonlySet<GridKey>]; readonly paginate: readonly [page: number]; readonly clear: readonly []; }` | Lists everything a grid announces, mapping each event to the payload its listeners receive. |
318
+ | `RowManagerInterface` | interface | `{ row(), rows(), add(), update(), replace(), move(), remove() }` | Manages the rows a grid holds, in the order it holds them. |
319
+ | `SortManagerInterface` | interface | `{ order(), orders(), set(), remove() }` | Manages the order a grid reads its rows in. |
320
+ | `FilterManagerInterface` | interface | `{ filter(), filters(), set(), remove() }` | Manages which rows a grid keeps. |
321
+ | `SelectionManagerInterface` | interface | `{ keys, select(), clear(), toggle() }` | Manages the rows somebody has picked. |
322
+ | `ExpansionManagerInterface` | interface | `{ keys, expand(), clear(), toggle() }` | Manages the rows somebody has opened up. |
323
+ | `PaginationManagerInterface` | interface | `{ page, limit, offset, count, move(), resize() }` | Manages which stretch of the filtered rows the view shows. |
324
+ | `GridError` | class | `new (code: GridErrorCode, message: string, context?: JSONRecord) => GridError` | Represents an error raised by the grid domain — a machine-readable `code` and optional structured `context`. |
325
+ | `GridErrorCode` | type | `'SCHEMA' \| 'COLUMN' \| 'KEY' \| 'CELL' \| 'DESTROYED'` | Names the reason a `GridError` carries — the machine-readable code a `catch` branches on. |
326
+ | `isGridError` | function | `(input: unknown) => input is GridError` | Determines whether a caught value is a grid error, so a `catch` branches on `code` without an assertion. |
327
+
328
+ `GridInterface`'s readonly data members stay here, in its `Signature` cell, rather than in
335
329
  `## Methods`, and each manager's own readonly members sit in that manager's cell. Every
336
330
  call-signature member is documented under [Methods](#methods).
337
331
 
338
332
  The members spelled `count` answer different questions, because each is the lone tally of the
339
- entity it belongs to. `table.count` is **rows** — how many the filter admits, before the page narrows them.
340
- `table.pagination.count` is **pages** — how many the admitted rows fill.
333
+ entity it belongs to. `grid.count` is **rows** — how many the filter admits, before the page narrows them.
334
+ `grid.pagination.count` is **pages** — how many the admitted rows fill.
341
335
 
342
- Each manager class is constructed by `Table` and stays out of the barrel, so no consumer can
343
- construct one. Its constructor takes the table's emitter and a set of closures over state the
344
- owning table keeps private, which is what keeps every store single-owned, so the class is internal
345
- and its interface is the published contract. A consumer writing its own table composes `Table`, or writes
336
+ Each manager class is constructed by `Grid` and stays out of the barrel, so no consumer can
337
+ construct one. Its constructor takes the grid's emitter and a set of closures over state the
338
+ owning grid keeps private, which is what keeps every store single-owned, so the class is internal
339
+ and its interface is the published contract. A consumer writing its own grid composes `Grid`, or writes
346
340
  its own managers against the manager interfaces and reads these classes as the working reference.
347
341
 
348
342
  ### Constants
349
343
 
350
- The cell registry and the budgets. The registry is frozen, so a shared list cannot be rewritten
351
- under a consumer.
344
+ The cell registry and the column budget. The registry is frozen, so a shared list cannot be
345
+ rewritten under a consumer. The other schema budgets are `@orkestrel/contract` exports; § Budgets
346
+ lists them.
352
347
 
353
- A `Shape` cell holds the constant's declared type.
354
-
355
- | Name | Kind | Signature | Summary |
356
- | -------------- | ----- | ----------------------- | --------------------------------------------------------------------------------------------- |
357
- | `COLUMN_CELLS` | const | `readonly ColumnCell[]` | Lists every column cell, in the order declared by the public contract. |
358
- | `COLUMN_LIMIT` | const | `256` | Names the maximum number of columns one schema may declare: 256. |
359
- | `CHOICE_LIMIT` | const | `1024` | Names the maximum number of choices one `choice` column may offer: 1024. |
360
- | `NAME_LIMIT` | const | `128` | Names the maximum length of a schema name or column key: 128 UTF-16 code units. |
361
- | `STRING_LIMIT` | const | `65536` | Names the maximum length of any single retained string: 65536 UTF-16 code units. |
362
- | `TEXT_LIMIT` | const | `1048576` | Names the maximum total length of every string one schema retains: 1048576 UTF-16 code units. |
363
- | `NODE_LIMIT` | const | `16384` | Names the maximum total number of records, arrays, and leaves one schema retains: 16384. |
348
+ | Name | Kind | Signature | Summary |
349
+ | -------------- | ----- | ----------------------- | ---------------------------------------------------------------------- |
350
+ | `COLUMN_CELLS` | const | `readonly ColumnCell[]` | Lists every column cell, in the order declared by the public contract. |
351
+ | `COLUMN_LIMIT` | const | `256` | Names the maximum number of columns one schema may declare: 256. |
364
352
 
365
353
  ### Guards
366
354
 
367
355
  Total `is*` guards over unknown input. None throws, none coerces, and each returns `false` for
368
356
  anything off-shape — including an unexpected prototype, a symbol key, or a cyclic value.
369
357
 
370
- In a guard table a `Shape` cell holds the type the guard narrows to.
371
-
372
- | Name | Kind | Signature | Summary |
373
- | ------------------------- | -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
374
- | `isTableCell` | function | `(input: unknown) => input is TableCell` | Determines whether an unknown value has a table cell shape — a string, a finite number, or a boolean. |
375
- | `isTableRow` | function | `(input: unknown) => input is TableRow` | Determines whether an unknown value is a record whose every own key is a string and every value a `TableCell`. |
376
- | `isColumnCell` | function | `(input: unknown) => input is ColumnCell` | Determines whether an unknown value is a declared column cell. |
377
- | `isColumnChoice` | function | `(input: unknown) => input is ColumnChoice` | Determines whether an unknown value is one exact `ColumnChoice` record; an unknown member refuses it. |
378
- | `isTableColumn` | function | `(input: unknown) => input is TableColumn` | Determines whether an unknown value is one exact discriminated `TableColumn`, checked against its cell's own options. |
379
- | `isStructuralTableSchema` | function | `(input: unknown) => input is TableSchema` | Determines whether an unknown value has the exact shape of a `TableSchema` — the shape alone, with no domain check. |
380
- | `isTableSchema` | function | `(input: unknown) => input is TableSchema` | Determines whether an unknown value is a `TableSchema` a table can be opened against — the exact shape, and an audit that finds nothing. |
358
+ | Name | Kind | Signature | Summary |
359
+ | ------------------------ | -------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
360
+ | `isGridCell` | function | `(input: unknown) => input is GridCell` | Determines whether an unknown value has a grid cell shape — a string, a finite number, or a boolean. |
361
+ | `isGridRow` | function | `(input: unknown) => input is GridRow` | Determines whether an unknown value is a record whose every own key is a string and every value a `GridCell`. |
362
+ | `isColumnCell` | function | `(input: unknown) => input is ColumnCell` | Determines whether an unknown value is a declared column cell. |
363
+ | `isColumnChoice` | function | `(input: unknown) => input is ColumnChoice` | Determines whether an unknown value is one exact `ColumnChoice` record; an unknown member refuses it. |
364
+ | `isGridColumn` | function | `(input: unknown) => input is GridColumn` | Determines whether an unknown value is one exact discriminated `GridColumn`, checked against its cell's own options. |
365
+ | `isStructuralGridSchema` | function | `(input: unknown) => input is GridSchema` | Determines whether an unknown value has the exact shape of a `GridSchema` — the shape alone, with no domain check. |
366
+ | `isGridSchema` | function | `(input: unknown) => input is GridSchema` | Determines whether an unknown value is a `GridSchema` a grid can be opened against — the exact shape, and an audit that finds nothing. |
381
367
 
382
368
  The schema guards answer about a schema, and which one to reach for is which question you are asking.
383
- `isStructuralTableSchema` asks whether the shape is exact: every declared member present and typed,
384
- and nothing else there. `isTableSchema` asks that and then asks `auditTable`, so it refuses a
369
+ `isStructuralGridSchema` asks whether the shape is exact: every declared member present and typed,
370
+ and nothing else there. `isGridSchema` asks that and then asks `auditGrid`, so it refuses a
385
371
  schema-shaped value carrying a domain fault or a budget breach — a `key` naming no declared column,
386
372
  a column key declared twice, a `choice` column offering nothing. It is the guard the parsers read.
387
- The `Table` constructor asks in a different order. It guards the value it was handed, owns a copy
373
+ The `Grid` constructor asks in a different order. It guards the value it was handed, owns a copy
388
374
  of it, then guards and audits that copy and keeps that same object. Its `SCHEMA` message carries
389
375
  the audit diagnostics when the owned copy reaches the audit, and names
390
- `The schema is not a table schema` when the copy fails the guard the handed value passed. It also
376
+ `The schema is not a grid schema` when the copy fails the guard the handed value passed. It also
391
377
  names `column "<key>" has metadata that cannot be owned` when the column's `meta` answers the
392
- guard's read and the clone's read differently, the message `cloneSchema` raises and the
378
+ guard's read and the clone's read differently, the message `cloneGridSchema` raises and the
393
379
  constructor rethrows unchanged.
394
380
 
395
- `isTableSchema`, the constructor, and `parseTable` agree on every schema whose reads are stable,
381
+ `isGridSchema`, the constructor, and `parseGrid` agree on every schema whose reads are stable,
396
382
  which is every schema made of ordinary declared data. They part where a foreign object answers a
397
383
  property read with something other than the value a clone of it holds — a `meta` behind a `get`
398
- trap is the shipped case. `isTableSchema` admits such a schema, because it reads it once and the
384
+ trap is the shipped case. `isGridSchema` admits such a schema, because it reads it once and the
399
385
  read answers. The constructor refuses it, because it guards the copy it owns rather than the object
400
- it read, and `parseTable` refuses it too, because it re-guards its own projection. Reach for the
386
+ it read, and `parseGrid` refuses it too, because it re-guards its own projection. Reach for the
401
387
  structural guard where you mean to run the audit yourself and read its diagnostics.
402
388
 
403
389
  ### Helpers
404
390
 
405
- The pure leaves the table composes: the column lookup, the identity read, the key-set engine, the
391
+ The pure leaves the grid composes: the column lookup, the identity read, the key-set engine, the
406
392
  lens-list operations, the cell gate, the comparison, the filter tests, the row passes, the
407
- audit, and the wire projections. `computeKeys`, `matchesTerms`, `filterRows`, and `sortRows`
408
- propagate exceptions from supplied callbacks; `serializeTable` raises `SCHEMA` for a `meta` no clone
393
+ audit, and the wire projections. `computeKeys`, `matchesTerms`, `filterGridRows`, and `sortGridRows`
394
+ propagate exceptions from supplied callbacks; `serializeGrid` raises `SCHEMA` for a `meta` no clone
409
395
  can own. The other helpers are total over ordinary declared inputs, subject to the core's
410
396
  reflection-failure boundary described later.
411
397
 
412
- | Name | Kind | Signature | Summary |
413
- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
414
- | `extractColumn` | function | `(schema: TableSchema, key: string) => TableColumn \| undefined` | Finds one column by key; `undefined` when the schema declares no such column. |
415
- | `extractKey` | function | `(schema: TableSchema, row: TableRow) => TableKey \| undefined` | Reads one row's declared identity; `undefined` when its key cell is missing, empty, or not a string. |
416
- | `computeKeys` | function | `(known: readonly TableKey[], current: ReadonlySet<TableKey>, input: TableKey \| readonly TableKey[] \| undefined, include: (included: boolean) => boolean) => ReadonlySet<TableKey> \| undefined` | Computes one atomic 0/1/N membership change over the keys a caller may address — the engine selection and expansion share. |
417
- | `mergeTerms` | function | `<Term extends TableTerm>(current: readonly Term[], requested: readonly Term[]) => readonly Term[]` | Merges lens terms into a column-keyed list, replacing the entry that names the same column — the `set` write. |
418
- | `removeTerms` | function | `<Term extends TableTerm>(current: readonly Term[], columns: readonly string[]) => readonly Term[]` | Removes every lens term naming one of the given columns — the drop `sort.remove` and `filter.remove` share. |
419
- | `matchesTerms` | function | `<Term extends TableTerm>(left: readonly Term[], right: readonly Term[], equal: (left: Term, right: Term) => boolean) => boolean` | Checks whether two lens lists hold the same terms in the same order, with the supplied test deciding the operands. |
420
- | `matchesCell` | function | `(column: TableColumn, value: unknown) => value is TableCell` | Checks whether one column can hold a value — the shape gate every write and every seed passes through. |
421
- | `compareCells` | function | `(column: TableColumn, left: TableCell \| undefined, right: TableCell \| undefined) => number` | Compares two of one column's cells the way its `cell` fixes, describing ascending order. |
422
- | `admitsFilter` | function | `(column: TableColumn, filter: TableFilter) => boolean` | Checks whether one column admits a filter and every operand it carries — the gate `filter.set` and `matchesFilter` share. |
423
- | `matchesFilter` | function | `(column: TableColumn, cell: TableCell \| undefined, filter: TableFilter) => boolean` | Tests one of a column's cells against one filter the way its `cell` fixes. |
424
- | `filterRows` | function | `(schema: TableSchema, rows: readonly TableRow[], filters: readonly TableFilter[], matchers?: Readonly<Record<string, CellMatcher>>) => readonly TableRow[]` | Keeps the rows every filter accepts, in the order given; a supplied `CellMatcher` replaces the default per column. |
425
- | `sortRows` | function | `(schema: TableSchema, rows: readonly TableRow[], orders: readonly TableOrder[], comparators?: Readonly<Record<string, CellComparator>>) => readonly TableRow[]` | Orders rows by the terms given, stably; a supplied `CellComparator` replaces the default per column. |
426
- | `auditTable` | function | `(schema: TableSchema) => readonly string[]` | Audits a structurally valid schema for domain faults and budget breaches, returning human diagnostics. |
427
- | `serializeTable` | function | `(schema: TableSchema) => JSONRecord` | Projects a schema into JSON in declaration order, dropping every absent member; raises `SCHEMA` for a `meta` it cannot own. |
428
- | `serializeRows` | function | `(schema: TableSchema, rows: readonly TableRow[]) => readonly JSONRecord[]` | Projects rows into JSON with each row's cells in the schema's column order, dropping every absent cell. |
398
+ | Name | Kind | Signature | Summary |
399
+ | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
400
+ | `extractColumn` | function | `(schema: GridSchema, key: string) => GridColumn \| undefined` | Finds one column by key; `undefined` when the schema declares no such column. |
401
+ | `extractGridKey` | function | `(schema: GridSchema, row: GridRow) => GridKey \| undefined` | Reads one row's declared identity; `undefined` when its key cell is missing, empty, or not a string. |
402
+ | `computeKeys` | function | `(known: readonly GridKey[], current: ReadonlySet<GridKey>, input: GridKey \| readonly GridKey[] \| undefined, include: (included: boolean) => boolean) => ReadonlySet<GridKey> \| undefined` | Computes one atomic 0/1/N membership change over the keys a caller may address — the engine selection and expansion share. |
403
+ | `mergeTerms` | function | `<Term extends GridTerm>(current: readonly Term[], requested: readonly Term[]) => readonly Term[]` | Merges lens terms into a column-keyed list, replacing the entry that names the same column — the `set` write. |
404
+ | `removeTerms` | function | `<Term extends GridTerm>(current: readonly Term[], columns: readonly string[]) => readonly Term[]` | Removes every lens term naming one of the given columns — the drop `sort.remove` and `filter.remove` share. |
405
+ | `matchesTerms` | function | `<Term extends GridTerm>(left: readonly Term[], right: readonly Term[], equal: (left: Term, right: Term) => boolean) => boolean` | Checks whether two lens lists hold the same terms in the same order, with the supplied test deciding the operands. |
406
+ | `matchesCell` | function | `(column: GridColumn, value: unknown) => value is GridCell` | Checks whether one column can hold a value — the shape gate every write and every seed passes through. |
407
+ | `compareCells` | function | `(column: GridColumn, left: GridCell \| undefined, right: GridCell \| undefined) => number` | Compares two of one column's cells the way its `cell` fixes, describing ascending order. |
408
+ | `admitsFilter` | function | `(column: GridColumn, filter: GridFilter) => boolean` | Checks whether one column admits a filter and every operand it carries — the gate `filter.set` and `matchesFilter` share. |
409
+ | `matchesFilter` | function | `(column: GridColumn, cell: GridCell \| undefined, filter: GridFilter) => boolean` | Tests one of a column's cells against one filter the way its `cell` fixes. |
410
+ | `filterGridRows` | function | `(schema: GridSchema, rows: readonly GridRow[], filters: readonly GridFilter[], matchers?: Readonly<Record<string, CellMatcher>>) => readonly GridRow[]` | Keeps the rows every filter accepts, in the order given; a supplied `CellMatcher` replaces the default per column. |
411
+ | `sortGridRows` | function | `(schema: GridSchema, rows: readonly GridRow[], orders: readonly GridOrder[], comparators?: Readonly<Record<string, CellComparator>>) => readonly GridRow[]` | Orders rows by the terms given, stably; a supplied `CellComparator` replaces the default per column. |
412
+ | `auditGrid` | function | `(schema: GridSchema) => readonly string[]` | Audits a structurally valid schema for domain faults and budget breaches, returning human diagnostics. |
413
+ | `serializeGrid` | function | `(schema: GridSchema) => JSONRecord` | Projects a schema into JSON in declaration order, dropping every absent member; raises `SCHEMA` for a `meta` it cannot own. |
414
+ | `serializeRows` | function | `(schema: GridSchema, rows: readonly GridRow[]) => readonly JSONRecord[]` | Projects rows into JSON with each row's cells in the schema's column order, dropping every absent cell. |
429
415
 
430
416
  ### Cloners
431
417
 
432
- Owned frozen snapshots. The table takes one of the schema at construction and one of every row at
433
- admission, so a later edit to the object a caller passed changes nothing inside the table, and no
434
- row the table hands back is a live internal reference.
418
+ Owned frozen snapshots. The grid takes one of the schema at construction and one of every row at
419
+ admission, so a later edit to the object a caller passed changes nothing inside the grid, and no
420
+ row the grid hands back is a live internal reference.
435
421
 
436
- | Name | Kind | Signature | Summary |
437
- | ------------- | -------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
438
- | `cloneRow` | function | `(row: TableRow) => TableRow` | Clones one row into an owned frozen snapshot. |
439
- | `cloneSchema` | function | `(schema: TableSchema) => TableSchema` | 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. |
422
+ | Name | Kind | Signature | Summary |
423
+ | ----------------- | -------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
424
+ | `cloneRow` | function | `(row: GridRow) => GridRow` | Clones one row into an owned frozen snapshot. |
425
+ | `cloneGridSchema` | function | `(schema: GridSchema) => GridSchema` | 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. |
440
426
 
441
427
  `cloneRow` cannot fail for an ordinary row record, subject to the core's reflection-failure boundary
442
- described later. `cloneSchema` can also fail when a column's `meta` holds something no clone can own, such as a
428
+ described later. `cloneGridSchema` can also fail when a column's `meta` holds something no clone can own, such as a
443
429
  record that refers back to itself. `meta` is typed as JSON and a cycle satisfies that type, so the
444
- refusal is a `TableError` coded `SCHEMA` rather than a silent partial copy. `createTable` never reaches
445
- it for a schema whose reads are stable, because `isTableColumn` admits only bounded, exactly ownable
430
+ refusal is a `GridError` coded `SCHEMA` rather than a silent partial copy. `createGrid` never reaches
431
+ it for a schema whose reads are stable, because `isGridColumn` admits only bounded, exactly ownable
446
432
  JSON there and refuses such a schema first; a `meta` that answers the guard's read with ownable JSON
447
433
  and the clone's read with something no clone can own reaches it, and it refuses
448
434
  with `column "<key>" has metadata that cannot be owned`. This is the door a caller cloning or
449
- serializing a schema on its own meets, and `serializeTable` refuses the same value the same way.
435
+ serializing a schema on its own meets, and `serializeGrid` refuses the same value the same way.
450
436
 
451
437
  ### Parsers
452
438
 
453
439
  The wire boundary. Each returns `undefined` on refusal rather than throwing, and each returns an
454
440
  owned value rather than the caller's.
455
441
 
456
- | Name | Kind | Signature | Summary |
457
- | ------------ | -------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
458
- | `parseTable` | function | `(input: unknown) => TableSchema \| undefined` | Parses unknown wire data into an owned, structurally valid, semantically sound table schema. |
459
- | `parseRows` | function | `(schema: TableSchema, input: unknown) => readonly TableRow[] \| undefined` | Parses unknown wire data into owned rows against one table schema, coercing a numeric string and `'true'` / `'false'`. |
442
+ | Name | Kind | Signature | Summary |
443
+ | ----------- | -------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
444
+ | `parseGrid` | function | `(input: unknown) => GridSchema \| undefined` | Parses unknown wire data into an owned, structurally valid, semantically sound grid schema. |
445
+ | `parseRows` | function | `(schema: GridSchema, input: unknown) => readonly GridRow[] \| undefined` | Parses unknown wire data into owned rows against one grid schema, coercing a numeric string and `'true'` / `'false'`. |
460
446
 
461
447
  **Reflection failures.** A TypeScript shape does not guarantee that reflection succeeds. An ordinary
462
448
  helper or cloner may propagate a throw from a proxy trap or accessor. Guards and parsers contain that
@@ -491,7 +477,7 @@ const name: TextColumn = { cell: 'text', key: 'name', label: 'Name' }
491
477
  ```
492
478
 
493
479
  `contains` is the operator a filter bar reaches for, and it compares **case-sensitively**. Case
494
- folding is a locale decision this package cannot make for a host, so a table that wants it supplies
480
+ folding is a locale decision this package cannot make for a host, so a grid that wants it supplies
495
481
  a `CellMatcher` for that column. The same is true of collation: `text` compares with the language's
496
482
  own string order, not a locale-aware collator.
497
483
 
@@ -506,7 +492,7 @@ const age: NumberColumn = { cell: 'number', key: 'age', label: 'Age' }
506
492
  ```
507
493
 
508
494
  A cell must be a finite number. `NaN` and either infinity are values a column cannot hold, so a
509
- write carrying one raises `TableError` coded `CELL`.
495
+ write carrying one raises `GridError` coded `CELL`.
510
496
 
511
497
  ### flag
512
498
 
@@ -520,7 +506,7 @@ const active: FlagColumn = { cell: 'flag', key: 'active', label: 'Active' }
520
506
 
521
507
  `flag` takes `equals` and nothing else. `contains` has no meaning against a boolean and `between`
522
508
  carries bounds it could not order usefully, so a filter carrying either against a `flag` column
523
- raises `TableError` coded `CELL`.
509
+ raises `GridError` coded `CELL`.
524
510
 
525
511
  ### choice
526
512
 
@@ -609,7 +595,7 @@ needs the check adds it at its own door.
609
595
 
610
596
  ### meta
611
597
 
612
- `ColumnBase.meta` is a bounded JSON carrier for whatever the schema declines to model. The table
598
+ `ColumnBase.meta` is a bounded JSON carrier for whatever the schema declines to model. The grid
613
599
  never reads it, no comparison sees it, no filter tests it, and it round-trips verbatim key for key.
614
600
  This package defines no key in it, so every key belongs to the host: an alignment, a number format,
615
601
  a pixel width, an icon name.
@@ -626,9 +612,9 @@ question before it writes needs the same answer. `extractColumn` finds the colum
626
612
 
627
613
  ```ts
628
614
  import { extractColumn, matchesCell } from '@orkestrel/table'
629
- import type { TableSchema } from '@orkestrel/table'
615
+ import type { GridSchema } from '@orkestrel/table'
630
616
 
631
- const schema: TableSchema = {
617
+ const schema: GridSchema = {
632
618
  key: 'id',
633
619
  columns: [
634
620
  { cell: 'text', key: 'id' },
@@ -651,13 +637,13 @@ naming a column the schema does not declare has nothing to be measured against.
651
637
 
652
638
  ### Overriding a column
653
639
 
654
- `TableOptions.comparators` and `TableOptions.matchers` are keyed by column key, and each entry
640
+ `GridOptions.comparators` and `GridOptions.matchers` are keyed by column key, and each entry
655
641
  replaces — for that column alone — the comparison or the test its `cell` fixes. They are the reason
656
- no function belongs in the schema: behavior is supplied where the table is opened, and the schema
642
+ no function belongs in the schema: behavior is supplied where the grid is opened, and the schema
657
643
  stays data that crosses a wire whole.
658
644
 
659
645
  ```ts
660
- import { createTable } from '@orkestrel/table'
646
+ import { createGrid } from '@orkestrel/table'
661
647
  import type { CellComparator, CellMatcher } from '@orkestrel/table'
662
648
 
663
649
  const natural: CellComparator = (left, right) =>
@@ -669,7 +655,7 @@ const loose: CellMatcher = (cell, filter) =>
669
655
  .toLowerCase()
670
656
  .includes(filter.text.toLowerCase())
671
657
 
672
- const table = createTable(
658
+ const grid = createGrid(
673
659
  {
674
660
  key: 'id',
675
661
  columns: [
@@ -684,36 +670,36 @@ const table = createTable(
684
670
  },
685
671
  )
686
672
 
687
- table.filter.set({ column: 'name', operator: 'contains', text: 'ADA' })
688
- table.count // 1 — the matcher folded the case; the default would not have
673
+ grid.filter.set({ column: 'name', operator: 'contains', text: 'ADA' })
674
+ grid.count // 1 — the matcher folded the case; the default would not have
689
675
  ```
690
676
 
691
677
  An override receives `undefined` for a row carrying no cell there, so it decides absence for itself.
692
- A comparator always describes ascending order and `TableDirection` is applied afterwards, so one
678
+ A comparator always describes ascending order and `GridDirection` is applied afterwards, so one
693
679
  comparator serves either direction. An override for a column the schema does not declare is never
694
680
  consulted and is not an error: the schema decides which columns exist, and the option only says how
695
681
  one of them behaves.
696
682
 
697
683
  ## Identity
698
684
 
699
- Every row carries its own identity, in the cell named by `TableSchema.key`, as a non-empty string.
685
+ Every row carries its own identity, in the cell named by `GridSchema.key`, as a non-empty string.
700
686
 
701
- `key` is **required**. It must name a declared column, and the table refuses a row whose cell there
687
+ `key` is **required**. It must name a declared column, and the grid refuses a row whose cell there
702
688
  is missing, empty, or not a string. There is no default column, no positional fallback, and no key
703
689
  generation: an index is a position, and a position is not an identity — the moment a sort moves a
704
690
  row, a position that named it names somebody else.
705
691
 
706
692
  That is a deliberate divergence from `@orkestrel/database`, whose `DEFAULT_PRIMARY` assumes `id`
707
- when a table declares no primary column. A database row arrives from a store that already gave it a
708
- key, so assuming the usual name saves a declaration and costs nothing. A table's rows arrive from a
693
+ when a grid declares no primary column. A database row arrives from a store that already gave it a
694
+ key, so assuming the usual name saves a declaration and costs nothing. A grid's rows arrive from a
709
695
  caller who may have joined, projected, or invented them in the browser, so the same assumption picks
710
696
  a column that may not exist, or picks one that exists and is not unique. Declaring the key is one
711
697
  line, and it is the line every refusal described later is measured against.
712
698
 
713
699
  ```ts
714
- import { createTable, isTableError } from '@orkestrel/table'
700
+ import { createGrid, isGridError } from '@orkestrel/table'
715
701
 
716
- const table = createTable({
702
+ const grid = createGrid({
717
703
  key: 'id',
718
704
  columns: [
719
705
  { cell: 'text', key: 'id' },
@@ -721,44 +707,44 @@ const table = createTable({
721
707
  ],
722
708
  })
723
709
 
724
- table.rows.add({ id: '7', name: 'Ada' })
710
+ grid.rows.add({ id: '7', name: 'Ada' })
725
711
 
726
712
  try {
727
- table.rows.add({ id: '7', name: 'Grace' })
713
+ grid.rows.add({ id: '7', name: 'Grace' })
728
714
  } catch (error) {
729
- if (isTableError(error)) error.code // 'KEY' — already taken
715
+ if (isGridError(error)) error.code // 'KEY' — already taken
730
716
  }
731
717
 
732
718
  try {
733
- table.rows.add({ name: 'Alan' })
719
+ grid.rows.add({ name: 'Alan' })
734
720
  } catch (error) {
735
- if (isTableError(error)) error.code // 'KEY' — no identity at all
721
+ if (isGridError(error)) error.code // 'KEY' — no identity at all
736
722
  }
737
723
 
738
- table.rows.rows().length // 1 — a refused write changed nothing
724
+ grid.rows.rows().length // 1 — a refused write changed nothing
739
725
  ```
740
726
 
741
727
  These rules follow from it, and each one is a refusal rather than a repair:
742
728
 
743
- - **A key is unique.** `add` raises `KEY` for a key the table already holds, and for a key repeated
729
+ - **A key is unique.** `add` raises `KEY` for a key the grid already holds, and for a key repeated
744
730
  inside one batch. Every row in the batch is checked before any is admitted, so one duplicate
745
731
  admits none of them.
746
732
  - **A key cannot move.** `update` merges: the cells given replace the cells held and the cells left
747
733
  out stay as they are. A row is found by the key it carries, so writing a different key writes a
748
734
  different row — or writes nothing, if that row does not exist.
749
- - **A row is owned.** The table clones and freezes a row at admission, so the object a caller keeps
750
- is no longer the row the table holds, and `row()` and `rows()` hand back frozen copies rather than
735
+ - **A row is owned.** The grid clones and freezes a row at admission, so the object a caller keeps
736
+ is no longer the row the grid holds, and `row()` and `rows()` hand back frozen copies rather than
751
737
  internal references.
752
738
  - **Selection and expansion hold keys.** Never rows, never positions. A pick survives a sort, a
753
- filter, and a page turn, and a row that leaves the table takes its key out of both sets with it.
739
+ filter, and a page turn, and a row that leaves the grid takes its key out of both sets with it.
754
740
 
755
741
  `update` is where that second rule is felt. It merges, so a call carries only the cells it means to
756
742
  change, and the row it writes is the one carrying the key it names — never a rename.
757
743
 
758
744
  ```ts
759
- import { createTable } from '@orkestrel/table'
745
+ import { createGrid } from '@orkestrel/table'
760
746
 
761
- const table = createTable(
747
+ const grid = createGrid(
762
748
  {
763
749
  key: 'id',
764
750
  columns: [
@@ -770,24 +756,24 @@ const table = createTable(
770
756
  { rows: [{ id: '1', name: 'Ada', age: 36 }] },
771
757
  )
772
758
 
773
- table.rows.update({ id: '1', age: 37 }) // true
774
- table.rows.row('1') // { id: '1', name: 'Ada', age: 37 } — `name` was left out and stayed
775
- table.rows.update({ id: '9', name: 'Nobody' }) // false — no row carries that key
776
- table.rows.rows().length // 1 — a different key is a different row, so nothing was added
759
+ grid.rows.update({ id: '1', age: 37 }) // true
760
+ grid.rows.row('1') // { id: '1', name: 'Ada', age: 37 } — `name` was left out and stayed
761
+ grid.rows.update({ id: '9', name: 'Nobody' }) // false — no row carries that key
762
+ grid.rows.rows().length // 1 — a different key is a different row, so nothing was added
777
763
  ```
778
764
 
779
- `extractKey` is the read those rules are built on, and it is exported because a host doing the same
765
+ `extractGridKey` is the read those rules are built on, and it is exported because a host doing the same
780
766
  check before it calls needs the same answer.
781
767
 
782
768
  ```ts
783
- import { extractKey } from '@orkestrel/table'
784
- import type { TableSchema } from '@orkestrel/table'
769
+ import { extractGridKey } from '@orkestrel/table'
770
+ import type { GridSchema } from '@orkestrel/table'
785
771
 
786
- const schema: TableSchema = { key: 'id', columns: [{ cell: 'text', key: 'id' }] }
772
+ const schema: GridSchema = { key: 'id', columns: [{ cell: 'text', key: 'id' }] }
787
773
 
788
- extractKey(schema, { id: '7' }) // '7'
789
- extractKey(schema, { id: '' }) // undefined — empty is not an identity
790
- extractKey(schema, { name: 'Ada' }) // undefined — no key cell at all
774
+ extractGridKey(schema, { id: '7' }) // '7'
775
+ extractGridKey(schema, { id: '' }) // undefined — empty is not an identity
776
+ extractGridKey(schema, { name: 'Ada' }) // undefined — no key cell at all
791
777
  ```
792
778
 
793
779
  ## The lens
@@ -799,15 +785,15 @@ before sorting pages the wrong rows onto every page.
799
785
 
800
786
  ### Sorting
801
787
 
802
- The table holds at most one term per column and applies them in the order they were set. The first
788
+ The grid holds at most one term per column and applies them in the order they were set. The first
803
789
  term decides, and each later term breaks the tie the terms before it left. Rows no term separates
804
- keep the order the table holds them in, so the sort is stable and the row store's own order is the
790
+ keep the order the grid holds them in, so the sort is stable and the row store's own order is the
805
791
  final tiebreak.
806
792
 
807
793
  ```ts
808
- import { createTable } from '@orkestrel/table'
794
+ import { createGrid } from '@orkestrel/table'
809
795
 
810
- const table = createTable(
796
+ const grid = createGrid(
811
797
  {
812
798
  key: 'id',
813
799
  columns: [
@@ -825,13 +811,13 @@ const table = createTable(
825
811
  },
826
812
  )
827
813
 
828
- table.sort.set([
814
+ grid.sort.set([
829
815
  { column: 'team', direction: 'ascending' },
830
816
  { column: 'age', direction: 'descending' },
831
817
  ])
832
818
 
833
- table.view.map((row) => row.id) // ['1', '3', '2'] — team first, age breaking the tie
834
- table.sort.order('age') // { column: 'age', direction: 'descending' }
819
+ grid.view.map((row) => row.id) // ['1', '3', '2'] — team first, age breaking the tie
820
+ grid.sort.order('age') // { column: 'age', direction: 'descending' }
835
821
  ```
836
822
 
837
823
  There is no cycling verb. Which direction a heading offers next is the host's decision, so a host
@@ -847,9 +833,9 @@ holding a lens of its own gets the same list arithmetic without writing it again
847
833
 
848
834
  ```ts
849
835
  import { matchesTerms, mergeTerms, removeTerms } from '@orkestrel/table'
850
- import type { TableOrder } from '@orkestrel/table'
836
+ import type { GridOrder } from '@orkestrel/table'
851
837
 
852
- const current: readonly TableOrder[] = [
838
+ const current: readonly GridOrder[] = [
853
839
  { column: 'team', direction: 'ascending' },
854
840
  { column: 'age', direction: 'descending' },
855
841
  ]
@@ -860,14 +846,14 @@ matchesTerms(next, current, (order, other) => order.direction === other.directio
860
846
  removeTerms(next, ['team']).map((order) => order.column) // ['age']
861
847
  ```
862
848
 
863
- `sortRows` is the same pass without a table, for a caller that has rows and terms and no entity. It
849
+ `sortGridRows` is the same pass without a grid, for a caller that has rows and terms and no entity. It
864
850
  sorts a copy, so the list handed to it never moves.
865
851
 
866
852
  ```ts
867
- import { sortRows } from '@orkestrel/table'
868
- import type { TableSchema } from '@orkestrel/table'
853
+ import { sortGridRows } from '@orkestrel/table'
854
+ import type { GridSchema } from '@orkestrel/table'
869
855
 
870
- const schema: TableSchema = {
856
+ const schema: GridSchema = {
871
857
  key: 'id',
872
858
  columns: [
873
859
  { cell: 'text', key: 'id' },
@@ -876,26 +862,26 @@ const schema: TableSchema = {
876
862
  }
877
863
  const rows = [{ id: '1', age: 40 }, { id: '2' }, { id: '3', age: 30 }]
878
864
 
879
- sortRows(schema, rows, [{ column: 'age', direction: 'ascending' }]).map((row) => row.id)
865
+ sortGridRows(schema, rows, [{ column: 'age', direction: 'ascending' }]).map((row) => row.id)
880
866
  // ['2', '3', '1'] — an absent cell sorts before every present one
881
- sortRows(schema, rows, []).map((row) => row.id) // ['1', '2', '3'] — no term, no movement
867
+ sortGridRows(schema, rows, []).map((row) => row.id) // ['1', '2', '3'] — no term, no movement
882
868
  rows.map((row) => row.id) // ['1', '2', '3'] — the input is untouched
883
869
  ```
884
870
 
885
871
  ### Filtering
886
872
 
887
- The table holds at most one filter per column and keeps every row all of them accept. Composition is
873
+ The grid holds at most one filter per column and keeps every row all of them accept. Composition is
888
874
  **and** in this version: there is no either-or, and no nesting.
889
875
 
890
876
  A filter names a column and carries only the operands its operator uses, so a `between` missing a
891
- bound cannot be written down. An operator the column's cell does not admit raises `TableError` coded
877
+ bound cannot be written down. An operator the column's cell does not admit raises `GridError` coded
892
878
  `CELL`, and an operand the column cannot hold raises the same — a `contains` against a `number`
893
879
  column and a `between` whose bounds are the wrong shape are both refusals, not empty results.
894
880
 
895
881
  ```ts
896
- import { createTable, isTableError } from '@orkestrel/table'
882
+ import { createGrid, isGridError } from '@orkestrel/table'
897
883
 
898
- const table = createTable(
884
+ const grid = createGrid(
899
885
  {
900
886
  key: 'id',
901
887
  columns: [
@@ -912,18 +898,18 @@ const table = createTable(
912
898
  },
913
899
  )
914
900
 
915
- table.filter.set([
901
+ grid.filter.set([
916
902
  { column: 'name', operator: 'contains', text: 'a' },
917
903
  { column: 'age', operator: 'between', minimum: 40, maximum: 50 },
918
904
  ])
919
905
 
920
- table.count // 1 — both filters, and only Grace satisfies both
921
- table.view.map((row) => row.name) // ['Grace']
906
+ grid.count // 1 — both filters, and only Grace satisfies both
907
+ grid.view.map((row) => row.name) // ['Grace']
922
908
 
923
909
  try {
924
- table.filter.set({ column: 'age', operator: 'contains', text: '4' })
910
+ grid.filter.set({ column: 'age', operator: 'contains', text: '4' })
925
911
  } catch (error) {
926
- if (isTableError(error)) error.code // 'CELL' — `contains` has no meaning against a number
912
+ if (isGridError(error)) error.code // 'CELL' — `contains` has no meaning against a number
927
913
  }
928
914
  ```
929
915
 
@@ -945,13 +931,13 @@ admitsFilter(age, { column: 'age', operator: 'equals', value: '36' }) // false
945
931
  admitsFilter(age, { column: 'name', operator: 'equals', value: 36 }) // false — the filter names another column
946
932
  ```
947
933
 
948
- `filterRows` is the same pass without a table, and it keeps the order it was given.
934
+ `filterGridRows` is the same pass without a grid, and it keeps the order it was given.
949
935
 
950
936
  ```ts
951
- import { filterRows } from '@orkestrel/table'
952
- import type { TableSchema } from '@orkestrel/table'
937
+ import { filterGridRows } from '@orkestrel/table'
938
+ import type { GridSchema } from '@orkestrel/table'
953
939
 
954
- const schema: TableSchema = {
940
+ const schema: GridSchema = {
955
941
  key: 'id',
956
942
  columns: [
957
943
  { cell: 'text', key: 'id' },
@@ -964,23 +950,23 @@ const rows = [
964
950
  { id: '3', name: 'Bob' },
965
951
  ]
966
952
 
967
- const lower = filterRows(schema, rows, [{ column: 'name', operator: 'contains', text: 'a' }])
968
- const upper = filterRows(schema, rows, [{ column: 'name', operator: 'contains', text: 'A' }])
953
+ const lower = filterGridRows(schema, rows, [{ column: 'name', operator: 'contains', text: 'a' }])
954
+ const upper = filterGridRows(schema, rows, [{ column: 'name', operator: 'contains', text: 'A' }])
969
955
 
970
956
  lower.map((row) => row.name) // ['Ada', 'Grace']
971
957
  upper.map((row) => row.name) // ['Ada'] — `contains` is case-sensitive
972
- filterRows(schema, rows, []).length // 3 — no filter refuses nothing
958
+ filterGridRows(schema, rows, []).length // 3 — no filter refuses nothing
973
959
  ```
974
960
 
975
961
  ### Pagination
976
962
 
977
963
  `page` is the state, counted from one. `offset` and `count` are worked out from it and from the rows
978
- the filter admits, so nothing here can drift out of step with what the table holds.
964
+ the filter admits, so nothing here can drift out of step with what the grid holds.
979
965
 
980
- - `limit` is how many rows a page holds, or `undefined` when the table is not paged. An unpaged table
966
+ - `limit` is how many rows a page holds, or `undefined` when the grid is not paged. An unpaged grid
981
967
  reports `page` 1, `offset` 0, and `count` 1, and its `view` is every row the filter admits.
982
968
  - `offset` counts the rows skipped, from zero, which is exactly what a database query asks for.
983
- - `count` is `max(1, ceil(rows / limit))`, so a paged table whose filter admits no rows still
969
+ - `count` is `max(1, ceil(rows / limit))`, so a paged grid whose filter admits no rows still
984
970
  reports one page, and that page's `view` is empty. There is no page zero, and a host drawing
985
971
  "page 1 of 1" over an empty list needs no separate case for it.
986
972
  - A page beyond the last one clamps to the last one. Narrowing the filter therefore moves the page
@@ -989,22 +975,22 @@ the filter admits, so nothing here can drift out of step with what the table hol
989
975
  falls. Resizing is a change of magnification, not a jump to the top.
990
976
 
991
977
  ```ts
992
- import { createTable } from '@orkestrel/table'
978
+ import { createGrid } from '@orkestrel/table'
993
979
 
994
- const table = createTable(
980
+ const grid = createGrid(
995
981
  { key: 'id', columns: [{ cell: 'text', key: 'id' }] },
996
982
  { rows: [{ id: '1' }, { id: '2' }, { id: '3' }, { id: '4' }, { id: '5' }], limit: 2 },
997
983
  )
998
984
 
999
- table.pagination.count // 3 — five rows, two to a page
1000
- table.pagination.move(9)
1001
- table.pagination.page // 3 — clamped to the last page
1002
- table.pagination.offset // 4
1003
- table.view.map((row) => row.id) // ['5']
985
+ grid.pagination.count // 3 — five rows, two to a page
986
+ grid.pagination.move(9)
987
+ grid.pagination.page // 3 — clamped to the last page
988
+ grid.pagination.offset // 4
989
+ grid.view.map((row) => row.id) // ['5']
1004
990
 
1005
- table.pagination.resize()
1006
- table.pagination.limit // undefined — not paged
1007
- table.view.length // 5
991
+ grid.pagination.resize()
992
+ grid.pagination.limit // undefined — not paged
993
+ grid.view.length // 5
1008
994
  ```
1009
995
 
1010
996
  This vocabulary is deliberately the one `@orkestrel/database` and `@orkestrel/relation` already use:
@@ -1016,53 +1002,53 @@ is in the words, so each side agrees without depending on the other.
1016
1002
 
1017
1003
  ### Selection and expansion
1018
1004
 
1019
- Selection and expansion hold `TableKey` sets and nothing else, and each offers the same verbs:
1005
+ Selection and expansion hold `GridKey` sets and nothing else, and each offers the same verbs:
1020
1006
  `select` and `expand` add, `clear` removes, and `toggle` turns one row around. Each takes no argument to mean
1021
1007
  every row, one key to mean one row, and a key list to mean those rows, and a list is checked in full
1022
1008
  before any of it moves.
1023
1009
 
1024
- Selecting with no argument picks **every row the table holds** — not every visible one. A host
1010
+ Selecting with no argument picks **every row the grid holds** — not every visible one. A host
1025
1011
  offering a header checkbox that picks the page hands that page's keys over instead, which is one
1026
1012
  line over `view` and keeps the ambiguity where the host can see it.
1027
1013
 
1028
1014
  ```ts
1029
- import { createTable } from '@orkestrel/table'
1015
+ import { createGrid } from '@orkestrel/table'
1030
1016
 
1031
- const table = createTable(
1017
+ const grid = createGrid(
1032
1018
  { key: 'id', columns: [{ cell: 'text', key: 'id' }] },
1033
1019
  { rows: [{ id: '1' }, { id: '2' }, { id: '3' }] },
1034
1020
  )
1035
1021
 
1036
- table.selection.select(table.view.map((row) => String(row.id))) // the page, not the table
1037
- table.selection.keys.size // 3
1022
+ grid.selection.select(grid.view.map((row) => String(row.id))) // the page, not the grid
1023
+ grid.selection.keys.size // 3
1038
1024
 
1039
- table.selection.toggle('2')
1040
- table.selection.keys.has('2') // false
1025
+ grid.selection.toggle('2')
1026
+ grid.selection.keys.has('2') // false
1041
1027
 
1042
- table.rows.remove('1')
1043
- table.selection.keys.has('1') // false — a row that leaves takes its key with it
1028
+ grid.rows.remove('1')
1029
+ grid.selection.keys.has('1') // false — a row that leaves takes its key with it
1044
1030
  ```
1045
1031
 
1046
1032
  What an opened row shows beside it is the host's to draw. Expansion says which rows are open and
1047
1033
  stops there.
1048
1034
 
1049
1035
  ```ts
1050
- import { createTable } from '@orkestrel/table'
1036
+ import { createGrid } from '@orkestrel/table'
1051
1037
 
1052
- const table = createTable(
1038
+ const grid = createGrid(
1053
1039
  { key: 'id', columns: [{ cell: 'text', key: 'id' }] },
1054
1040
  { rows: [{ id: '1' }, { id: '2' }, { id: '3' }] },
1055
1041
  )
1056
1042
 
1057
- table.expansion.expand() // no argument — every row the table holds
1058
- table.expansion.keys.size // 3
1043
+ grid.expansion.expand() // no argument — every row the grid holds
1044
+ grid.expansion.keys.size // 3
1059
1045
 
1060
- table.expansion.clear('2')
1061
- table.expansion.expand(['2', '9']) // false — '9' names no row, so neither one opened
1062
- table.expansion.keys.has('2') // false
1046
+ grid.expansion.clear('2')
1047
+ grid.expansion.expand(['2', '9']) // false — '9' names no row, so neither one opened
1048
+ grid.expansion.keys.has('2') // false
1063
1049
 
1064
- table.expansion.toggle('2')
1065
- table.expansion.keys.size // 3
1050
+ grid.expansion.toggle('2')
1051
+ grid.expansion.keys.size // 3
1066
1052
  ```
1067
1053
 
1068
1054
  The selection and the expansion manager are the same algorithm over their own key set, so it is
@@ -1079,10 +1065,10 @@ atomicity without writing it again.
1079
1065
 
1080
1066
  ```ts
1081
1067
  import { computeKeys } from '@orkestrel/table'
1082
- import type { TableKey } from '@orkestrel/table'
1068
+ import type { GridKey } from '@orkestrel/table'
1083
1069
 
1084
- const known: readonly TableKey[] = ['1', '2', '3']
1085
- const picked: ReadonlySet<TableKey> = new Set(['1'])
1070
+ const known: readonly GridKey[] = ['1', '2', '3']
1071
+ const picked: ReadonlySet<GridKey> = new Set(['1'])
1086
1072
 
1087
1073
  computeKeys(known, picked, '2', () => true)?.size // 2 — '2' joins '1'
1088
1074
  computeKeys(known, picked, '9', () => true) // undefined — '9' is not a key the caller may address
@@ -1092,67 +1078,67 @@ computeKeys(known, picked, undefined, (included) => !included)?.size // 2 — ev
1092
1078
 
1093
1079
  ## Lifecycle and state
1094
1080
 
1095
- A table is a live projection, not a document that settles. It has no terminal success state, no
1081
+ A grid is a live projection, not a document that settles. It has no terminal success state, no
1096
1082
  submit, and no result: rows arrive and leave for as long as the host holds it, and every read
1097
1083
  answers from what it holds at that moment.
1098
1084
 
1099
1085
  The verbs that end things end different things.
1100
1086
 
1101
- - **`clear` resets, and the table stays open.** Every row goes, and sort, filter, selection,
1102
- expansion, and the page all reset to how the table opened. The schema and the options do not move.
1103
- A cleared table takes rows again immediately.
1104
- - **`destroy` tears down, and the table stays readable.** Calling it twice does what calling it once
1105
- did. Afterwards every write raises `TableError` coded `DESTROYED`, while every getter still answers
1106
- what the table last held — so a host can read its way out of teardown without catching anything.
1087
+ - **`clear` resets, and the grid stays open.** Every row goes, and sort, filter, selection,
1088
+ expansion, and the page all reset to how the grid opened. The schema and the options do not move.
1089
+ A cleared grid takes rows again immediately.
1090
+ - **`destroy` tears down, and the grid stays readable.** Calling it twice does what calling it once
1091
+ did. Afterwards every write raises `GridError` coded `DESTROYED`, while every getter still answers
1092
+ what the grid last held — so a host can read its way out of teardown without catching anything.
1107
1093
 
1108
- `destroyed` is the readable fact, and it exists so a host handed a `TableInterface` it did not
1094
+ `destroyed` is the readable fact, and it exists so a host handed a `GridInterface` it did not
1109
1095
  construct does not have to use an exception as control flow.
1110
1096
 
1111
1097
  ```ts
1112
- import { createTable, isTableError } from '@orkestrel/table'
1098
+ import { createGrid, isGridError } from '@orkestrel/table'
1113
1099
 
1114
- const table = createTable(
1100
+ const grid = createGrid(
1115
1101
  { key: 'id', columns: [{ cell: 'text', key: 'id' }] },
1116
1102
  { rows: [{ id: '1' }, { id: '2' }] },
1117
1103
  )
1118
1104
 
1119
- table.clear()
1120
- table.count // 0
1121
- table.rows.add({ id: '3' }) // a cleared table is still open
1105
+ grid.clear()
1106
+ grid.count // 0
1107
+ grid.rows.add({ id: '3' }) // a cleared grid is still open
1122
1108
 
1123
- table.destroy()
1124
- table.destroy() // idempotent
1125
- table.destroyed // true
1126
- table.count // 1 — every getter still answers
1109
+ grid.destroy()
1110
+ grid.destroy() // idempotent
1111
+ grid.destroyed // true
1112
+ grid.count // 1 — every getter still answers
1127
1113
 
1128
1114
  try {
1129
- table.rows.add({ id: '4' })
1115
+ grid.rows.add({ id: '4' })
1130
1116
  } catch (error) {
1131
- if (isTableError(error)) error.code // 'DESTROYED'
1117
+ if (isGridError(error)) error.code // 'DESTROYED'
1132
1118
  }
1133
1119
  ```
1134
1120
 
1135
- A write is every call that could change what the table holds: `rows.add`, `rows.update`,
1121
+ A write is every call that could change what the grid holds: `rows.add`, `rows.update`,
1136
1122
  `rows.move`, `rows.remove`, `sort.set`, `sort.remove`, `filter.set`, `filter.remove`,
1137
1123
  `selection.select`, `selection.clear`, `selection.toggle`, `expansion.expand`, `expansion.clear`,
1138
- `expansion.toggle`, `pagination.move`, `pagination.resize`, and the table's own `clear`. Every one of
1124
+ `expansion.toggle`, `pagination.move`, `pagination.resize`, and the grid's own `clear`. Every one of
1139
1125
  them raises `DESTROYED` after teardown. `destroy` itself does not.
1140
1126
 
1141
1127
  ## Events
1142
1128
 
1143
- Each event carries the fact that moved. No listener sees a state the table has not finished writing.
1129
+ Each event carries the fact that moved. No listener sees a state the grid has not finished writing.
1144
1130
  An event fires only when something actually moved: a write that changes nothing announces nothing.
1145
1131
 
1146
- | Event | Payload | Fires |
1147
- | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1148
- | `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. |
1149
- | `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. |
1150
- | `sort` | every current `TableOrder` | Whenever the term list's content changes, carrying the whole list as it stands. |
1151
- | `filter` | every current `TableFilter` | Whenever the filter list's content changes, carrying the whole list as it stands. |
1152
- | `select` | the picked `TableKey` set | Whenever the picked set changes, carrying the whole set — including when removing rows pruned it. |
1153
- | `expand` | the opened `TableKey` set | Whenever the opened set changes, carrying the whole set — including when removing rows pruned it. |
1154
- | `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. |
1155
- | `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. |
1132
+ | Event | Payload | Fires |
1133
+ | ---------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1134
+ | `write` | the row's `key` | Once per row admitted, written over, or moved to a different place, in the order the grid wrote them. A listener that wants the row reads it back. |
1135
+ | `remove` | the row's `key` | Once per row taken out, in the order the grid removed them. A `clear` is the exception; see its row. |
1136
+ | `sort` | every current `GridOrder` | Whenever the term list's content changes, carrying the whole list as it stands. |
1137
+ | `filter` | every current `GridFilter` | Whenever the filter list's content changes, carrying the whole list as it stands. |
1138
+ | `select` | the picked `GridKey` set | Whenever the picked set changes, carrying the whole set — including when removing rows pruned it. |
1139
+ | `expand` | the opened `GridKey` set | Whenever the opened set changes, carrying the whole set — including when removing rows pruned it. |
1140
+ | `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. |
1141
+ | `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. |
1156
1142
 
1157
1143
  A payload is owned by the listener. `sort` and `filter` carry the whole axis because a single term is
1158
1144
  unreadable without the rest, and `select` and `expand` carry the same `ReadonlySet` shape the
@@ -1161,21 +1147,21 @@ holds moves underneath it.
1161
1147
 
1162
1148
  One call can announce more than one thing, and the order is fixed: **the rows first, then the axes
1163
1149
  they disturbed, in the order `select`, `expand`, `paginate`.** Removing two picked rows from a paged
1164
- table therefore emits `remove`, `remove`, `select`, and then `paginate` if the page had to clamp.
1150
+ grid therefore emits `remove`, `remove`, `select`, and then `paginate` if the page had to clamp.
1165
1151
 
1166
- `TableOptions.rows` seeds quietly. Seeding announces nothing at all, so a table opens silent and
1152
+ `GridOptions.rows` seeds quietly. Seeding announces nothing at all, so a grid opens silent and
1167
1153
  every later write is heard.
1168
1154
 
1169
- Wire listeners at construction through `TableOptions.on`, or afterwards through the `emitter`. Each
1155
+ Wire listeners at construction through `GridOptions.on`, or afterwards through the `emitter`. Each
1170
1156
  reaches the same typed emitter, and a listener that throws is isolated and reported to
1171
- `TableOptions.error` rather than breaking its siblings or the table.
1157
+ `GridOptions.error` rather than breaking its siblings or the grid.
1172
1158
 
1173
1159
  ```ts
1174
- import { createTable } from '@orkestrel/table'
1160
+ import { createGrid } from '@orkestrel/table'
1175
1161
 
1176
1162
  const seen: string[] = []
1177
1163
 
1178
- const table = createTable(
1164
+ const grid = createGrid(
1179
1165
  {
1180
1166
  key: 'id',
1181
1167
  columns: [
@@ -1193,12 +1179,12 @@ const table = createTable(
1193
1179
  },
1194
1180
  )
1195
1181
 
1196
- table.emitter.on('clear', () => seen.push('clear'))
1182
+ grid.emitter.on('clear', () => seen.push('clear'))
1197
1183
 
1198
- table.rows.add({ id: '2', age: 45 })
1199
- table.sort.set({ column: 'age', direction: 'ascending' })
1200
- table.sort.set({ column: 'age', direction: 'ascending' }) // the same term twice
1201
- table.clear()
1184
+ grid.rows.add({ id: '2', age: 45 })
1185
+ grid.sort.set({ column: 'age', direction: 'ascending' })
1186
+ grid.sort.set({ column: 'age', direction: 'ascending' }) // the same term twice
1187
+ grid.clear()
1202
1188
 
1203
1189
  seen // ['write 2', 'sort 1', 'clear'] — the repeated term moved nothing and said nothing
1204
1190
  ```
@@ -1206,13 +1192,13 @@ seen // ['write 2', 'sort 1', 'clear'] — the repeated term moved nothing and s
1206
1192
  ## Wire safety
1207
1193
 
1208
1194
  A schema is data, so it travels whole. It carries no function, nothing is dropped on the way, and
1209
- `serializeTable` and `parseTable` are the two ends of that trip.
1195
+ `serializeGrid` and `parseGrid` are the two ends of that trip.
1210
1196
 
1211
1197
  ```ts
1212
- import { parseTable, serializeTable } from '@orkestrel/table'
1213
- import type { TableSchema } from '@orkestrel/table'
1198
+ import { parseGrid, serializeGrid } from '@orkestrel/table'
1199
+ import type { GridSchema } from '@orkestrel/table'
1214
1200
 
1215
- const schema: TableSchema = {
1201
+ const schema: GridSchema = {
1216
1202
  name: 'people',
1217
1203
  label: 'People',
1218
1204
  key: 'id',
@@ -1222,15 +1208,15 @@ const schema: TableSchema = {
1222
1208
  ],
1223
1209
  }
1224
1210
 
1225
- const wire = JSON.stringify(serializeTable(schema))
1226
- const received = parseTable(JSON.parse(wire))
1211
+ const wire = JSON.stringify(serializeGrid(schema))
1212
+ const received = parseGrid(JSON.parse(wire))
1227
1213
 
1228
- JSON.stringify(serializeTable(received ?? schema)) === wire // true
1229
- parseTable({ key: 'id', columns: 'not a list' }) // undefined
1230
- parseTable({ columns: [{ cell: 'text', key: 'id' }] }) // undefined — no `key`
1214
+ JSON.stringify(serializeGrid(received ?? schema)) === wire // true
1215
+ parseGrid({ key: 'id', columns: 'not a list' }) // undefined
1216
+ parseGrid({ columns: [{ cell: 'text', key: 'id' }] }) // undefined — no `key`
1231
1217
  ```
1232
1218
 
1233
- The round trip is byte-stable because both projections fix the order they emit in: `serializeTable`
1219
+ The round trip is byte-stable because both projections fix the order they emit in: `serializeGrid`
1234
1220
  writes a schema's members in declaration order and a column's in the order the contract declares
1235
1221
  them, and `serializeRows` writes each row's cells in the schema's column order. Ordering is what
1236
1222
  turns "the same data" into "the same bytes", and it is the only reason a caller can compare two wire
@@ -1239,7 +1225,7 @@ forms with `===` instead of walking them.
1239
1225
  That is canonicalization, not preservation. A projection reorders whatever it was handed: an object
1240
1226
  written `columns` before `key` comes back with `key` before `columns`, because declaration order is
1241
1227
  the order the contract declares and not the order the caller typed. So the bytes settle at the first
1242
- projection, and every projection after it — of that schema, or of what `parseTable` returned from
1228
+ projection, and every projection after it — of that schema, or of what `parseGrid` returned from
1243
1229
  those bytes — reproduces them exactly. Compare two wire forms, never a wire form against arbitrary
1244
1230
  incoming bytes.
1245
1231
 
@@ -1254,13 +1240,13 @@ payload, and so does a row with no usable identity or an identity another row al
1254
1240
  `null` is a cell no column can hold, and it is the refusal a wire producer meets most often: absence
1255
1241
  here is an absent key, so a producer writing `null` for an empty field drops the key instead. There is
1256
1242
  no partial result, because a half-accepted row set is worse than a rejected one — and the door where
1257
- identity is checked is this one, so nothing that reaches the table has to be checked for it twice.
1243
+ identity is checked is this one, so nothing that reaches the grid has to be checked for it twice.
1258
1244
 
1259
1245
  ```ts
1260
1246
  import { parseRows, serializeRows } from '@orkestrel/table'
1261
- import type { TableSchema } from '@orkestrel/table'
1247
+ import type { GridSchema } from '@orkestrel/table'
1262
1248
 
1263
- const schema: TableSchema = {
1249
+ const schema: GridSchema = {
1264
1250
  key: 'id',
1265
1251
  columns: [
1266
1252
  { cell: 'text', key: 'id' },
@@ -1277,13 +1263,13 @@ parseRows(schema, [{ id: '1', colour: 'red' }]) // undefined — no such column
1277
1263
  serializeRows(schema, [{ age: 36, id: '1' }]) // [{ id: '1', age: 36 }] — schema column order
1278
1264
  ```
1279
1265
 
1280
- **What never travels is everything that is not the document.** `TableOptions` does not: `on`,
1266
+ **What never travels is everything that is not the document.** `GridOptions` does not: `on`,
1281
1267
  `error`, `comparators`, and `matchers` are functions or hold them, and a function has no wire form.
1282
1268
  Neither does live state — the sort terms, the filters, the picked and opened keys, and the page are
1283
1269
  the lens a session is looking through, not the data it is looking at. A host that wants to persist a
1284
1270
  lens reads `sort.orders()`, `filter.filters()`, `selection.keys`, and `pagination.page` and stores
1285
1271
  them at its own door, in its own format. This package ships no parser for them, because it would be
1286
- a parser for the host's decision rather than for the table's document.
1272
+ a parser for the host's decision rather than for the grid's document.
1287
1273
 
1288
1274
  The guards are the same boundary read one value at a time, and every one of them is total.
1289
1275
 
@@ -1291,55 +1277,55 @@ The guards are the same boundary read one value at a time, and every one of them
1291
1277
  import {
1292
1278
  isColumnCell,
1293
1279
  isColumnChoice,
1294
- isTableCell,
1295
- isTableColumn,
1296
- isTableRow,
1297
- isTableSchema,
1280
+ isGridCell,
1281
+ isGridColumn,
1282
+ isGridRow,
1283
+ isGridSchema,
1298
1284
  } from '@orkestrel/table'
1299
1285
 
1300
1286
  isColumnCell('choice') // true
1301
1287
  isColumnCell('date') // false — a date is `text` holding an ISO string
1302
- isTableCell(36) // true
1303
- isTableCell(null) // false — absence is an absent key, never null
1304
- isTableRow({ id: '1', age: 36 }) // true
1305
- isTableRow({ id: ['1'] }) // false
1288
+ isGridCell(36) // true
1289
+ isGridCell(null) // false — absence is an absent key, never null
1290
+ isGridRow({ id: '1', age: 36 }) // true
1291
+ isGridRow({ id: ['1'] }) // false
1306
1292
  isColumnChoice({ value: 'a', label: 'A' }) // true
1307
1293
  isColumnChoice({ value: 'a', label: 'A', colour: 'red' }) // false — an unknown member refuses it
1308
- isTableColumn({ cell: 'choice', key: 'status', choices: [] }) // true — structure only
1309
- isTableSchema({ key: 'id', columns: [{ cell: 'text', key: 'id' }] }) // true
1310
- isTableSchema({ columns: [] }) // false — `key` is required
1294
+ isGridColumn({ cell: 'choice', key: 'status', choices: [] }) // true — structure only
1295
+ isGridSchema({ key: 'id', columns: [{ cell: 'text', key: 'id' }] }) // true
1296
+ isGridSchema({ columns: [] }) // false — `key` is required
1311
1297
  ```
1312
1298
 
1313
1299
  The schema guards are where the boundary is drawn twice, because a schema can be the right shape
1314
- and still be a table nobody could open. `isStructuralTableSchema` answers the shape;
1315
- `isTableSchema` answers the shape and the audit together, and it is the single-call guard consumers
1316
- and parsers read. The constructor reads `isStructuralTableSchema` and runs `auditTable` once so its
1300
+ and still be a grid nobody could open. `isStructuralGridSchema` answers the shape;
1301
+ `isGridSchema` answers the shape and the audit together, and it is the single-call guard consumers
1302
+ and parsers read. The constructor reads `isStructuralGridSchema` and runs `auditGrid` once so its
1317
1303
  `SCHEMA` message retains the diagnostics.
1318
1304
 
1319
1305
  ```ts
1320
- import { isStructuralTableSchema, isTableSchema, parseTable } from '@orkestrel/table'
1306
+ import { isStructuralGridSchema, isGridSchema, parseGrid } from '@orkestrel/table'
1321
1307
 
1322
1308
  const unsound = { key: 'missing', columns: [{ cell: 'text', key: 'id' }] }
1323
1309
 
1324
- isStructuralTableSchema(unsound) // true — every member is present and typed
1325
- isTableSchema(unsound) // false — `key` names no declared column
1326
- parseTable(unsound) // undefined — the parser refuses exactly what the guard refuses
1327
- isStructuralTableSchema({ columns: [] }) // false — `key` is required by the shape itself
1310
+ isStructuralGridSchema(unsound) // true — every member is present and typed
1311
+ isGridSchema(unsound) // false — `key` names no declared column
1312
+ parseGrid(unsound) // undefined — the parser refuses exactly what the guard refuses
1313
+ isStructuralGridSchema({ columns: [] }) // false — `key` is required by the shape itself
1328
1314
  ```
1329
1315
 
1330
1316
  ### Owning what arrives
1331
1317
 
1332
- The cloners are how a value stops being the caller's. The table clones the schema at construction and
1318
+ The cloners are how a value stops being the caller's. The grid clones the schema at construction and
1333
1319
  every row at admission, and it clones every row it hands back. They are exported because a consumer
1334
1320
  building its own row store needs the same guarantee.
1335
1321
 
1336
1322
  Construction guards the schema it was handed, owns a copy, and then guards and audits that copy, so
1337
- the schema a table opens against is the one it validated. A schema whose property reads and stored
1323
+ the schema a grid opens against is the one it validated. A schema whose property reads and stored
1338
1324
  values disagree — a proxy answering a read with one value while holding another — is refused with
1339
1325
  `SCHEMA` instead of opened.
1340
1326
 
1341
1327
  ```ts
1342
- import { cloneRow, cloneSchema } from '@orkestrel/table'
1328
+ import { cloneRow, cloneGridSchema } from '@orkestrel/table'
1343
1329
 
1344
1330
  const row = { id: '1', age: 36 }
1345
1331
  const owned = cloneRow(row)
@@ -1347,14 +1333,16 @@ const owned = cloneRow(row)
1347
1333
  owned === row // false
1348
1334
  Object.isFrozen(owned) // true
1349
1335
 
1350
- Object.isFrozen(cloneSchema({ key: 'id', columns: [{ cell: 'text', key: 'id' }] })) // true
1336
+ Object.isFrozen(cloneGridSchema({ key: 'id', columns: [{ cell: 'text', key: 'id' }] })) // true
1351
1337
  ```
1352
1338
 
1353
1339
  ### Budgets
1354
1340
 
1355
1341
  The budgets bound how much a schema can be, so a document that arrives from a wire cannot cost
1356
- unbounded memory or unbounded scanning before anything decides to trust it. Every one is exported, so
1357
- a host can check against the same number the package checks against.
1342
+ unbounded memory or unbounded scanning before anything decides to trust it. This package exports
1343
+ `COLUMN_LIMIT`, and `@orkestrel/contract` exports `CHOICE_LIMIT`, `NAME_LIMIT`, `STRING_LIMIT`,
1344
+ `TEXT_LIMIT`, and `NODE_LIMIT`, so a host can check against the same number the package checks
1345
+ against.
1358
1346
 
1359
1347
  | Constant | Value | Unit | Bounds |
1360
1348
  | -------------- | ------- | ----------------------- | ----------------------------------------- |
@@ -1367,32 +1355,32 @@ a host can check against the same number the package checks against.
1367
1355
 
1368
1356
  They bind at the schema door and the value door, and which door a limit sits at is the whole story.
1369
1357
 
1370
- **The schema door reports.** `auditTable` counts columns, choices, names, strings, total text, and
1358
+ **The schema door reports.** `auditGrid` counts columns, choices, names, strings, total text, and
1371
1359
  total nodes — `meta` included, because it is retained like everything else — and returns one human
1372
- diagnostic per breach. `createTable` raises `SCHEMA` carrying them and `parseTable` refuses the
1360
+ diagnostic per breach. `createGrid` raises `SCHEMA` carrying them and `parseGrid` refuses the
1373
1361
  schema, so no over-budget schema is ever held.
1374
1362
 
1375
- **The value door refuses.** `matchesCell` checks `STRING_LIMIT` on any string before it consults the
1376
- column, so an over-long cell is refused before anything else looks at it. `rows.add`, `rows.update`,
1377
- and a seeded row raise `CELL`; `parseRows` returns `undefined`.
1363
+ **The value door refuses.** `matchesCell` checks `STRING_LIMIT`, from `@orkestrel/contract`, on any
1364
+ string before it consults the column, so an over-long cell is refused before anything else looks at
1365
+ it. `rows.add`, `rows.update`, and a seeded row raise `CELL`; `parseRows` returns `undefined`.
1378
1366
 
1379
- `STRING_LIMIT` is the one that stands at each door, so no string this package retains is longer
1380
- than 65536 code units whichever way it arrived.
1367
+ `STRING_LIMIT`, from `@orkestrel/contract`, is the one that stands at each door, so no string this
1368
+ package retains is longer than 65536 code units whichever way it arrived.
1381
1369
 
1382
1370
  The whole-schema ceilings are what make the arithmetic safe. Whatever the per-item limits admit,
1383
1371
  one audited schema retains at most 1048576 string code units and at most 16384 nodes, so the worst
1384
1372
  case is those ceilings rather than the product of the others.
1385
1373
 
1386
1374
  Rows and the structural read stay unbounded, each for its own reason. **Rows are not budgeted**: a
1387
- table legitimately holds a million of them, and a ceiling here would be product policy wearing a
1388
- constant's name. And the structural **read** at the parse door is not bounded either — `parseTable`
1375
+ grid legitimately holds a million of them, and a ceiling here would be product policy wearing a
1376
+ constant's name. And the structural **read** at the parse door is not bounded either — `parseGrid`
1389
1377
  copies and guards every column that arrived before the audit sees one of them, so a payload four
1390
1378
  times over `COLUMN_LIMIT` is read four times over and then refused. Bound the size of a payload at
1391
1379
  the transport that delivers it, which is the only layer holding the bytes.
1392
1380
 
1393
1381
  ### Auditing a schema
1394
1382
 
1395
- `auditTable` is the semantic pass beyond structural validation. It reports the domain faults listed
1383
+ `auditGrid` is the semantic pass beyond structural validation. It reports the domain faults listed
1396
1384
  following and every budget breach stated earlier. The shape alone cannot see them, except an unownable `meta`,
1397
1385
  which the structural guard also refuses so the doors stay in agreement:
1398
1386
 
@@ -1404,10 +1392,10 @@ which the structural guard also refuses so the doors stay in agreement:
1404
1392
  - A `choice` column offers no choice at all, so it is a column no cell could ever fill.
1405
1393
  - A column's `meta` cannot be owned as exact JSON.
1406
1394
 
1407
- The audit runs inside `createTable` and inside `parseTable`, so a consumer rarely calls it directly —
1395
+ The audit runs inside `createGrid` and inside `parseGrid`, so a consumer rarely calls it directly —
1408
1396
  but it is exported, because a schema editor wants the diagnostics before it constructs anything.
1409
- `isTableSchema` is this list's emptiness over a structurally exact value, and nothing else, so the
1410
- guard, the constructor, and the parser cannot disagree about which schemas a table can be opened
1397
+ `isGridSchema` is this list's emptiness over a structurally exact value, and nothing else, so the
1398
+ guard, the constructor, and the parser cannot disagree about which schemas a grid can be opened
1411
1399
  against. The guard is the yes-or-no; the audit is why.
1412
1400
 
1413
1401
  **It returns human diagnostics, not a machine contract.** Read them, show them, log them. Do not
@@ -1415,16 +1403,16 @@ branch on their text or parse a column key out of them: the wording is free to c
1415
1403
  diagnostics, and only the emptiness of the list is a promise. It returns a string list rather than a
1416
1404
  `Result` for exactly that reason — a `Result` would dress a diagnostic list as an outcome and invite
1417
1405
  a consumer to treat one as the other. Where a machine outcome is what you need, use the guards, or
1418
- use `parseTable` and read `undefined`.
1406
+ use `parseGrid` and read `undefined`.
1419
1407
 
1420
1408
  ```ts
1421
- import { auditTable } from '@orkestrel/table'
1409
+ import { auditGrid } from '@orkestrel/table'
1422
1410
 
1423
- auditTable({ key: 'ref', columns: [{ cell: 'text', key: 'id' }] })
1411
+ auditGrid({ key: 'ref', columns: [{ cell: 'text', key: 'id' }] })
1424
1412
  // ['schema key "ref" names no declared column']
1425
- auditTable({ key: 'age', columns: [{ cell: 'number', key: 'age' }] })
1413
+ auditGrid({ key: 'age', columns: [{ cell: 'number', key: 'age' }] })
1426
1414
  // ['schema key "age" names a number column, which holds no identity']
1427
- auditTable({
1415
+ auditGrid({
1428
1416
  key: 'id',
1429
1417
  columns: [
1430
1418
  { cell: 'text', key: 'id' },
@@ -1432,14 +1420,14 @@ auditTable({
1432
1420
  ],
1433
1421
  })
1434
1422
  // ['column "id" is declared more than once']
1435
- auditTable({ key: 'id', columns: [{ cell: 'text', key: 'id' }] }) // []
1423
+ auditGrid({ key: 'id', columns: [{ cell: 'text', key: 'id' }] }) // []
1436
1424
  ```
1437
1425
 
1438
1426
  ## Methods
1439
1427
 
1440
1428
  The public methods of the behavioral interfaces, which their classes implement exactly and add
1441
1429
  nothing to. Every readonly data member stays in the `## Surface` rows stated earlier, in each
1442
- interface's `Shape` cell, and is not repeated here.
1430
+ interface's `Signature` cell, and is not repeated here.
1443
1431
 
1444
1432
  Every other row in the Surface tables is a data shape, a union, a constant, a function, or an error
1445
1433
  class, so none of them carries a method table. `CellComparator` and `CellMatcher` are callable
@@ -1447,30 +1435,30 @@ function types with one call signature and no named members.
1447
1435
 
1448
1436
  Where a method takes no argument, one key, or a key list, that is one method with overloads rather
1449
1437
  than several methods. A list is checked in full before any of it moves, and the call returns
1450
- `true` only when every name in it names what its manager addresses: a row the table holds for
1438
+ `true` only when every name in it names what its manager addresses: a row the grid holds for
1451
1439
  `rows`, `selection`, and `expansion`, and a column the schema declares for `sort` and `filter`. So
1452
1440
  `selection.clear('9')` is `false` for a key no row carries, while `sort.remove('age')` is `true` for
1453
1441
  a declared `age` column nothing was sorting by — the column exists, and afterwards nothing sorts by
1454
1442
  it either way.
1455
1443
 
1456
- #### `TableInterface`
1444
+ #### `GridInterface`
1457
1445
 
1458
- | Method | Returns | Summary |
1459
- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
1460
- | `clear` | `void` | Puts the table back the way it opened, holding nothing. Rows, sort, filter, selection, expansion, and the page all reset. |
1461
- | `destroy` | `void` | Tears the table down. Idempotent; afterwards every write raises `DESTROYED` and every getter still answers. |
1446
+ | Method | Returns | Summary |
1447
+ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
1448
+ | `clear` | `void` | Puts the grid back the way it opened, holding nothing. Rows, sort, filter, selection, expansion, and the page all reset. |
1449
+ | `destroy` | `void` | Tears the grid down. Idempotent; afterwards every write raises `DESTROYED` and every getter still answers. |
1462
1450
 
1463
1451
  #### `RowManagerInterface`
1464
1452
 
1465
- | Method | Returns | Summary |
1466
- | --------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
1467
- | `row` | `TableRow` or `undefined` | Finds one row by key; `undefined` when the table holds no such key. |
1468
- | `rows` | `readonly TableRow[]` | Reads every row the table holds, in its own order — unfiltered, unsorted, and unpaged. |
1469
- | `add` | `void` | Takes in one row or several, appending them in the order given. Every row is checked before any is admitted. |
1470
- | `update` | `boolean` | Writes over one row or several, each found by the key it carries. The cells given replace; the cells left out stay. |
1471
- | `replace` | `boolean` | Replaces complete rows under existing keys, removing omitted cells without moving identities. |
1472
- | `move` | `boolean` | Moves one row to another place in the table's own order, counted from zero and clamped to the rows that exist. |
1473
- | `remove` | `void` or `boolean` | Takes out every row, one row, or several. Selection and expansion drop the keys of the rows that went. |
1453
+ | Method | Returns | Summary |
1454
+ | --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
1455
+ | `row` | `GridRow` or `undefined` | Finds one row by key; `undefined` when the grid holds no such key. |
1456
+ | `rows` | `readonly GridRow[]` | Reads every row the grid holds, in its own order — unfiltered, unsorted, and unpaged. |
1457
+ | `add` | `void` | Takes in one row or several, appending them in the order given. Every row is checked before any is admitted. |
1458
+ | `update` | `boolean` | Writes over one row or several, each found by the key it carries. The cells given replace; the cells left out stay. |
1459
+ | `replace` | `boolean` | Replaces complete rows under existing keys, removing omitted cells without moving identities. |
1460
+ | `move` | `boolean` | Moves one row to another place in the grid's own order, counted from zero and clamped to the rows that exist. |
1461
+ | `remove` | `void` or `boolean` | Takes out every row, one row, or several. Selection and expansion drop the keys of the rows that went. |
1474
1462
 
1475
1463
  #### `TableBindingInterface`
1476
1464
 
@@ -1481,27 +1469,27 @@ it either way.
1481
1469
 
1482
1470
  #### `SortManagerInterface`
1483
1471
 
1484
- | Method | Returns | Summary |
1485
- | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1486
- | `order` | `TableOrder` or `undefined` | Finds one column's term; `undefined` when nothing sorts that column. |
1487
- | `orders` | `readonly TableOrder[]` | Reads every term the table sorts by, first to last, in the order they decide. |
1488
- | `set` | `void` | Sorts by one column or several. A term for a column already sorted replaces its direction in place; every other term joins the end. An undeclared column raises `COLUMN`. |
1489
- | `remove` | `void` or `boolean` | Stops sorting by everything, by one column, or by several. An undeclared column returns `false` and stops nothing. |
1472
+ | Method | Returns | Summary |
1473
+ | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1474
+ | `order` | `GridOrder` or `undefined` | Finds one column's term; `undefined` when nothing sorts that column. |
1475
+ | `orders` | `readonly GridOrder[]` | Reads every term the grid sorts by, first to last, in the order they decide. |
1476
+ | `set` | `void` | Sorts by one column or several. A term for a column already sorted replaces its direction in place; every other term joins the end. An undeclared column raises `COLUMN`. |
1477
+ | `remove` | `void` or `boolean` | Stops sorting by everything, by one column, or by several. An undeclared column returns `false` and stops nothing. |
1490
1478
 
1491
1479
  #### `FilterManagerInterface`
1492
1480
 
1493
- | Method | Returns | Summary |
1494
- | --------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1495
- | `filter` | `TableFilter` or `undefined` | Finds one column's filter; `undefined` when nothing filters that column. |
1496
- | `filters` | `readonly TableFilter[]` | Reads every filter the table keeps rows by, in the order they were set. |
1497
- | `set` | `void` | Filters one column or several. A filter for a column already filtered replaces it; every other one joins the end. An undeclared column raises `COLUMN`, and a filter the column does not admit raises `CELL`. |
1498
- | `remove` | `void` or `boolean` | Stops filtering everything, one column, or several. An undeclared column returns `false` and stops nothing. |
1481
+ | Method | Returns | Summary |
1482
+ | --------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1483
+ | `filter` | `GridFilter` or `undefined` | Finds one column's filter; `undefined` when nothing filters that column. |
1484
+ | `filters` | `readonly GridFilter[]` | Reads every filter the grid keeps rows by, in the order they were set. |
1485
+ | `set` | `void` | Filters one column or several. A filter for a column already filtered replaces it; every other one joins the end. An undeclared column raises `COLUMN`, and a filter the column does not admit raises `CELL`. |
1486
+ | `remove` | `void` or `boolean` | Stops filtering everything, one column, or several. An undeclared column returns `false` and stops nothing. |
1499
1487
 
1500
1488
  #### `SelectionManagerInterface`
1501
1489
 
1502
1490
  | Method | Returns | Summary |
1503
1491
  | -------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
1504
- | `select` | `void` or `boolean` | Picks every row the table holds, one row, or several. Every row, not every visible one. |
1492
+ | `select` | `void` or `boolean` | Picks every row the grid holds, one row, or several. Every row, not every visible one. |
1505
1493
  | `clear` | `void` or `boolean` | Drops every pick, one pick, or several. A known key that was not picked still answers `true`. |
1506
1494
  | `toggle` | `boolean` | Picks one row, or drops it when it is already picked; over a list, turns each row around on its own. |
1507
1495
 
@@ -1509,7 +1497,7 @@ it either way.
1509
1497
 
1510
1498
  | Method | Returns | Summary |
1511
1499
  | -------- | ------------------- | --------------------------------------------------------------------------------------------------- |
1512
- | `expand` | `void` or `boolean` | Opens every row the table holds, one row, or several. |
1500
+ | `expand` | `void` or `boolean` | Opens every row the grid holds, one row, or several. |
1513
1501
  | `clear` | `void` or `boolean` | Closes every row, one row, or several. A known key that was not open still answers `true`. |
1514
1502
  | `toggle` | `boolean` | Opens one row, or closes it when it is already open; over a list, turns each row around on its own. |
1515
1503
 
@@ -1522,27 +1510,27 @@ it either way.
1522
1510
 
1523
1511
  ### Errors
1524
1512
 
1525
- `TableError` carries a machine-readable `code` and an optional structured `context`. Narrow a caught
1526
- value with `isTableError` and branch on `code`; never match on message text.
1513
+ `GridError` carries a machine-readable `code` and an optional structured `context`. Narrow a caught
1514
+ value with `isGridError` and branch on `code`; never match on message text.
1527
1515
 
1528
- | Code | Raised when |
1529
- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1530
- | `SCHEMA` | The schema is not a table schema, or `auditTable` found a domain fault or a budget breach — `createTable` and the `Table` constructor raise those. `serializeTable` and `cloneSchema` raise it at their own door for a `meta` no clone can own, which the guard and the audit refuse first for every schema whose reads are stable. |
1531
- | `COLUMN` | A term or a filter names a column the schema does not declare. |
1532
- | `KEY` | A row's identity is missing, unusable, already taken, or repeated inside one batch. |
1533
- | `CELL` | A cell is one its column cannot hold, or a filter's operator or operand is one its column cannot take. |
1534
- | `DESTROYED` | A write reached a table that has been torn down. |
1516
+ | Code | Raised when |
1517
+ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1518
+ | `SCHEMA` | The schema is not a grid schema, or `auditGrid` found a domain fault or a budget breach — `createGrid` and the `Grid` constructor raise those. `serializeGrid` and `cloneGridSchema` raise it at their own door for a `meta` no clone can own, which the guard and the audit refuse first for every schema whose reads are stable. |
1519
+ | `COLUMN` | A term or a filter names a column the schema does not declare. |
1520
+ | `KEY` | A row's identity is missing, unusable, already taken, or repeated inside one batch. |
1521
+ | `CELL` | A cell is one its column cannot hold, or a filter's operator or operand is one its column cannot take. |
1522
+ | `DESTROYED` | A write reached a grid that has been torn down. |
1535
1523
 
1536
1524
  ```ts
1537
- import { createTable, isTableError } from '@orkestrel/table'
1525
+ import { createGrid, isGridError } from '@orkestrel/table'
1538
1526
 
1539
1527
  try {
1540
- createTable({ key: 'missing', columns: [{ cell: 'text', key: 'id' }] })
1528
+ createGrid({ key: 'missing', columns: [{ cell: 'text', key: 'id' }] })
1541
1529
  } catch (error) {
1542
- if (isTableError(error)) error.code // 'SCHEMA'
1530
+ if (isGridError(error)) error.code // 'SCHEMA'
1543
1531
  }
1544
1532
 
1545
- const table = createTable({
1533
+ const grid = createGrid({
1546
1534
  key: 'id',
1547
1535
  columns: [
1548
1536
  { cell: 'text', key: 'id' },
@@ -1551,33 +1539,33 @@ const table = createTable({
1551
1539
  })
1552
1540
 
1553
1541
  try {
1554
- table.sort.set({ column: 'nope', direction: 'ascending' })
1542
+ grid.sort.set({ column: 'nope', direction: 'ascending' })
1555
1543
  } catch (error) {
1556
- if (isTableError(error)) error.code // 'COLUMN'
1544
+ if (isGridError(error)) error.code // 'COLUMN'
1557
1545
  }
1558
1546
 
1559
1547
  try {
1560
- table.rows.add({ id: '1', age: 'twelve' })
1548
+ grid.rows.add({ id: '1', age: 'twelve' })
1561
1549
  } catch (error) {
1562
- if (isTableError(error)) error.code // 'CELL'
1550
+ if (isGridError(error)) error.code // 'CELL'
1563
1551
  }
1564
1552
 
1565
- table.rows.rows().length // 0 — a refused write changed nothing
1553
+ grid.rows.rows().length // 0 — a refused write changed nothing
1566
1554
  ```
1567
1555
 
1568
- `createTable` and `new Table(...)` are the same construction. Prefer the factory at a call site that
1569
- only needs `TableInterface`; reach for the class where a class holds a table as its own field and
1556
+ `createGrid` and `new Grid(...)` are the same construction. Prefer the factory at a call site that
1557
+ only needs `GridInterface`; reach for the class where a class holds a grid as its own field and
1570
1558
  wants the concrete type.
1571
1559
 
1572
1560
  ```ts
1573
- import { Table } from '@orkestrel/table'
1561
+ import { Grid } from '@orkestrel/table'
1574
1562
 
1575
- const table = new Table(
1563
+ const grid = new Grid(
1576
1564
  { key: 'id', columns: [{ cell: 'text', key: 'id' }] },
1577
1565
  { rows: [{ id: '1' }] },
1578
1566
  )
1579
1567
 
1580
- table.count // 1
1568
+ grid.count // 1
1581
1569
  ```
1582
1570
 
1583
1571
  ## Contract
@@ -1591,26 +1579,26 @@ These invariants hold across [`src/core`](../src/core) and this guide.
1591
1579
  2. **Documented methods equal interface methods.** Each `## Methods` table lists exactly its
1592
1580
  interface's call-signature members, and each class implements every one and adds no public
1593
1581
  behavior beyond them. Each interface has one table and one class.
1594
- 3. **Identity is a declared column's non-empty string cell.** `TableSchema.key` is required and must
1582
+ 3. **Identity is a declared column's non-empty string cell.** `GridSchema.key` is required and must
1595
1583
  name a declared column. A row whose cell there is missing, empty, or not a string is refused with
1596
- `KEY`, and so is a key the table already holds or a key repeated inside one batch. There is no
1584
+ `KEY`, and so is a key the grid already holds or a key repeated inside one batch. There is no
1597
1585
  default column, no positional fallback, and no key generation anywhere in this package.
1598
- 4. **A row is owned at admission and at every read.** The table clones and freezes each row it
1586
+ 4. **A row is owned at admission and at every read.** The grid clones and freezes each row it
1599
1587
  admits and each row it hands back, and clones and freezes the schema at construction. An edit to
1600
- the object a caller passed changes nothing inside the table, and no getter returns a live internal
1588
+ the object a caller passed changes nothing inside the grid, and no getter returns a live internal
1601
1589
  reference.
1602
1590
  5. **A write is all-or-nothing, and it refuses by raising or by returning `false`.** `rows.add`,
1603
1591
  `rows.update`, `rows.remove`, `sort.set`, `sort.remove`, `filter.set`, `filter.remove`, and every
1604
1592
  0/1/N verb on selection and expansion check the whole argument before any of it lands. A bad
1605
1593
  value raises `KEY`, `CELL`, or `COLUMN`. A name that nothing answers to returns `false` and raises
1606
1594
  nothing — an unheld row key for `rows`, `selection`, and `expansion`, and an undeclared column for
1607
- `sort.remove` and `filter.remove`. Either way the table is left exactly as it was.
1595
+ `sort.remove` and `filter.remove`. Either way the grid is left exactly as it was.
1608
1596
  6. **`update` merges and cannot move a key.** The cells given replace the cells held and the cells
1609
1597
  left out stay as they are, and the row is found by the key it carries — so no sequence of
1610
1598
  `update` calls changes any row's identity.
1611
1599
  7. **The view is derived, never stored.** `view`, `count`, `pagination.offset`, and
1612
1600
  `pagination.count` are worked out on every read from the rows, the filters, the terms, and
1613
- `page`. Nothing caches them, so none of them can disagree with what the table holds.
1601
+ `page`. Nothing caches them, so none of them can disagree with what the grid holds.
1614
1602
  8. **The lens applies in one order.** `view` is filtered, then sorted, then paged, always. A filter
1615
1603
  therefore decides `count` and the page count, and paging never reorders anything.
1616
1604
  9. **Sorting is stable and its terms are ordered.** The first term decides and each later term
@@ -1619,24 +1607,24 @@ These invariants hold across [`src/core`](../src/core) and this guide.
1619
1607
  in the list. A `choice` column compares by the order its `choices` declares, a `flag` compares
1620
1608
  false before true, a `number` by magnitude, and a `text` lexically. An absent cell sorts before
1621
1609
  every present one in ascending order.
1622
- 10. **Filters are and-only, one per column.** The table holds at most one filter per column and
1610
+ 10. **Filters are and-only, one per column.** The grid holds at most one filter per column and
1623
1611
  keeps the rows every one of them accepts. There is no either-or composition and no nesting. An
1624
1612
  operator its column's cell does not admit, and an operand its column cannot hold, are both `CELL`
1625
1613
  refusals rather than empty results.
1626
1614
  11. **An override replaces one column's default and nothing else.** A `comparators` or `matchers`
1627
1615
  entry is consulted only for the column its key names, receives `undefined` for a row carrying no
1628
1616
  cell there, and never changes which columns exist. A comparator always describes ascending order
1629
- and `TableDirection` is applied to its result. An entry naming an undeclared column is never
1617
+ and `GridDirection` is applied to its result. An entry naming an undeclared column is never
1630
1618
  consulted and is not an error.
1631
- 12. **Selection and expansion hold keys, and prune.** Both hold `TableKey` sets only, so a pick
1632
- survives a sort, a filter, and a page turn; and a row leaving the table removes its key from
1633
- both. Selecting with no argument picks every row the table holds, not every row in `view`.
1619
+ 12. **Selection and expansion hold keys, and prune.** Both hold `GridKey` sets only, so a pick
1620
+ survives a sort, a filter, and a page turn; and a row leaving the grid removes its key from
1621
+ both. Selecting with no argument picks every row the grid holds, not every row in `view`.
1634
1622
  13. **Pagination is derived and clamps.** `page` is the only stored fact, counted from one;
1635
1623
  `offset` is `(page - 1) * limit` and zero when unpaged; `count` is `max(1, ceil(rows / limit))`
1636
- and `1` when unpaged — so a paged table with no admitted rows holds one page, and that page's
1624
+ and `1` when unpaged — so a paged grid with no admitted rows holds one page, and that page's
1637
1625
  `view` is empty. A page beyond the last clamps to the last, including when a filter or a removal
1638
1626
  shrinks the rows underneath it. `resize` keeps the first row the view was showing.
1639
- 14. **Every event fires after commit, and a no-op is silent.** No listener sees a state the table has
1627
+ 14. **Every event fires after commit, and a no-op is silent.** No listener sees a state the grid has
1640
1628
  not finished writing, and a call that moves nothing announces nothing — the same sort term twice,
1641
1629
  a toggle back to where it was, a `move` to the index a row already occupies. When one call moves
1642
1630
  several things, the rows announce first and then the axes they disturbed, in the order `select`,
@@ -1644,18 +1632,18 @@ These invariants hold across [`src/core`](../src/core) and this guide.
1644
1632
  15. **`clear` is one announcement and `destroy` is idempotent.** `clear` emits `clear` alone,
1645
1633
  whatever it reset, so a reset of ten thousand rows is one event. `destroy` called twice does what
1646
1634
  calling it once did; afterwards every write raises `DESTROYED` while every getter still answers
1647
- what the table last held, and `destroyed` reports the fact so a host need not catch to learn it.
1635
+ what the grid last held, and `destroyed` reports the fact so a host need not catch to learn it.
1648
1636
  16. **Guards are total and parsers refuse.** No `is*` throws for any input — unexpected prototype,
1649
1637
  symbol key, cycle, or depth. No `parse*` throws; each returns `undefined` on refusal. A
1650
1638
  guard-valid value is never refused by its parser, and every parsed result satisfies its guard.
1651
- `isTableSchema` is therefore semantic and not merely structural: it is the exact shape plus an
1652
- empty `auditTable`, which is exactly what `parseTable` and the `Table` constructor demand.
1653
- `isStructuralTableSchema` is the shape alone, for a caller running the audit itself.
1654
- 17. **Only data crosses the wire, and the round trip is byte-stable.** `serializeTable` and
1639
+ `isGridSchema` is therefore semantic and not merely structural: it is the exact shape plus an
1640
+ empty `auditGrid`, which is exactly what `parseGrid` and the `Grid` constructor demand.
1641
+ `isStructuralGridSchema` is the shape alone, for a caller running the audit itself.
1642
+ 17. **Only data crosses the wire, and the round trip is byte-stable.** `serializeGrid` and
1655
1643
  `serializeRows` emit in canonical order — a schema's members in declaration order, a column's in
1656
1644
  the order the contract declares them, and a row's cells in the schema's column order. Incoming
1657
1645
  key order is canonicalized rather than preserved, so the bytes settle at the first projection
1658
- and every projection after it reproduces them, including a projection of what `parseTable` or
1646
+ and every projection after it reproduces them, including a projection of what `parseGrid` or
1659
1647
  `parseRows` returned from those bytes. `meta` survives verbatim key for key. Options and live
1660
1648
  state have no projection at all: functions, sort terms, filters, picked keys, opened keys, and
1661
1649
  the page never travel.
@@ -1663,14 +1651,15 @@ These invariants hold across [`src/core`](../src/core) and this guide.
1663
1651
  no usable identity, when two rows share one, when a cell's column cannot hold it, or when a key
1664
1652
  names no declared column. It coerces a numeric string for a `number` column and `'true'` /
1665
1653
  `'false'` for a `flag` column, and nothing else.
1666
- 19. **Every retained size is budgeted.** `auditTable` reports a breach of `COLUMN_LIMIT`,
1667
- `CHOICE_LIMIT`, `NAME_LIMIT`, `STRING_LIMIT`, `TEXT_LIMIT`, or `NODE_LIMIT`, so `createTable`
1668
- raises `SCHEMA` and `parseTable` refuses; `matchesCell` refuses a string breaching
1669
- `STRING_LIMIT` before it consults the column, so a write raises `CELL` and `parseRows` returns
1670
- `undefined`. `TEXT_LIMIT` and `NODE_LIMIT` are whole-schema ceilings, `meta` included, so the
1671
- per-item limits never multiply. Row count is deliberately unbudgeted, and so is the structural
1672
- read at the parse door, which is the transport's to bound.
1673
- 20. **`auditTable` returns diagnostics, not a contract.** The list's emptiness is the promise. The
1654
+ 19. **Every retained size is budgeted.** `auditGrid` reports a breach of this package's
1655
+ `COLUMN_LIMIT` or of the `@orkestrel/contract` budgets `CHOICE_LIMIT`, `NAME_LIMIT`,
1656
+ `STRING_LIMIT`, `TEXT_LIMIT`, and `NODE_LIMIT`, so `createGrid` raises `SCHEMA` and
1657
+ `parseGrid` refuses; `matchesCell` refuses a string breaching `STRING_LIMIT`, from
1658
+ `@orkestrel/contract`, before it consults the column, so a write raises `CELL` and `parseRows`
1659
+ returns `undefined`. `TEXT_LIMIT` and `NODE_LIMIT`, from `@orkestrel/contract`, are whole-schema
1660
+ ceilings, `meta` included, so the per-item limits never multiply. Row count is deliberately
1661
+ unbudgeted, and so is the structural read at the parse door, which is the transport's to bound.
1662
+ 20. **`auditGrid` returns diagnostics, not a contract.** The list's emptiness is the promise. The
1674
1663
  wording of its strings is not. Never parse them.
1675
1664
  21. **Temporal values are ISO text compared lexically, under one spelling.** A date, a time, and a
1676
1665
  timestamp are `text` cells, and lexical order is chronological order only where a column's
@@ -1692,22 +1681,22 @@ this package answers today through a mechanism it already exposes.
1692
1681
 
1693
1682
  | Concept | Layer | Why it sits there |
1694
1683
  | ---------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1695
- | Rendering | host | The table owns values, not pixels. It names no host type, so one table serves a browser, a terminal, a report, and an export equally — and the moment it drew one of them it would serve only that one. |
1696
- | ARIA and roles | host | `label` and `help` are the strings an accessible grid needs. The roles, the ids, and their uniqueness belong to the layer that owns the elements. |
1697
- | Keyboard and focus | host | Arrow keys, roving focus, and type-ahead are input gestures over drawn cells. The table has no cursor because it has no cells on a screen. |
1698
- | Virtualization | host | Which rows are cheap to draw is a measurement of drawn things. `pagination` already gives a windowing host `offset` and `limit`, and a virtualizer that wants the whole list leaves the table unpaged and reads `view`, which is every admitted row in sort order. `rows()` is the store's own order and ignores the lens. |
1699
- | Column resizing | host | A width is pixels. `meta` carries one when a host must ship it in the schema, and the table never reads it. |
1684
+ | Rendering | host | The grid owns values, not pixels. It names no host type, so one grid serves a browser, a terminal, a report, and an export equally — and the moment it drew one of them it would serve only that one. |
1685
+ | ARIA and roles | host | `label` and `help` are the strings an accessible table needs. The roles, the ids, and their uniqueness belong to the layer that owns the elements. |
1686
+ | Keyboard and focus | host | Arrow keys, roving focus, and type-ahead are input gestures over drawn cells. The grid has no cursor because it has no cells on a screen. |
1687
+ | Virtualization | host | Which rows are cheap to draw is a measurement of drawn things. `pagination` already gives a windowing host `offset` and `limit`, and a virtualizer that wants the whole list leaves the grid unpaged and reads `view`, which is every admitted row in sort order. `rows()` is the store's own order and ignores the lens. |
1688
+ | Column resizing | host | A width is pixels. `meta` carries one when a host must ship it in the schema, and the grid never reads it. |
1700
1689
  | Column reordering and hiding | seam | `columns` order is presentation order and `hidden` is the flag. Reordering is building the next schema, which is one line over the array a host already holds. |
1701
- | Row drag-and-drop | seam | The gesture is the host's; the result is `rows.move(key, index)`, which is the one verb that writes the table's own order. |
1690
+ | Row drag-and-drop | seam | The gesture is the host's; the result is `rows.move(key, index)`, which is the one verb that writes the grid's own order. |
1702
1691
  | Sticky columns and headers | host | Which columns stay put while the rest scroll is a layout decision about drawn elements. |
1703
1692
  | Or-filters and nested groups | out | v1 composes filters with **and** only, one per column, which is what a filter bar produces. The one thing it cannot express at all is the global search box that matches a term against every column: that is an or across columns, and a host wanting one narrows `rows()` with its own predicate and holds the result itself. Either-or turns a flat list into a tree and takes every guard, parser, and wire form with it. |
1704
- | 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. |
1693
+ | 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 grid holds. |
1705
1694
  | 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. |
1706
1695
  | 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. |
1707
- | 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. |
1696
+ | Undo and history | out | The grid 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. |
1708
1697
  | 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`. |
1709
1698
  | 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. |
1710
- | 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. |
1699
+ | Row count budget | out | A grid 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. |
1711
1700
  | Parsing a lens off the wire | out | Sort terms, filters, and the picked keys are what a session is looking through, not the document. A host persisting them owns the format, so a parser here would parse the host's decision. |
1712
1701
  | Case folding and collation | seam | `contains` compares case-sensitively and `text` compares with the language's own string order. Locale is a decision this package cannot make for a host, so a `CellMatcher` or `CellComparator` makes it. |
1713
1702
  | A temporal cell | out | ISO text written to one canonical spelling per instant — one offset, one precision, and no alternate spelling of a given date or time — sorts chronologically already, so a temporal cell would add a variant that behaves exactly like `text` and a calendar to go with it. Normalizing to that one canonical representation is the host's, and a `CellComparator` covers a column that arrives mixed. |
@@ -1722,44 +1711,43 @@ this package answers today through a mechanism it already exposes.
1722
1711
 
1723
1712
  - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ barrel bijection, the
1724
1713
  interface ↔ class method bijections, and the equality gate: every `Summary` cell against its
1725
- declaration's description paragraph, the titled `Open a table` fence against the `@example` block
1714
+ declaration's description paragraph, the titled `Open a grid` fence against the `@example` block
1726
1715
  of that title (pinned so the titled pair cannot be retired silently), and the README pitch against
1727
1716
  this guide's tagline. It also runs the preceding worked examples against the real source so a
1728
1717
  documented value that the code contradicts fails.
1729
- - [`tests/src/core/Table.test.ts`](../tests/src/core/Table.test.ts) — construction, schema
1718
+ - [`tests/src/core/Grid.test.ts`](../tests/src/core/Grid.test.ts) — construction, schema
1730
1719
  ownership, seeding, the derived `view` and `count`, emission order, `clear`, `destroy`, and writes
1731
1720
  after teardown.
1732
- - [`tests/src/core/tables/RowManager.test.ts`](../tests/src/core/tables/RowManager.test.ts) —
1721
+ - [`tests/src/core/grids/RowManager.test.ts`](../tests/src/core/grids/RowManager.test.ts) —
1733
1722
  `row`, `rows`, `add`, `update`, `move`, `remove`, batch atomicity, and identity refusals.
1734
- - [`tests/src/core/tables/SortManager.test.ts`](../tests/src/core/tables/SortManager.test.ts) —
1723
+ - [`tests/src/core/grids/SortManager.test.ts`](../tests/src/core/grids/SortManager.test.ts) —
1735
1724
  `order`, `orders`, `set`, `remove`, in-place replacement, stability, and comparator overrides.
1736
- - [`tests/src/core/tables/FilterManager.test.ts`](../tests/src/core/tables/FilterManager.test.ts) —
1725
+ - [`tests/src/core/grids/FilterManager.test.ts`](../tests/src/core/grids/FilterManager.test.ts) —
1737
1726
  `filter`, `filters`, `set`, `remove`, and-composition, operator refusals, and matcher overrides.
1738
- - [`tests/src/core/tables/SelectionManager.test.ts`](../tests/src/core/tables/SelectionManager.test.ts)
1727
+ - [`tests/src/core/grids/SelectionManager.test.ts`](../tests/src/core/grids/SelectionManager.test.ts)
1739
1728
  — `select`, `clear`, `toggle`, the 0/1/N overloads, and pruning on removal.
1740
- - [`tests/src/core/tables/ExpansionManager.test.ts`](../tests/src/core/tables/ExpansionManager.test.ts)
1729
+ - [`tests/src/core/grids/ExpansionManager.test.ts`](../tests/src/core/grids/ExpansionManager.test.ts)
1741
1730
  — `expand`, `clear`, `toggle`, the 0/1/N overloads, and pruning on removal.
1742
- - [`tests/src/core/tables/KeyManager.test.ts`](../tests/src/core/tables/KeyManager.test.ts) — the
1731
+ - [`tests/src/core/grids/KeyManager.test.ts`](../tests/src/core/grids/KeyManager.test.ts) — the
1743
1732
  0/1/N forms, the unknown-key refusal, the announcement only on a move, the owned key set, and the
1744
1733
  gate throw passed through.
1745
- - [`tests/src/core/tables/PaginationManager.test.ts`](../tests/src/core/tables/PaginationManager.test.ts)
1746
- — `page`, `limit`, `offset`, `count`, `move`, `resize`, clamping, and the unpaged table.
1734
+ - [`tests/src/core/grids/PaginationManager.test.ts`](../tests/src/core/grids/PaginationManager.test.ts)
1735
+ — `page`, `limit`, `offset`, `count`, `move`, `resize`, clamping, and the unpaged grid.
1747
1736
  - [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — `extractColumn`,
1748
- `extractKey`, `computeKeys`, `mergeTerms`, `removeTerms`, `matchesTerms`, `matchesCell`,
1749
- `compareCells`, `admitsFilter`, `matchesFilter`, `filterRows`, `sortRows`, `auditTable`,
1750
- `serializeTable`, `serializeRows`, and the budgets.
1737
+ `extractGridKey`, `computeKeys`, `mergeTerms`, `removeTerms`, `matchesTerms`, `matchesCell`,
1738
+ `compareCells`, `admitsFilter`, `matchesFilter`, `filterGridRows`, `sortGridRows`, `auditGrid`,
1739
+ `serializeGrid`, `serializeRows`, and the budgets.
1751
1740
  - [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — every guard against
1752
- valid, off-shape, and untrusted input, plus guard/parser soundness in both directions.
1753
- - [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseTable`, `parseRows`,
1741
+ valid, off-shape, and untrusted input, the cell registry, plus guard/parser soundness in both
1742
+ directions.
1743
+ - [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseGrid`, `parseRows`,
1754
1744
  the coercions, identity at the parse door, and the canonical byte-stable round trip.
1755
1745
  - [`tests/src/core/cloners.test.ts`](../tests/src/core/cloners.test.ts) — every clone is owned,
1756
1746
  frozen, and deep enough that no caller reference survives.
1757
- - [`tests/src/core/constants.test.ts`](../tests/src/core/constants.test.ts) — the cell registry and
1758
- each budget's value and unit.
1759
- - [`tests/src/core/errors.test.ts`](../tests/src/core/errors.test.ts) — `TableError`'s `code` and
1760
- `context`, and `isTableError` narrowing.
1761
- - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createTable` returns
1762
- a working `TableInterface`.
1747
+ - [`tests/src/core/errors.test.ts`](../tests/src/core/errors.test.ts) — `GridError`'s `code` and
1748
+ `context`, and `isGridError` narrowing.
1749
+ - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createGrid` returns
1750
+ a working `GridInterface`.
1763
1751
  - [`tests/src/core/index.test.ts`](../tests/src/core/index.test.ts) — the barrel resolves every
1764
1752
  documented export.
1765
1753