@loadbare/app 0.18.2 → 0.19.1

package/skills/loadbare-app/references/miswarts.md

@@ -0,0 +1,140 @@
+# Miswarts
+
+A miswart is a place where Loadbare/app breaks one of its own rules.
+Anybody paying attention will see it as a violation, and they will be
+right.  Yet in context it turns out to be the RightThing(tm), and doing it
+any other way would be worse for the user or the developer.
+
+The reference describes each miswart's behavior where it applies, and
+links here.  This document is the one place that admits they are
+exceptions, and says why each one is allowed to stay.
+
+## The test
+
+A miswart must be:
+
+- **Small.**  It can be stated in a sentence or two.
+- **Orthogonal.**  It has no interaction with any other miswart.
+- **Terminating.**  It does not, by logical extension, require another
+  miswart.  If fixing the edges of one exception calls for a second, we
+  probably should be looking for a weakness in earlier implementation
+  decisions. 
+
+Each entry also names two things:
+
+- **The rule it breaks.**  If we cannot name the rule, it is not a
+  miswart, it is undocumented behavior.
+- **The motivation that justifies it**: performance, correctness or
+  ergonomics, as set out in the theory document.  That is what makes it
+  the RightThing(tm) rather than a convenience.
+
+## Radio button names in a row template
+
+**What.**  The hub stamps the `name` of each radio button in a row
+template with the `name` written, or its column when none is, followed by
+`-` and the live row's key.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness.  The browser groups radio
+buttons by `name`, and a row template repeats one `name` in every live
+row, so without the stamp every row's buttons would form a single group,
+and checking one row would uncheck all the others.
+
+**Why it terminates.**  It applies only to radio buttons inside a row
+template, and only the `name`.
+
+## Checkboxes and radio groups always gather a value
+
+**What.**  An unchecked checkbox gathers `"false"`, a checked one
+`"true"`, and its `value` attribute means nothing to the hub.  A radio
+group with none checked gathers `""`.
+
+**Rule broken.**  Where HTML already has an opinion, Loadbare/app
+follows it.  HTML sends a checkbox's `value` when it
+is checked, and sends nothing for an unchecked checkbox or an empty radio
+group.
+
+**Why it is the RightThing(tm).**  Correctness.  A write must be able to
+set a flag back to false, or clear a choice, and nothing on the wire
+cannot say either.
+
+**Why it terminates.**  It applies only to gathering from these two
+controls.  Landing still follows HTML's own idea of checked.
+
+## Rows hidden by a filter
+
+**What.**  A row that does not pass the user's filter gets the `hidden`
+attribute, and so does a group whose rows are all hidden.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Performance and ergonomics.  A filter
+over rows already on the page needs no round trip, and `hidden` is HTML's
+own word for an element that is present but not shown.  A stamp of our
+own would make every stylesheet restate what the browser already does.
+
+**Why it terminates.**  It applies only to live rows and groups under a
+filter.
+
+## Leaving rows are inert
+
+**What.**  A row on its way out takes `inert` while its animation runs,
+and is removed when the animation finishes.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness.  A row that is gone from
+the database must not take a click or the focus during its exit
+animation, and `inert` is exactly HTML's word for that.
+
+**Why it terminates.**  It applies only to a row already stamped
+`lb-row-leaving`, which never comes back.
+
+## Busy elements carry aria-busy
+
+**What.**  While an element's request is in flight, it carries
+`aria-busy="true"` alongside `lb-request-pending`.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness, for a user of assistive
+technology.  `lb-request-pending` tells a stylesheet, and `aria-busy` tells
+a screen reader, the same fact.
+
+**Why it terminates.**  It rides with `lb-request-pending` and nothing
+else.
+
+## The hub unhides the body
+
+**What.**  When the chrome writes `<body hidden>`, the hub removes
+`hidden` once the first page has landed.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Performance, as the user perceives it.
+Without it, the first load blinks an empty page before the data lands.
+Only the hub knows when the first page has landed.
+
+**Why it terminates.**  It happens once, to `<body>`, and only when the
+application opted in by writing `hidden`.
+
+## `lb-url` lands every parm it names
+
+**What.**  When `lb-url` lands, a query parm the URL does not carry lands
+empty on every element naming it as a column.
+
+**Rule broken.**  Landing a row sets the columns the row carries, and
+leaves the rest as they were.
+
+**Why it is the RightThing(tm).**  Correctness.  A control must show what
+the address bar says, after Back as well as after a reload, and a parm
+that is absent from the URL is a parm whose value is empty.
+
+**Why it terminates.**  It applies only to `lb-url`, the one query whose
+columns are the URL itself.

