@loadbare/app 0.5.5 → 0.6.0

package/docs/reference/page-files.md

@@ -1,13 +1,13 @@
 # Page Files
 
 A page is a set of files sharing one base name. The application writes the
-HTML, and adds queries and hooks when the page shows data.
+HTML, and adds queries and requests when the page shows data.
 
-| File                | Holds                         |
-|---------------------|-------------------------------|
-| `<name>.page.html`  | The page's HTML               |
-| `<name>.queries.ts` | The data the page displays    |
-| `<name>.hooks.ts`   | What the page does when asked |
+| File                 | Holds                         |
+|----------------------|-------------------------------|
+| `<name>.page.html`   | The page's HTML               |
+| `<name>.queries.ts`  | The data the page displays    |
+| `<name>.requests.ts` | What the page does when asked |
 
 Name the landing page `index.page.html`. A bare `/` resolves to `index`, and
 every other path names the page of the same name.
@@ -25,12 +25,12 @@ is supplied by [chrome.html](./chrome.md).
 <h1>About</h1>
 <p>This is the about page.</p>
 
-<div lb-query="visits">
+<div lb-row="visits">
   <p>This page has been visited <span lb-cell="count"></span> times.</p>
 </div>
 ```
 
-Bind elements to data with `lb-query`, `lb-cell`, and the rest of the
+Bind elements to data with `lb-list` or `lb-row`, `lb-cell`, and the rest of the
 attribute vocabulary in [Data Binding](./data-binding.md).
 
 A page that displays no data needs no other file.
@@ -38,56 +38,64 @@ A page that displays no data needs no other file.
 ## Queries
 
 Export `queries` from `<name>.queries.ts`. Each key is a name the HTML binds
-to with `lb-query`, and each value takes the request context and returns
+to with `lb-list` or `lb-row`, and each value takes the request context and returns
 that query's result:
 
 ```ts
 // src/pages/about.queries.ts
-import { type Queries } from "@loadbare/app/server";
+import { row, type Queries } from "@loadbare/app/server";
 
 export const queries: Queries = {
-  visits: async (ctx) => ({ count: String(await ctx.db.visitCount()) }),
+  visits: row(async (ctx) => ({ count: String(await ctx.db.visitCount()) })),
 };
 ```
 
-Return every cell as a string. Format numbers, dates, and money in the query,
-so the browser displays a value it never computes.
+Declare each query with `row()` or `list()`. Cardinality is a property of the
+name rather than of any one answer, so one name answers with one shape,
+always, and `createHub` refuses an answer that disagrees. A page that needs
+the same data as one row and as a set declares two queries.
 
-Return many rows through `rows()`:
+The hub hands each cell to the browser untouched and takes no position on
+its type, so what a number, a date or a null looks like is decided here, in
+the query. Formatting it here means the browser displays a value it never
+computes.
+
+Declare a query that answers with many rows using `list()`, and return the
+array itself:
 
 ```ts
 // src/pages/directory.queries.ts
-import { rows, type Queries } from "@loadbare/app/server";
+import { list, type Queries } from "@loadbare/app/server";
 
 export const queries: Queries = {
-  directory: async (ctx) => rows(await ctx.db.directory()),
+  directory: list((ctx) => ctx.db.directory()),
 };
 ```
 
-Give every row a cell that identifies it, and name that cell with `lb-key` in
-the HTML. Return the rows in the order the page shows them.
+Give every row a column that identifies it, and name that column with
+`lb-key` in the HTML. Return the rows in the order the page shows them.
 
-Return the full result every time. Sending only what changed is a hook's job —
+Return the full result every time. Sending only what changed is a request's job —
 see [refresh and patch](#refresh-and-patch).
 
-## Hooks, actions, CRUD
+## Requests, actions, CRUD
 
-Export `hooks` from `<name>.hooks.ts`. It holds three keys, each optional:
+Export `requests` from `<name>.requests.ts`. It holds three keys, each optional:
 
-| Key         | Runs                                                 |
-|-------------|------------------------------------------------------|
-| `beforeGet` | Before the page's queries, on a request for the page |
-| `actions`   | What the page may be asked to do, by name            |
-| `crud`      | The four operations a query permits on its rows      |
+| Key           | Runs                                                 |
+|---------------|------------------------------------------------------|
+| `onPageEnter` | Before the page's queries, on entering the page      |
+| `actions`     | What the page may be asked to do, by name            |
+| `crud`        | The four operations a list permits on its rows       |
 
-### beforeGet
+### onPageEnter
 
 ```ts