package/skills/loadbare-app/references/names.md

@@ -0,0 +1,250 @@
+# Names
+
+Every name Loadbare/app owns, in one place.  Each row links to the section
+that defines it, and the definition lives there and only there.
+
+An application names nothing with the `lb-` prefix: no attribute, query,
+column, request, command, custom element or event.  A name Loadbare has not
+defined today it may define tomorrow.  `createHub` refuses at startup a page
+that declares a query, a handler or a `crud` entry whose name begins with
+`lb-`, and the builder refuses the rest; see
+[The markup checks](./data-binding.md#the-markup-checks).
+
+## Builder flags
+
+| Flag       | Default | Names                                     | Defined in                                          |
+| ---------- | ------- | ----------------------------------------- | --------------------------------------------------- |
+| `--src`    | `src`   | The application's own tree, scanned whole | [Running the builder](./builder.md#running-the-builder) |
+| `--out`    | `dist`  | Where the builder writes                  | [Running the builder](./builder.md#running-the-builder) |
+| `--watch`  | off     | Rebuild on change under `--src`           | [Running the builder](./builder.md#running-the-builder) |
+| `--minify` | off     | Minify `client.js` and `app.css`          | [Running the builder](./builder.md#running-the-builder) |
+
+## Reserved file names
+
+A file so named carries its meaning wherever it sits in the `--src` tree,
+so an application uses none of these names for anything else.
+
+| File                    | How many                       | Holds                                                    | Defined in                                          |
+| ----------------------- | ------------------------------ | -------------------------------------------------------- | --------------------------------------------------- |
+| `chrome.html`           | Exactly one                    | The application's one HTML document                      | [chrome.html](./chrome.md)                          |
+| `imports.ts`            | Zero or one                    | Default-exports an array of widget package names         | [Widgets from packages](./builder.md#widgets-from-packages) |
+| `<stub>.page.html`      | One per page                   | One page's markup, as a fragment                         | [HTML](./page-files.md#html)                        |
+| `<stub>.queries.ts`     | Zero or one per page           | That page's queries                                      | [Queries](./page-files.md#queries)                  |
+| `<stub>.requests.ts`    | Zero or one per page           | That page's requests                                     | [Requests](./page-files.md#requests)                |
+| `<tag-name>.html`       | Zero or one per custom element | One element file, as a fragment                          | [HTML](./custom-elements.md#html)                   |
+| `<tag-name>.browser.ts` | Zero or one per custom element | One custom element's script, `.js` also accepted         | [Code](./custom-elements.md#code)                   |
+| `*.css`                 | Any number                     | A stylesheet, concatenated into `app.css`                | [CSS](./css.md)                                     |
+
+## Build outputs
+
+The builder writes these into `--out`.
+
+| File              | Written           | Holds                                                              | Defined in                                              |
+| ----------------- | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
+| `app.html`        | Always            | The chrome, with every page inside a `<template>`                  | [What the builder writes](./builder.md#what-the-builder-writes) |
+| `client.js`       | Always            | `<lb-hub>` and every custom element the application uses           | [What the builder writes](./builder.md#what-the-builder-writes) |
+| `client-entry.ts` | Always            | The generated entry `client.js` is bundled from                    | [What the builder writes](./builder.md#what-the-builder-writes) |
+| `app.css`         | With a stylesheet | Every stylesheet in the cascade, concatenated                      | [CSS](./css.md)                                         |
+| `pages.ts`        | With page data    | The one `createHub()` call, over every page's queries and requests | [Running the server](./server.md#running-the-server)    |
+
+## Reserved package.json keys
+
+A widget package declares these.  An application never does.
+
+| Key                | Value                     | Means                                                              | Defined in                                          |
+| ------------------ | ------------------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
+| `loadbare.widgets` | A path inside the package | Where its custom elements are; absent means the whole installed directory | [Widgets from packages](./builder.md#widgets-from-packages) |
+
+## Reserved namespaces
+
+| Namespace | Applies to                                                  | Loadbare owns                                     | Defined in                                       |
+| --------- | ----------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ |
+| `lb-*`    | Attributes, their values, queries, columns of `lb-` queries, requests, custom elements, events | The names and their behavior | [Attributes](#attributes)                        |
+| `--lb-*`  | Values of HTML's `command` attribute                        | The names and their behavior                      | [Reserved commands](#reserved-commands)          |
+| `exp-*`   | Attributes on a custom element                              | The behavior; element file authors pick the names | [Parameters](./custom-elements.md#parameters)    |
+| `lb*`     | Methods on custom elements: `lb` and a capital              | The names and their behavior                      | [Reserved methods](#reserved-methods)            |
+
+## Attributes
+
+The developer writes sixteen attributes in pages and the chrome, and the
+builder refuses any other `lb-` attribute there.  `lb-exp-slot` and
+`lb-exp-template` are written for expansion, which removes them before the
+check.  The hub and the builder write the rest, as stamps, and script never
+assigns one.
+
+| Attribute            | Written by      | Defined in                                                       |
+| -------------------- | --------------- | ---------------------------------------------------------------- |
+| `lb-query`           | Developer       | [Landing](./data-binding.md#landing)                             |
+| `lb-column`          | Developer       | [Landing](./data-binding.md#landing)                             |
+| `lb-show`            | Developer       | [Conditional rendering](./data-binding.md#conditional-rendering) |
+| `lb-order`           | Developer       | [Order](./data-binding.md#order)                                 |
+| `lb-filter`          | Developer       | [Filters](./data-binding.md#filters)                             |
+| `lb-group`           | Developer       | [Groups](./data-binding.md#groups)                               |
+| `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max` | Developer | [Aggregates](./data-binding.md#aggregates)       |
+| `lb-select`          | Developer       | [Selecting rows](./data-binding.md#selecting-rows)               |
+| `lb-request`         | Developer       | [Requests](./data-binding.md#requests)                           |
+| `lb-url-link`        | Developer       | [Links](./chrome.md#links)                                       |
+| `lb-url-push`        | Developer       | [Query parms](./chrome.md#query-parms)                           |
+| `lb-url-unknown`     | Developer       | [An unknown page](./chrome.md#an-unknown-page)                   |
+| `lb-exp-slot`        | Developer, consumed by expansion | [The slot](./custom-elements.md#the-slot)       |
+| `lb-exp-template`    | Developer, consumed by expansion | [Destinations](./custom-elements.md#destinations) |
+| `lb-column-value`    | Hub             | [Where a column lands](./data-binding.md#where-a-column-lands)   |
+| `lb-key-value`       | Hub             | [Landing](./data-binding.md#landing), [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `lb-row-live`        | Hub             | [Landing](./data-binding.md#landing)                             |
+| `lb-query-row-count` | Hub             | [Counting rows](./data-binding.md#counting-rows)                 |
+| `lb-group-live`, `lb-group-column`, `lb-group-value` | Hub | [Groups](./data-binding.md#groups)                       |
+| `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
+| `lb-row-leaving`, `lb-group-leaving` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
+| `lb-row-editing`     | Hub             | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `lb-row-selected`    | Hub             | [Selecting rows](./data-binding.md#selecting-rows)               |
+| `lb-request-pending` | Hub             | [Request state](./data-binding.md#request-state)                 |
+| `lb-request-error`   | Hub             | [Request state](./data-binding.md#request-state)                 |
+| `lb-request-refused` | Hub             | [Refusals](./data-binding.md#refusals)                           |
+| `lb-show` on a `<template>` | Hub and builder | [Where an absent element is](./data-binding.md#where-an-absent-element-is) |
+| `lb-page`            | Builder         | [What the builder writes](./builder.md#what-the-builder-writes)  |
+| `lb-page-title`      | Builder         | [The page title](./page-files.md#the-page-title)                 |
+
+## Reserved queries
+
+The hub serves these in the browser.  Every page and the chrome may name
+them, and a page declares neither.
+
+| Query        | Kind  | Key       | Columns                                                         | Defined in                            |
+| ------------ | ----- | --------- | --------------------------------------------------------------- | ------------------------------------- |
+| `lb-url`     | `row` | `lb-path` | `lb-path`, `lb-page-label`, `lb-page-unknown`, every query parm | [The URL](./chrome.md#the-url)        |
+| `lb-choices` | `row` | `lb-path` | `lb-path`, every choice                                         | [Choices](./data-binding.md#choices)  |
+
+No query parm is reserved: a column of `lb-url` whose name begins with
+`lb-` is never a query parm.
+
+## Reserved request names
+
+| Request name    | Runs under `crud` | Defined in                                                                  |
+| --------------- | ----------------- | --------------------------------------------------------------------------- |
+| `lb-row-insert` | `rowInsert`       | [Inserting, updating and deleting rows](./data-binding.md#inserting-updating-and-deleting-rows) |
+| `lb-row-update` | `rowUpdate`       | [Inserting, updating and deleting rows](./data-binding.md#inserting-updating-and-deleting-rows) |
+| `lb-row-delete` | `rowDelete`       | [Inserting, updating and deleting rows](./data-binding.md#inserting-updating-and-deleting-rows) |
+
+## Reserved commands
+
+Loadbare/app owns every value of HTML's `command` attribute beginning with
+`--lb-`.
+
+| Command        | Defined in                                                               |
+| -------------- | ------------------------------------------------------------------------ |
+| `--lb-edit`    | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `--lb-new`     | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `--lb-release` | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+
+## Reserved tags
+
+An application writes these and never defines them.
+
+| Tag        | Written in | Means                          | Defined in                                         |
+| ---------- | ---------- | ------------------------------ | -------------------------------------------------- |
+| `<lb-hub>` | The chrome | The application's live element | [The parts of a chrome](./chrome.md#the-parts-of-a-chrome) |
+
+## Reserved events
+
+Loadbare/app owns each event's name and what its `detail` carries.
+
+| Event             | Dispatched from            | Bubbles | Cancelable | Defined in                                                  |
+| ----------------- | -------------------------- | ------- | ---------- | ----------------------------------------------------------- |
+| `lb-request`      | The element that committed | Yes     | No         | [The request event](./data-binding.md#the-request-event)    |
+| `lb-request-done` | The element that committed | Yes     | No         | [Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out) |
+
+## Reserved methods
+
+The build refuses a custom element script declaring any other method,
+accessor or field named `lb` and a capital.
+
+| Method          | On                                                     | Defined in                                                  |
+| --------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
+| `lbAttached`    | Any custom element the hub places                      | [When its code runs](./custom-elements.md#when-its-code-runs) |
+| `lbRowsLanded`  | A custom element with `lb-query` and a row template    | [Holding rows](./custom-elements.md#holding-rows)           |
+| `lbRequestDone` | A custom element that committed, or holds one that did | [Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out) |
+| `lbDetached`    | Any custom element the hub removes                     | [When its code runs](./custom-elements.md#when-its-code-runs) |
+
+## Exports
+
+| Entry point                | Exports                                                          | Defined in                                     |
+| -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| `@loadbare/app/server`     | `row`, `rows`, `patch`, `url`, `choices`, `refusal`, `createHub`, and the types `Queries`, `Requests`, `HubContext`, `Hub` | [Page Files](./page-files.md), [The data channel](./server.md#the-data-channel) |
+| `@loadbare/app/express`    | `hubRoutes`                                                      | [The Express Server](./server.md)              |
+| `@loadbare/app/types`      | `HubRequest`, `ResponseItem`, `HubRequestDone`, `HubLifecycle`, and the rules the hub applies: `readAs`, `parseFilter`, `passes`, `passesTerm` | [The data channel](./server.md#the-data-channel), [Order](./data-binding.md#order), [Filters](./data-binding.md#filters) |
+| `@loadbare/app`            | `applyRow`                                                       | [Filling a subtree by hand](./custom-elements.md#filling-a-subtree-by-hand) |
+| `@loadbare/app/constants`  | Every name on this page; see [Constants](#constants)             | [Code](./custom-elements.md#code)              |
+
+## Constants
+
+`@loadbare/app/constants` exports every name above.  Custom element code
+imports them rather than writing a string.
+
+| Constant                  | Value                                   |
+| ------------------------- | --------------------------------------- |
+| `ATTR_QUERY`              | `lb-query`                              |
+| `ATTR_COLUMN`             | `lb-column`                             |
+| `ATTR_SHOW`               | `lb-show`                               |
+| `SHOW_NOT`                | `!`, written before a column in `lb-show` |
+| `ATTR_COLUMN_VALUE`       | `lb-column-value`                       |
+| `ATTR_KEY_VALUE`          | `lb-key-value`                          |
+| `ATTR_ROW_LIVE`           | `lb-row-live`                           |
+| `LIVE_ROW`                | `[lb-row-live]`, the selector for a live row |
+| `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
+| `ATTR_GROUP`              | `lb-group`                              |
+| `ATTR_GROUP_LIVE`         | `lb-group-live`                         |
+| `ATTR_GROUP_COLUMN`       | `lb-group-column`                       |
+| `ATTR_GROUP_VALUE`        | `lb-group-value`                        |
+| `LIVE_GROUP`              | `[lb-group-live]`, the selector for a group's element |
+| `ATTR_COUNT`, `ATTR_SUM`, `ATTR_AVG`, `ATTR_MIN`, `ATTR_MAX` | `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max` |
+| `AGGREGATES`              | All five aggregate attributes           |
+| `ORDER_DESCENDING`        | `-`, written before a column in an order |
+| `COLUMN_TYPES`            | `number`, `boolean`, `text`             |
+| `CHOICES_QUERY`           | `lb-choices`                            |
+| `ATTR_ORDER`              | `lb-order`                              |
+| `ATTR_FILTER`             | `lb-filter`                             |
+| `FILTER_OPERATORS`        | Every filter operator, the longer first |
+| `ATTR_ROW_CREATED`        | `lb-row-created`                        |
+| `ATTR_ROW_CHANGED`        | `lb-row-changed`                        |
+| `ATTR_ROW_MOVED`          | `lb-row-moved`                          |
+| `ATTR_ROW_REQUESTED`      | `lb-row-requested`                      |
+| `REQUESTED_CREATED`, `REQUESTED_CHANGED`, `REQUESTED_MOVED` | `created`, `changed`, `moved` |
+| `ATTR_ROW_LEAVING`        | `lb-row-leaving`                        |
+| `ATTR_GROUP_LEAVING`      | `lb-group-leaving`                      |
+| `ATTR_REQUEST`            | `lb-request`                            |
+| `LB_EVENT_NAME`           | `lb-request`, the event every request travels as |
+| `LB_DONE_EVENT_NAME`      | `lb-request-done`                       |
+| `ATTR_REQUEST_PENDING`    | `lb-request-pending`                    |
+| `ATTR_REQUEST_ERROR`      | `lb-request-error`                      |
+| `ATTR_REQUEST_REFUSED`    | `lb-request-refused`                    |
+| `LB_REFUSAL_STATUS`       | `422`                                   |
+| `COMMAND_EDIT`, `COMMAND_NEW`, `COMMAND_RELEASE` | `--lb-edit`, `--lb-new`, `--lb-release` |
+| `LB_COMMANDS`             | All three commands                      |
+| `LB_COMMAND_PREFIX`       | `--lb-`                                 |
+| `ATTR_ROW_EDITING`        | `lb-row-editing`                        |
+| `ATTR_SELECT`             | `lb-select`                             |
+| `ATTR_ROW_SELECTED`       | `lb-row-selected`                       |
+| `LB_RESERVED_PREFIX`      | `lb-`                                   |
+| `REQUEST_ROW_INSERT`      | `lb-row-insert`                         |
+| `REQUEST_ROW_UPDATE`      | `lb-row-update`                         |
+| `REQUEST_ROW_DELETE`      | `lb-row-delete`                         |
+| `LB_ROW_REQUESTS`         | All three request names                 |
+| `LB_METHODS`              | The four reserved methods               |
+| `BROWSER_LIFECYCLE`       | The browser callbacks the build refuses |
+| `KIND_ROW`                | `row`                                   |
+| `KIND_ROWS`               | `rows`                                  |
+| `URL_QUERY`               | `lb-url`                                |
+| `URL_COLUMN_PATH`         | `lb-path`                               |
+| `URL_COLUMN_PAGE_LABEL`   | `lb-page-label`                         |
+| `URL_COLUMN_PAGE_UNKNOWN` | `lb-page-unknown`                       |
+| `ATTR_URL_LINK`           | `lb-url-link`                           |
+| `ATTR_URL_PUSH`           | `lb-url-push`                           |
+| `ATTR_URL_UNKNOWN`        | `lb-url-unknown`                        |
+| `ATTR_EXP_SLOT`           | `lb-exp-slot`                           |
+| `ATTR_EXP_TEMPLATE`       | `lb-exp-template`                       |
+| `ATTR_PAGE`               | `lb-page`                               |
+| `ATTR_PAGE_TITLE`         | `lb-page-title`                         |
+| `DEVELOPER_ATTRIBUTES`    | The sixteen attributes a developer writes |
+| `HUB_TAG_NAME`            | `lb-hub`                                |
+| `LB_ENDPOINT`             | `/lb`                                   |
+| `LB_REQUEST_TIMEOUT_MS`   | `10000`                                 |

package/skills/loadbare-app/references/overview.md

@@ -38,3 +38,9 @@ serves, and the custom elements those pages are made of.
 | [`<tag-name>.html`](./custom-elements.md#html)         | The markup the tag expands into |
 | [`<tag-name>.browser.ts`](./custom-elements.md#code)   | The class the tag registers     |
 | [The Basic Widget Library](./widgets.md)               | `@loadbare/widgets`             |
+
+## Names
+
+| Topic                    | Description                                                  |
+|--------------------------|--------------------------------------------------------------|
+| [Names](./names.md)      | Every name Loadbare owns, the constants, and where each is defined |

package/skills/loadbare-app/references/page-files.md

@@ -14,7 +14,9 @@ Name the landing page `index.page.html`. A bare `/` resolves to `index`, and
 every other path names the page whose stub it is.
 
 Put the files anywhere under `src/`. The builder pairs them by stub, not by
-directory; `src/pages/` is the convention.
+directory; `src/pages/` is the convention. The page namespace is flat, so
+`src/deep/path/mypage.page.html` is the page for `/mypage`, and a stub is
+unique across the application.
 
 ## What the page files are
 
@@ -122,8 +124,19 @@ including a `row` query's: an aggregate row answers with a constant key. The
 hub matches rows to live rows by key, and a request names a row by key.
 
 Kind and key belong to the name, so one name answers with one shape, always,
-and `createHub` leaves out an answer that disagrees with its declaration. A
-page that needs the same data as one row and as a set declares two queries.
+and `createHub` leaves out an answer that disagrees with its declaration,
+with a warning naming the query. A page that needs the same data as one row
+and as a set declares two queries.
+
+`createHub` refuses at startup a page that declares a query, a handler or a
+`crud` entry whose name begins with `lb-`, a query whose order has a term
+naming no column, and a type it does not know.
+
+Every query and every handler receives `ctx`, the application's own request
+context, built by `contextFor`; see
+[the Express server](./server.md#database-layer). Loadbare declares it
+empty and never reads it, so a query finds exactly what the application put
+there.
 
 The hub hands each value to the browser untouched, so what a number, a date
 or a null looks like is decided here, in the query.
@@ -229,13 +242,21 @@ export const requests: Requests = {
 };
 ```
 
-Declare every request the page allows. The server refuses a name the page
-does not declare.
+Declare every request the page allows. The builder refuses markup naming a
+request the page does not declare; see
+[The markup checks](./data-binding.md#the-markup-checks). One can still
+arrive, from a widget's script or from outside the page. The server then
+warns on its console, naming the page and the missing entry, and answers
+200 with no response items, so nothing lands and `lb-request-pending`
+clears. A request carrying no name answers 400, and a `run` that throws
+anything but a [refusal](#refusing-a-request) answers 500.
 
 ### crud
 
 Declare what the three requests Loadbare provides do under `crud`, keyed by
-the query they operate on:
+the query they operate on. Each key is the request name with its `lb-`
+stripped and the rest camel-cased, so the attribute, the wire and the key
+are one vocabulary:
 
 | Request name    | Runs        | `run` receives   |
 |-----------------|-------------|------------------|
@@ -293,8 +314,10 @@ export const requests: Requests = {
 };
 ```
 
-Declare every request the query permits. The server refuses a request a
-query does not declare, and a query with no `crud` entry permits none.
+Declare every request the query permits. The builder refuses markup sending
+a request a query does not declare, and the server answers one that arrives
+anyway as it does an undeclared handler, with a console warning and nothing
+to land. A query with no `crud` entry permits none.
 
 Write `rowUpdate` to set the columns `values` names and leave every other
 column as it is. A form or a live row sends every control it gathers, and a
@@ -303,6 +326,36 @@ columns the page may edit.
 
 Every value in `values` is a string, as a control's value is.
 
+Two users writing the same row overlap only on the columns their requests
+carry, and the last write wins.  A single control sends its own column, so
+two users editing different columns of a row do not overwrite each other.
+A form sends every control it gathers, so two forms saved over one row
+overlap on all of their columns.
+
+A write whose outcome matters states its precondition in its own SQL, and
+refuses when no row was updated:
+
+```ts
+handlers: {
+  approve: {
+    run: async (ctx, { key }) => {
+      const updated = await ctx.db.run(
+        "UPDATE invoice SET status = 'approved' WHERE id = $1 AND status = 'pending'",
+        [key],
+      );
+      if (updated === 0) {
+        throw refusal("Someone else has already decided this invoice.");
+      }
+    },
+    refresh: ["invoice"],
+  },
+},
+```
+
+The request's name says what the user meant, and the precondition follows
+from it, so no earlier value is needed.  See
+[Refusing a request](#refusing-a-request).
+
 ### refresh and patch
 
 List in `refresh` every query whose whole answer the request changed.
@@ -342,7 +395,7 @@ removing a row never reorders the rest. So does an insert, which has the new
 row's key once it has written it, and the hub places the new row by the
 query's order. `createHub` refuses at startup a `crud` `rowInsert`,
 `rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names that same
-query.
+query. A `row` query sends one row and may refresh itself.
 
 Each request's `refresh` is its own, and every query in it needs its own
 reason. A list shared by several requests is a warning sign.
@@ -408,6 +461,21 @@ nothing else `run` returned is sent, since both answered for the URL the page
 left. The loaded page reads the new parms through `contextFor`; see
 [the Express server](./server.md#database-layer).
 
+- A `url()` naming no column, or holding a value that is not a string, is
+  warned about on the server console and ignored, and the refresh set runs
+  as usual.
+- If loading the page fails, the write has still happened. The response
+  carries the `lb-url` item alone, and the hub loads the page itself. A
+  failure there is a page load's, and is not stamped on the element that
+  sent the request.
+- A user who has moved by the time the response arrives, to another page or
+  to other query parms, keeps the URL they are on.
+
+Saving what the user has on screen, for `onPageEnter` to restore, is a
+declared request with `refresh: []`, whose handler each page passes to a
+routine the application's pages share. A custom element naming `lb-url`
+sees every change of the URL and sends it.
+
 ### Refusing a request
 
 A handler refuses a request by throwing `refusal()`, with words written for

package/skills/loadbare-app/references/server.md

@@ -17,7 +17,7 @@ import { readFileSync } from "node:fs";
 import express, { type Request } from "express";
 import { hubRoutes } from "@loadbare/app/express";
 import type { HubContext } from "@loadbare/app/server";
-import { hub } from "./dist/pages";
+import { hub } from "./dist/pages.ts";
 import { openDb } from "./src/database";
 
 const DIST = path.resolve("dist");
@@ -181,3 +181,56 @@ open across the two, is both.
 Add a field for anything else a request needs — the authenticated user, a
 request id, a feature flag set. Queries and requests read them from `ctx`; see
 [page files](./page-files.md).
+
+## The data channel
+
+One path, one method. The hub sends every round trip as
+`POST /lb/<stub>?<query string>`, with the query string the browser is
+showing, verbatim. An empty body, or `{}`, asks for the page load. Any other
+body is a request:
+
+```ts
+interface HubRequest {
+  name: string;
+  query?: string;
+  key?: string;
+  keys?: string[];
+  values?: Record<string, string>;
+  rows?: Record<string, { key: string; values: Record<string, string> }[]>;
+}
+```
+
+A refused request is answered with status 422 and
+`{ refusal: { message?, columns? } }`, a request with no name with 400 and
+`[]`, and
+any other failure with 500 and no body; see
+[Refusing a request](./page-files.md#refusing-a-request). Every other
+response is an array of response items:
+
+```ts
+interface ResponseItem {
+  query: string;
+  kind: "row" | "rows";
+  key: string;
+  row?: Row;
+  rows?: Row[];
+  patch?: { rows?: Row[]; drop?: unknown[] };
+}
+```
+
+A response item carries exactly one of `row`, `rows` or `patch`. A patch
+answers a `rows` query only: rows named in `rows` are added or updated, keys
+in `drop` are removed, and every other row is left alone. A `rows` item on
+the answer that loads the page also carries the query's declared `order`
+and `types`, which the hub keeps for every answer after it.
+
+A choice is sent as `lb-row-update` for `lb-choices`, keyed by the path,
+with every choice made on the page as `values`; see
+[Choices](./data-binding.md#choices).
+
+`createHub(pages)` builds the `Hub`, which has two calls, both answering
+with response items: `dataForPage(page, ctx, options)` for a page load, and
+`runRequest(page, request, ctx)` for a request. `options.parms` are the
+parms the page is loaded at, and `options.follow` false ignores a `url()`
+from `onPageEnter`. `hubRoutes` passes both, and an application calls
+neither.