-// src/pages/about.hooks.ts
-import { type Hooks } from "@loadbare/app/server";
+// src/pages/about.requests.ts
+import { type Requests } from "@loadbare/app/server";
 
-export const hooks: Hooks = {
-  beforeGet: (ctx) => ctx.db.recordVisit(),
+export const requests: Requests = {
+  onPageEnter: (ctx) => ctx.db.recordVisit(),
 };
 ```
 
@@ -99,7 +107,7 @@ Declare an action under the name the HTML gives `lb-action`. Pair what it
 does with the queries to re-run once it has:
 
 ```ts
-export const hooks: Hooks = {
+export const requests: Requests = {
   actions: {
     resetVisits: {
       run: (ctx) => ctx.db.resetVisits(),
@@ -113,29 +121,36 @@ Declare every action the page allows. A name the page does not declare is
 refused.
 
 Read where the interaction happened from `run`'s second argument, which
-carries `query`, `key`, `cell`, and `value` when the element that dispatched
-the request had them.
+carries `list` or `row`, whichever attribute scoped the element, plus `key`,
+`cell` and `value` when the element that dispatched the request had them.
 
 ### crud
 
-Declare CRUD operations under `crud`, keyed by the query they operate on. Each
-one takes the binding its trigger supplies:
+Declare CRUD operations under `crud`, keyed by the list they operate on. All
+four are list operations: each needs a key, and a key exists only on a live
+row inside a list, so a single-row scope is read-only and a declared action is
+the only thing it can send. Each operation takes the binding its trigger
+supplies:
+
+| Operation     | The page writes                          | `run` receives         |
+|---------------|------------------------------------------|------------------------|
+| `cellChange`  | `<lb-input lb-action="lb-cell-change">`  | `key`, `cell`, `value` |
+| `rowDelete` | `lb-action="lb-row-delete"`                  | `key`                  |
+| `rowInsert` | `<form lb-action="lb-row-insert">`           | `values`               |
+| `rowUpdate` | `<form lb-action="lb-row-update">`           | `key`, `values`        |
 
-| Operation     | The page writes    | `run` receives         |
-|---------------|--------------------|------------------------|
-| `cellChange`  | `<lb-input data-fire-on-change>` | `key`, `cell`, `value` |
-| `tupleDelete` | `lb-delete`        | `key`                  |
-| `tupleInsert` | `<form lb-insert>` | `values`               |
-| `tupleUpdate` | `<form lb-update>` | `key`, `values`        |
+The operation names are reserved: a name beginning with `lb-` cannot be
+declared under `actions` or as a query, and `createHub` refuses a page that
+tries.
 
 ```ts
-// src/pages/directory.hooks.ts
-import { patch, type Hooks } from "@loadbare/app/server";
+// src/pages/directory.requests.ts
+import { patch, type Requests } from "@loadbare/app/server";
 
-export const hooks: Hooks = {
+export const requests: Requests = {
   crud: {
     directory: {
-      tupleInsert: {
+      rowInsert: {
         run: async (ctx, { values }) => {
           const entry = await ctx.db.addDirectoryEntry(values);
           return { directory: patch({ rows: [entry] }) };
@@ -147,8 +162,8 @@ export const hooks: Hooks = {
 };
 ```
 
-Declare every operation the query permits. An operation a query does not
-declare is refused, and a query with no `crud` entry permits none.
+Declare every operation the list permits. An operation a list does not
+declare is refused, and a name with no `crud` entry permits none.
 
 ### refresh and patch
 
@@ -159,7 +174,7 @@ would. What `run` returns is laid over the refreshed queries:
 
 | Result                   | States                                      |
 |--------------------------|---------------------------------------------|
-| `rows([...])`            | The entire set, and its order               |
+| `[...]`                  | The entire set, and its order               |
 | `patch({ rows: [...] })` | These rows arrive or change; the rest stand |
 | `patch({ drop: [...] })` | These keys are gone; the rest stand         |
 

package/docs/reference/server.md

@@ -44,7 +44,7 @@ app.listen(8787);
 |------------------------------|-------------------------------|
 | `/client.js`                 | `dist/client.js`              |
 | `/app.css`                   | `dist/app.css`                |
-| `hubRoutes(hub, contextFor)` | `GET /lb/data` and `POST /lb` |
+| `hubRoutes(hub, contextFor)` | The hub's own route            |
 | Every other GET              | `dist/app.html`               |
 
 Everything else is optional:
@@ -66,9 +66,10 @@ Serve `dist/app.html` for every route the application does not claim,
 including a path that names no page. See [`chrome.html`](./chrome.md) for the
 `<dialog lb-unknown-page>` that announces that case to the user.
 
-Give the server the origin root. A proxy in front of it passes `/lb/data` and
-`/lb` through unchanged, and the application cannot be hosted under a subpath
-such as `example.com/myapp/`.
+Give the server the origin root. The hub reaches its own route by absolute
+path, so the application cannot be hosted under a subpath such as
+`example.com/myapp/`, and anything proxying in front of the server passes the
+whole path space through unchanged.
 
 Leave `express.json()` to `hubRoutes`, which mounts it on its own routes.
 
@@ -85,7 +86,7 @@ Run the server under a TypeScript-capable runner. The builder writes
 }
 ```
 
-Restart the server after adding or changing a `.hooks.ts` or `.queries.ts`
+Restart the server after adding or changing a `.requests.ts` or `.queries.ts`
 file.
 
 ## Database layer
@@ -119,5 +120,5 @@ declare module "@loadbare/app/server" {
 ```
 
 Add a field for anything else a request needs — the authenticated user, a
-request id, a feature flag set. Queries and hooks read them from `ctx`; see
+request id, a feature flag set. Queries and requests read them from `ctx`; see
 [page files](./page-files.md).

package/docs/reference/widgets.md

@@ -1,7 +1,7 @@
 # The Basic Widget Library
 
-Six widgets: `lb-input`, `lb-select`, `lb-list`, `lb-options`, `lb-table`,
-`lb-picker`. Every one of them is written against the same two contracts
+Seven widgets: `lb-input`, `lb-select`, `lb-list`, `lb-options`, `lb-table`,
+`lb-picker`, `lb-unknown-page`. Every one of them is written against the same two contracts
 documented elsewhere — [Custom Elements](./custom-elements.md#html) for its
 definition, [Custom Elements](./custom-elements.md#code) for its class —
 nothing here is special-cased machinery.
@@ -26,11 +26,12 @@ for where a listed package sits in the cascade.
 ## `lb-input`
 
 Wraps an `<input>`. `lb-value` sets the input's `.value`. The widget sends
-nothing on its own: `data-fire-on-change` asks it to send `cell-change` on the
-input's `change`, addressed by its own `lb-query`/`lb-key`/`lb-cell`
-coordinates.
+nothing on its own: `lb-action` names what the input's `change` sends. The
+reserved `lb-cell-change` sends `lb-cell-change`, addressed by the widget's own
+`lb-list`/`lb-key-value`/`lb-cell` coordinates; any other name sends that
+action with the input's value.
 
-An input inside an `lb-insert` or `lb-update` form leaves the attribute off.
+An input inside an `lb-row-insert` or `lb-row-update` form leaves the attribute off.
 The form reads every `lb-cell` in it on submit and sends one request for all
 of them, so an input that also sent its own would write the same edit twice.
 
@@ -41,7 +42,7 @@ of them, so an input that also sent its own would write the same edit twice.
 
 | Attribute | Asks for |
 | ---------- | ----- |
-| `data-fire-on-change` | an edit to be sent, on `change` |
+| `lb-action` | what to send on `change`; `lb-cell-change` for the cell's own edit |
 
 ## `lb-select`
 
@@ -57,15 +58,6 @@ action carries a value.
 
 Requires `lb-action` — a change with none logs and sends nothing.
 
-## `lb-list`
-
-The plain repeater: whatever the author writes inside a
-`<template lb-key="...">` is cloned once per row, in arrival order. No
-grouping, no sorting, no request of its own — it exists because a
-`Projection` has to land on something with `acceptRows`, and a bare
-`<table>` can't be one (a custom element written inside `<tbody>` is
-discarded by the parser).
-
 ## `lb-options`
 
 A `<select>` whose `<option>`s come from a query instead of being written by
@@ -73,8 +65,8 @@ hand. The author supplies the row template inside the widget (via
 `lb-slot`), same as any list widget:
 
 ```html
-<lb-options lb-query="statuses" exp-label="Status" lb-action="setStatus">
-  <template lb-key="id" lb-group="category">
+<lb-options lb-list="statuses" exp-label="Status" lb-action="setStatus">
+  <template lb-key="id" data-group="category">
     <option lb-cell="label"></option>
   </template>
 </lb-options>
@@ -84,11 +76,11 @@ hand. The author supplies the row template inside the widget (via
 | ---------- | ----- |
 | `exp-label` | the visible `<label>` text |
 
-- The row's key becomes the option's `value` — `lb-key` supplies both, so
-  nothing is declared twice.
-- `lb-group` on the row template sections the options into `<optgroup>`s,
+- The row's key becomes the option's `value`: the `lb-key-value` the hub
+  stamps on each option is copied across, so the page names the key column
+  once, with `lb-key`.
+- `data-group` on the row template sections the options into `<optgroup>`s,
   one per distinct value, created and removed as rows arrive and leave.
-- `lb-sort` is not read by this widget.
 - A `change` sends the action named by `lb-action`, value from the
   select's `.value`.
 
@@ -102,15 +94,15 @@ heading row, the row template, and optionally a footer, each as a
 `<template>` matched to a destination:
 
 ```html
-<lb-table lb-query="ledger" exp-caption="Ledger">
+<lb-table lb-list="ledger" exp-caption="Ledger">
   <template lb-template="head">
     <tr><th>Date</th><th>Amount</th></tr>
   </template>
-  <template lb-key="id" lb-sort="date" lb-group="month">
+  <template lb-key="id" data-sort="date" data-group="month">
     <tr><td lb-cell="date"></td><td lb-cell="amount"></td></tr>
   </template>
   <template lb-template="foot">
-    <tr lb-query="ledger-total"><td>Total</td><td lb-cell="total"></td></tr>
+    <tr lb-row="ledger-total"><td>Total</td><td lb-cell="total"></td></tr>
   </template>
 </lb-table>
 ```
@@ -125,13 +117,13 @@ heading row, the row template, and optionally a footer, each as a
 | `foot` (`lb-template="foot"`) | the `<tfoot>` content |
 | slot (no `lb-template`) | the row template, via `lb-slot` on `<tbody>` |
 
-- `lb-group` on the row template sections rows under a derived heading row,
+- `data-group` on the row template sections rows under a derived heading row,
   one per distinct value, whose `colSpan` matches the row's own column
-  count. `lb-sort` orders rows within a section (or the whole body, with no
+  count. `data-sort` orders rows within a section (or the whole body, with no
   grouping) by comparing each row's cell text.
-- The `foot` destination is not delivered through `acceptRows` — it's an
-  ordinary scope carrying its own `lb-query`, resolved by name like any
-  other on the page. A grand total is a second projection of the same
+- The `foot` destination is not delivered through `lbPlaceRow` — it's an
+  ordinary scope carrying its own `lb-row`, resolved by name like any
+  other on the page. A grand total is a second query over the same
   data, not a row the hub hands the table.
 
 ## `lb-picker`
@@ -141,7 +133,7 @@ the page — for when every row is one option and nothing else varies:
 
 ```html
 <lb-picker
-  lb-query="statuses"
+  lb-list="statuses"
   exp-label="Status"
   exp-key="id"
   exp-cell="label"
@@ -155,9 +147,28 @@ the page — for when every row is one option and nothing else varies:
 | `exp-label` | the visible `<label>` text |
 | `exp-key` | the row template's `lb-key` |
 | `exp-cell` | the option's `lb-cell` |
-| `exp-group` | the row template's `lb-group` |
+| `exp-group` | the row template's `data-group` |
 
 Behavior — grouping, key-as-value, the action on change — is inherited
 whole from `lb-options`; a page author who needs a second element in the
 row, or an option built from two columns, writes `lb-options` and its own
 `<template>` instead.
+
+## `lb-unknown-page`
+
+The chrome's dialog for a URL that names no page, as one tag:
+
+```html
+<lb-hub>
+  <nav>...</nav>
+  <main></main>
+  <lb-unknown-page></lb-unknown-page>
+</lb-hub>
+```
+
+It expands to a `<dialog lb-unknown-page>` scoped to the hub's own
+`lb-navigation` query, so `page-label` and `page-uri` land in it the way any
+cell lands anywhere, and the hub opens it on a miss. It takes no parameters
+and, so far, shows both cells rather than choosing between them. See
+[`chrome.html`](./chrome.md#where-the-page-is) for the query, and for the same
+dialog written by hand.

package/docs/roadmap.md

@@ -17,32 +17,17 @@ wrong thing. Revisit when the described symptom actually shows up.
 
 ### Staleness and concurrent writers
 
-Two tabs, or two users, updating the same projection at once. A solo
-developer testing in one browser will not produce this by accident, and
-retrofitting a version or conflict check onto every tuple after the fact
-touches every widget that writes.
+Two tabs, or two users, updating the same list at once. A solo developer
+testing in one browser will not produce this by accident, and retrofitting a
+version or conflict check onto every row after the fact touches every widget
+that writes.
 
 ### Nesting
 
-Whether a tuple may contain a projection (master-detail, an expanding
-row). [Theory](./theory.md) already flags this as possibly load-bearing if
+Whether a row may contain a list (master-detail, an expanding row). [Theory](./theory.md) already flags this as possibly load-bearing if
 disallowed. Worth a decision-in-principle the first time a master-detail
 page is built, even before the mechanism is needed elsewhere.
 
-### Whether `lb-query` may be inherited
-
-Currently every scope states its own `lb-query`; nothing resolves one from
-an ancestor. Inheritance would be friendlier to the page author but adds a
-resolution rule, and a resolution rule is a mechanism this framework has
-otherwise avoided. Worth deciding before an application grows deep enough
-nesting that restating the query on every level starts to hurt.
-
-### Whether `lb-key` is always required
-
-Undecided whether every row needs `lb-key`, or only a row something
-targets (a delete button, an update form). Revisit if a list widget shows
-up that never needs to address an individual row by key.
-
 ### Pending appearance
 
 A value that hasn't arrived yet is probably derivable from an absent
@@ -112,12 +97,53 @@ enough to measure.
 
 ### Data binding utilities
 
-If a dev team wishes to make their own widgets that identify `lb-query`,
-`lb-key`, `lb-cell`, they must repeat the code that is present in the hub.
+If a dev team wishes to make their own widgets that identify `lb-list` or `lb-row`,
+`lb-key-value`, `lb-cell`, they must repeat the code that is present in the hub.
 
 Perhaps a utility that can be called, like `getDataScope(el)`, to help
 clean up the code in these cases.
 
+### Build-time checking of `lb-action` against the declared requests
+
+Release 1.0 resolves every `lb-action` value at request time. A value naming
+no entry under `actions`, or a reserved operation naming a list with no entry
+under `crud`, is found on the first click: a server console warning and an
+empty answer, described in
+[Page files](./reference/page-files.md). A typo builds cleanly.
+
+The builder already expands each page and walks the finished document in
+`checkBinding`, tracking the enclosing `lb-list` scope, so collecting every
+action name together with the list it sits in needs no new machinery. What
+it lacks is the other half of the comparison: it knows the path of a
+`.requests.ts` file and never reads its contents.
+
+Two routes to the declared names, and the choice is the decision:
+
+- **Load the built module.** Bundle the generated `pages.ts`, import it, and
+  read the keys off the finished objects. Exact, and indifferent to how the
+  object was written. The build then executes application import-time code,
+  and a builder that only reads files stops being that.
+- **Parse the source.** Read the keys statically with the TypeScript compiler
+  API. No application code runs, at the price of a real dependency and of
+  guessing wrong on anything not written as a plain object literal.
+
+Three smaller calls come with either route. The chrome belongs to no page, so
+an action there can only be required of every page or forbidden. A page with
+no requests file makes any action on it an error. And the check sees markup
+only, so it is sound only if `lb-action` is authored and never assigned by
+script — no widget assigns it today, and the rule has never been written
+down.
+
+This reverses the position stated above `walkBinding`, that markup and server
+are separate artifacts and the comparison belongs to `createHub`. The same
+machinery would then also let `lb-list` and `lb-row` names be checked against
+the declared queries.
+
+One piece is separable and needs none of the above: an `lb-action` beginning
+with `lb-` that names none of the four operations is a typo the builder can
+refuse from markup alone. `LB_ACTIONS` in `core/lb-constants.ts` exists for
+this, and the builder does not yet import it.
+
 ### A language server
 
 ...for Loadbare HTML.
@@ -128,3 +154,23 @@ Internationalization would require a potential extension to build-time
 expansion allows a strings file.  We could either preserve the fully 
 static build-time system and create multiple versions of `app.html`, or we
 could add label hydration to the page navigation stage.
+
+## Decided against
+
+Settled questions, kept here so they are not reopened.  Each names what was
+asked for and why the answer is no.
+
+### Interpolation in a placeholder
+
+`{{name}}` is the whole of an attribute value or the whole of a text node.  A
+placeholder inside a longer string, such as `title="Hello {{name}}"`, ships
+literal braces.
+
+A value that is absent with no default drops the attribute, which is how a
+boolean attribute is turned off.  Inside a longer string the same placeholder
+could only become an empty string, so one syntax would mean two things.
+Interpolation would also reserve `{{` and `|` in every text node and
+attribute value, with no escape for either.
+
+Text has a workaround: `<div>Hello, <span>{{world}}</span></div>` places the
+placeholder in a text node of its own.  Attribute values have none.

package/docs/testing.md

@@ -19,8 +19,8 @@ emulation has given up the only failure mode it was looking for.
 |------|--------------------------------------------------|-------------|
 | 1    | Expansion and the build — `build/`               | node        |
 | 2    | The engine — `server/`, and the Express adapter  | node        |
-| 3    | Landing — `hub/lb-apply.ts`, `hub/lb-rows.ts`    | jsdom       |
-| 4    | The hub — `hub/lb-hub.browser.ts`                        | jsdom       |
+| 3    | Landing — `hub/lb-apply.ts`                      | jsdom       |
+| 4    | The hub — `hub/lb-hub.browser.ts`                | jsdom       |
 
 All four tiers run under `npm test` today and need no dependency that is not
 already installed. A fifth environment — a real browser — is discussed at the
@@ -112,7 +112,7 @@ needs a browser either.
 `createHub` takes a plain object and returns an object. Nothing in
 `server/lb-server.ts` opens a socket, so the fixtures are counting stubs.
 
-- `beforeGet` runs before any query, and the whole query set runs after it
+- `onPageEnter` runs before any query, and the whole query set runs after it
 - an unknown page answers `{}` and says so
 - an unknown query name in a refresh set is skipped, and its siblings run
 - an action the page did not declare is refused — the rule that keeps the
@@ -128,7 +128,7 @@ malformed body does not throw.
 
 ## Tier 3 — Landing
 
-`applyData`, `applyTuple` and `applyRows` are the most intricate code in the
+`applyData`, `applyRow` and `applyList` are the most intricate code in the
 framework and the most likely to break in ways nobody notices. They are also
 pure DOM: no fetch, no widget upgrade, no history. jsdom is real evidence
 here.
@@ -137,11 +137,11 @@ here.
 - the root of a scope counts as a cell if it carries one, which is what makes
   an `<option>` row possible
 - a query with no scope is reported and skipped; several scopes for one query
-  are all filled; a projection landing on something that is not a list widget
+  are all filled; a set of rows landing on a scope bound with `lb-row`
   is reported rather than thrown
 - `rows` decides membership and order, so a key that did not arrive is gone
 - `patch` disturbs only what it names, in contents and in position
-- `data-rows` is counted from the DOM after reconciliation, so a set and a
+- `lb-row-count` is counted from the DOM after reconciliation, so a set and a
   patch ending in the same state report the same number
 - the `place` callback is called for a fresh row always, and for an existing
   row only under `rows`. That is today's behavior, not a decision — a patch
@@ -149,8 +149,8 @@ here.
   is true now, and is the one that flips if that changes.
 
 **Two properties**, written as loops rather than with a library. Applying the
-same `rows` twice is applying it once. And `rows(S)` reached through any
-sequence of patches is `rows(S)` reached from empty. Convergence is the
+same set twice is applying it once. And a set reached through any
+sequence of patches is that set reached from empty. Convergence is the
 actual contract of a reconciler, and those two say it better than twenty
 examples.
 
@@ -159,7 +159,40 @@ examples.
 The widget half of this tier lives in `@loadbare/widgets` and is tested
 there, against the same jsdom harness described below — see
 [`packages/widgets/AGENTS.md`](../../widgets/AGENTS.md). What follows applies
-to both, and the hub is what remains here.
+to both, and the hub element is what remains here.
+
+The hub is the one source file whose coverage is split across two tiers, so
+the split is written down rather than left to judgment. jsdom is evidence
+for everything the hub does to the document it is already holding: which
+element an event came from, what request that produces, which attributes
+land where, and which page host a path selects. It is not evidence for
+anything about a real network or a real frame, and those cases are listed
+under the browser tier below and are not written.
+
+Two things the hub reaches for do not exist in jsdom 25, so the harness
+supplies them. `fetch` is absent, and a test wants a scripted one anyway.
+`HTMLDialogElement.showModal` is absent, so the harness records the call
+instead. `history.pushState` and `popstate` are real, so navigation needs no
+help.
+
+What the hub is tested for here:
+
+- `requestFor` builds each of the three operations a native element can
+  send, and refuses a reserved name it cannot turn into one
+- a click finds the nearest `lb-action`, and skips a hyphenated tag and a
+  form, both of which own the interaction themselves
+- a submit gathers the form's cells, and reports a cell with no control
+- a request arriving with no action, or with a reserved name that is not one
+  of the four, is refused before it reaches the wire
+- `lb-pending` lands on the element that dispatched, `lb-error` replaces it
+  on failure, and the next request clears it
+- a path with no page host reports and opens the unknown-page dialog; two
+  hosts for one name report and take the first
+- `lb-navigation` lands with the path and the label of the link that names it
+- `lb-nav-link` pushes state and swaps the host, `popstate` reverses it, and
+  an ordinary anchor is left alone
+- `hidden` comes off the body once a page has landed, including the page
+  that failed to load
 
 Widgets are small and their logic is local, so jsdom carries them: a value
 reaches the control the widget owns, a change dispatches the declared action,
@@ -183,19 +216,16 @@ painting, or navigation.
 
 ## Not built: the browser tier
 
-The hub is where jsdom stops being evidence. Fetch, `history.pushState`,
-`popstate`, and the claim that insertion and hydration in one synchronous
-block never paint an empty frame are all statements about a browser.
+Tier 4 stops at the document. A real network and a real frame are statements
+about a browser, and stubbing either of them proves nothing about it.
 
 No browser test runner is installed and none of the following exists. They
 are recorded here as the shape of the work, not as coverage:
 
 1. a cold load fills `<main>` with no empty flash
-2. `lb-nav-link` pushes state, swaps the host and lands data; `popstate`
-   reverses it; an ordinary anchor is not hijacked
-3. a native action button produces the same event a widget produces
-4. the wizard never displays a step the server has not confirmed
-5. the view-source invariant
+2. the ten-second deadline aborts a request that never answers
+3. the wizard never displays a step the server has not confirmed
+4. the view-source invariant
 
 The last is the one worth a browser. Loadbare's central claim is that no
 markup exists in the DOM that is not in view-source, and that the difference

package/docs/theory.md

@@ -138,7 +138,7 @@ returns data objects.  The HTML contains attributes identifying how
 elements are bound to data, so the framework can update them.
 
 This should be self-evidently efficacious for scalar cells and
-tuples.  Something like `<span lb-query="siteStats" lb-cell="visitCount"></span>`
+rows.  Something like `<span lb-row="siteStats" lb-cell="visitCount"></span>`
 or the same type of addressing for an input makes it trivial to 
 both hyrdrate and refresh forms, and to gather a form's values
 to send to the server.
@@ -325,7 +325,7 @@ Javascript seems cool if you need a fully mutatable DOM, but when you realize
 you don't need that, it's back to plain old reliable HTML.
 
 Another big win is the server code for pages.  The clean organization
-of hooks, actions, CRUD and queries without boilerplate is pure
+of requests, actions, CRUD and queries without boilerplate is pure
 Essential Complexity.  The automatic building of the API and 4 lines to
 handle it in Express is lower than I have seen in any other tool.