@loadbare/app 0.18.1 → 0.19.0

package/skills/loadbare-app/references/TECHREF-1.0.md

@@ -5,79 +5,6 @@ This is the complete technical reference to the upcoming Release 1.0.
 Method-of-work is to continually revise this document to what we want
 to be true, then revise the code, docs, and tests to ensure it is true.
 
-## Blockers
-
-We cannot declare 1.0 until we determine if these blockers can be
-added later w/o breaking changes.  If we are reasonably confident
-that they can be decided later w/o breaking changes, then we rename
-them to "Out of Scope" or move them to the roadmap.  Otherwise, 
-they must be resolved before we declare 1.0.
-
-### Data types
-
-A value renders by browser coercion when it lands on an HTML text element or
-a control, and by whatever the custom element does with `lb-column-value`
-when it lands on one that is not a control.  A `rows` query may declare a
-column's type, which the [order](#order), a [filter](#filters), `lb-min` and
-`lb-max` read.
-
-- **Decide who formats a value.**  The hub could own formatting, or take it
-  from the application as configuration or as code.
-
-### Nested queries
-
-Imagine an HTML `<select>` that shows a fixed set of choices on every row of
-a table, such as `customer_type` for a table of customers.  When every
-customer may take every customer type, the system as written today is
-fine, because every `<select>` receives the same rows.
-
-But the allowed values may depend on other values in the row.
-
-- **Decide whether a nested query's rows may depend on its row.** A nested
-  query has one answer, which every live row receives.  See
-  [Master-detail](#master-detail) for what a nested query is for.
-
-```html
-<tbody lb-query="accounts">
-  <template><tr>
-    <td lb-column="name"></td>
-    <td><select lb-query="statuses" lb-column="status"><template><option lb-column="label"></option></template></select></td>
-  </tr></template>
-</tbody>
-```
-
-### The server API
-
-- **Land `staticRoutes`.**  It closes the last place where an
-  application hand-writes facts the builder owns.
-
-### The builder
-
-- **Adopt a configuration file and fold `imports.ts` into it.** It holds
-  `out`, `minify` and `imports`, and lives where `imports.ts` lives now, so a
-  repository with several applications gets one per application.  `--src`
-  stays a flag, since it is what locates the file.  State the precedence
-  between a flag and a key once.  Its key names join the permanent surface,
-  so this lands before 1.0 or not at all.  It reserves a key for the
-  roadmap's tree-shaking CSS by tag name.
-- **Confirm the three output names.** `app.html`, `client.js` and `app.css`
-  are about to be fixed in `staticRoutes` as well as in the builder.
-
-### The internal surface
-
-None of this is surface.  It is listed here because trimming it is free
-today and breaking after 1.0.
-
-- **Audit what the hub does.** Every routine it runs answers to an `lb-*`
-  attribute, a [reserved query](#reserved-queries), or a
-  [reserved event](#reserved-events) or [method](#reserved-methods).  Trim
-  whatever does not, and leave what stays clean: no dead code, no routine
-  written twice, no comment the code contradicts.
-- **Keep the rest as constants.** The endpoint, `index` and the timeout are
-  linkage between the builder and the hub rather than facts an application
-  varies.  Adding a knob for any of them buys a second shape of application
-  to reason about.
-
 ## The build
 
 ### Running the builder
@@ -184,8 +111,8 @@ it is sent to the browser on initial page load, no HTML is ever sent
 again.
 
 The developer writes `lb-*` attributes in markup.  Script never assigns
-them.  The hub and the builder write only their stamps, and the hub writes
-the `name` of a radio button in a row template.  See
+them.  The hub and the builder write only their stamps, apart from the
+few exceptions listed in [Miswarts](./miswarts.md).  See
 [The markup checks](#the-markup-checks).
 
 ### Expansion
@@ -483,6 +410,10 @@ landed inside another query, such as a total in a table's foot, is not one
 of that query's rows.  A stylesheet or a custom element selects live rows
 with `[lb-row-live]`, and never with `[lb-key-value]`.
 
+A `row` query answering `null` lands every column its element names as
+null, and the element loses `lb-key-value`.  Under a row template, its live
+row leaves.
+
 A key is unique within a query.  Two rows with one key in the same answer,
 or two live rows showing one key, are reported on the console.
 
@@ -1373,10 +1304,10 @@ new URL carries only the query parms the request names.
 
 Every load lands `lb-url`, and a parm the URL does not carry lands empty on
 every element naming it as a column, so a control shows what the address
-bar says after Back as well as after a reload.  This is the one exception
-to landing, where a row sets the columns it names and leaves the rest as
-they were: the hub reads the column names under `lb-query="lb-url"` and
-names each one in the row it lands.
+bar says after Back as well as after a reload
+([miswart](./miswarts.md#lb-url-lands-every-parm-it-names)): the hub reads the
+column names under `lb-query="lb-url"` and names each one in the row it
+lands.
 
 The hub sends the query parms with every round trip, a page load and a
 request alike.  The server passes them to `contextFor` — see
@@ -1525,6 +1456,15 @@ to build on any of these:
   reach the check.
 - `lb-request` naming a value that begins with `lb-` and is not one of the
   three request names.
+- `lb-query` naming a query the page does not declare.  `lb-url` and
+  `lb-choices` are the hub's, and every page and the chrome may name them.
+  The chrome belongs to no page, and names no other query.
+- `lb-request` naming a request the page does not declare under `handlers`.
+  The chrome sends none of them.
+- One of the three request names for a query whose `crud` entry does not
+  declare it, and any but `lb-row-update` for `lb-url` or `lb-choices`.  The
+  query is a form's own when the form carries `lb-query`, and otherwise the
+  nearest `lb-query` around the element.
 - `lb-url-link` on anything but an `<a>`.
 - `lb-url-push` on an element with no `lb-request`.
 - `lb-url-unknown` on anything but a `<dialog>`, and in the chrome, outside
@@ -1554,6 +1494,10 @@ whose name begins with `lb` and a capital and is not in
 
 `lb-column` with no ancestor row is allowed: the hub gathers from it.
 
+To know what each page declares, the builder loads the page's
+`.queries.ts` and `.requests.ts` modules, so their import-time code runs
+during the build, as it does when the server starts.
+
 Script never assigns an `lb-` attribute, so the markup states every one
 that exists, and checking the markup is sound.
 
@@ -1566,7 +1510,8 @@ uncommon, and Loadbare/app does not shape itself around them.
   by `name`, and a row template repeats one `name` in every live row.  The
   hub stamps each radio button's `name` with the `name` written, or its
   column when none is, followed by `-` and the live row's key, so each live
-  row holds a group of its own.
+  row holds a group of its own
+  ([miswart](./miswarts.md#radio-button-names-in-a-row-template)).
 - **Several rows not yet entered, each holding radio buttons.**  A
   [row not yet entered](#a-row-not-yet-entered) has an empty key, so the
   radio buttons of every such row share one `name` and form one group.
@@ -1795,8 +1740,8 @@ export const queries: Queries = {
 };
 ```
 
-A `row` query returns one object, and a `rows` query returns an array of
-objects, which the page shows in that order when the query declares none.  An answer that disagrees with
+A `row` query returns one object, or `null` when it finds no row, and a
+`rows` query returns an array of objects, which the page shows in that order when the query declares none.  An answer that disagrees with
 its declared kind is left out of the response, with a warning naming the
 query.
 
@@ -1828,9 +1773,12 @@ It has four optional keys.
 | `onChoices`   | Nothing               | Runs with every choice made on the page, each time the user makes one |
 
 The server resolves a declared request against `handlers`, and a request
-Loadbare provides against `crud` under the request's query.  A name with no
-entry there logs a server console warning naming the page and the missing
-entry, and answers 200 with no response items, so nothing lands and
+Loadbare provides against `crud` under the request's query.  The builder
+refuses markup naming a request the page does not declare; see
+[The markup checks](#the-markup-checks).  A name with no entry there can
+still arrive, from a widget's script or from outside the page, and it
+logs a server console warning naming the page and the missing entry, and
+answers 200 with no response items, so nothing lands and
 `lb-request-pending` clears from the element that issued the request.  A
 request carrying no name answers 400, and a `run` that throws answers 500.
 

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

@@ -128,11 +128,18 @@ substitution rules — wraps each expanded page in
 `<template lb-page="<stub>">`, and splices them into the chrome's `<body>`.
 It removes a page file's `<title>` and stamps its text on the page's
 template as `lb-page-title`; see [The page title](./page-files.md#the-page-title).
-It formats the result with Prettier when the application has it installed.
+It formats the result with Prettier, which ships with `@loadbare/app`, and
+keeps the unformatted result if Prettier fails.
 
 The builder checks the `lb-` attributes of the chrome and every page after
 expansion, and stops on the first file with a problem; see
-[The markup checks](./data-binding.md#the-markup-checks).
+[The markup checks](./data-binding.md#the-markup-checks). The names
+`lb-query` and `lb-request` carry are checked against what each page
+declares, which the builder reads by loading the page's `.queries.ts` and
+`.requests.ts` modules. Their import-time code runs during the build, as it
+does when the server starts, so a module that connects to a database at
+import connects during the build too; open connections in `contextFor`
+instead.
 
 The builder writes `app.css` only when it finds a stylesheet, and `pages.ts`
 only when some page has a `.requests.ts` or a `.queries.ts` file. Import `hub`

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

@@ -224,7 +224,8 @@ being visibly empty — so it's the whole document that needs to wait, not
 just the piece that was empty.
 
 The `<noscript>` block is the escape hatch for a visitor with JavaScript
-disabled. `<lb-hub>` is what removes `hidden` from `<body>`, so a browser
+disabled. `<lb-hub>` is what removes `hidden` from `<body>`
+([miswart](./miswarts.md#the-hub-unhides-the-body)), so a browser
 that never runs `client.js` would otherwise be stuck looking at a
 permanently blank page. `<noscript>` content is only rendered when scripting
 is off, so the fallback rule only ever applies in exactly that case — it

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

@@ -42,3 +42,166 @@ See [`chrome.html`](./chrome.md) for the link, [The Express
 server](./server.md) for the route, and
 [`loadbare-app-build`](./builder.md#running-the-builder) for `--minify`.
 </content>
+
+## Selecting what the hub stamps
+
+The hub tells a stylesheet everything it knows through attributes, so an
+application styles state with selectors and writes no script for it.  Each
+stamp is an `lb-` attribute the hub writes; never write one in markup.
+
+### A value
+
+Every element a column lands on carries the value as `lb-column-value`,
+exactly as the query sent it, and loses it when the value is null.  Select
+on the column and the value:
+
+```css
+[lb-column="status"][lb-column-value="locked"] { opacity: 0.5; }
+[lb-column="balance"][lb-column-value^="-"] { color: var(--negative); }
+[lb-column="note"]:not([lb-column-value]) { display: none; }
+```
+
+A widget that formats its value, such as `lb-number`, keeps the raw value
+in the stamp, so the selector reads the number and not its text.  See
+[Where a column lands](./data-binding.md#where-a-column-lands).
+
+### A row
+
+| Select               | For                                             |
+|----------------------|-------------------------------------------------|
+| `[lb-row-live]`      | Every live row of a list                        |
+| `[lb-row-selected]`  | A row its `lb-select` checkbox ticks            |
+| `[lb-row-editing]`   | The row a pointed form is editing               |
+| `[lb-key-value="…"]` | One row, by its key                             |
+| `[hidden]`           | A row a filter hides; the browser hides it      |
+
+An element a `row` query lands on carries `lb-key-value` while the query has
+a row, and loses it when the query answers `null`:
+
+```css
+[lb-query="member"]:not([lb-key-value]) .member-missing { display: revert; }
+```
+
+Select live rows with `[lb-row-live]`, never with `[lb-key-value]`: a `row`
+landed inside a list, such as a total in a table's foot, carries a key and
+is not one of the list's rows.
+
+```css
+[lb-row-selected] { background: var(--selected); }
+[lb-row-editing] { outline: 2px solid var(--accent); }
+```
+
+See [Rows](./data-binding.md#rows), [Selecting rows](./data-binding.md#selecting-rows)
+and [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form).
+
+### A group
+
+Each top-level element of a group carries `lb-group-live`, the column it
+breaks on as `lb-group-column`, and its value there as `lb-group-value`:
+
+```css
+[lb-group-column="category"][lb-group-value="Income"] { color: var(--income); }
+```
+
+See [Groups](./data-binding.md#groups).
+
+### What just happened to a row
+
+The hub stamps what its last landing did, so a stylesheet animates with
+nothing else:
+
+| Select                         | For                                            |
+|--------------------------------|------------------------------------------------|
+| `[lb-row-created]`             | A row that arrived                             |
+| `[lb-row-changed]`             | A row whose values changed                     |
+| `[lb-row-moved]`               | A row whose values changed and now stands elsewhere; it carries `lb-row-changed` too |
+| `[lb-row-requested]`           | Any of the three, done by this page's request, as `created`, `changed` or `moved` |
+| `[lb-row-leaving]`, `[lb-group-leaving]` | A row or group on its way out; the hub removes it when its animations end |
+
+```css
+[lb-row-created] { animation: arrive 200ms; }
+[lb-row-requested="changed"] { animation: flash 600ms; }
+[lb-row-leaving] { animation: depart 200ms forwards; }
+```
+
+A row stamped again plays its animation again.  See
+[What happened to a row](./data-binding.md#what-happened-to-a-row).
+
+### How many rows show
+
+An element carrying `lb-query` and a row template carries
+`lb-query-row-count`, the number of live rows showing.  A row a filter hides
+is not counted.
+
+```css
+.roster-empty { display: none; }
+[lb-query-row-count="0"] .roster-empty { display: revert; }
+```
+
+See [Counting rows](./data-binding.md#counting-rows).
+
+### A request
+
+| Select                 | For                                                     |
+|------------------------|---------------------------------------------------------|
+| `[lb-request-pending]` | The element that committed, while its round trip is out; `aria-busy="true"` rides with it |
+| `[lb-request-error]`   | The element whose round trip failed, until it commits again |
+| `[lb-request-refused]` | The element whose request the handler refused, holding the message, empty when there is none |
+| `:invalid`             | A control a refusal named a column for                  |
+
+The hub ignores a commit on a pending element, so the stylesheet only has to
+show it:
+
+```css
+[lb-request-pending] { cursor: progress; opacity: 0.6; }
+[lb-request-error] { outline: 2px solid var(--error); }
+[lb-request-refused]:not([lb-request-refused=""])::after {
+  content: attr(lb-request-refused);
+}
+```
+
+See [Request state](./data-binding.md#request-state) and
+[Refusals](./data-binding.md#refusals).
+
+### A form pointed at a row
+
+A pointed form's `lb-key-value` says what it is doing:
+
+| Select                       | The form is        |
+|------------------------------|--------------------|
+| `form[lb-key-value]:not([lb-key-value=""])` | Editing a row |
+| `form[lb-key-value=""]`      | Entering a new row |
+| `form:not([lb-key-value])`   | Not in use         |
+
+```css
+form[lb-key-value=""] .save-existing,
+form:not([lb-key-value=""]) .save-new { display: none; }
+```
+
+See [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form).
+
+### The user's choices
+
+An order or a filter the user chose is a column of `lb-choices`, so the
+element showing it carries it as `lb-column-value`.  Style anything else by
+it with `:has()`:
+
+```css
+table:has([lb-column="accounts_order"][lb-column-value="-balance"])
+  th.balance::after { content: "▼"; }
+```
+
+See [Choices](./data-binding.md#choices).
+
+### Content shown by condition
+
+An element `lb-show` turns off is moved into a `<template>`, so no selector
+reaches it and nothing about it needs styling.  The `<template>` keeps its
+place, so `:nth-child()` counts it; prefer `:nth-child(… of …)` or a class
+over position.  See [Where an absent element is](./data-binding.md#where-an-absent-element-is).
+
+### The first load
+
+Write `hidden` on the chrome's `<body>`, and the hub removes it once the
+first page has landed.  See
+[Preventing the first-load blink](./chrome.md#preventing-the-first-load-blink).

package/skills/loadbare-app/references/custom-elements.md

@@ -290,7 +290,7 @@ Each direction has one mechanism for each kind of message:
 
 | Direction      | What                                       | How                         | Today |
 |----------------|--------------------------------------------|-----------------------------|-------|
-| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error` |
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
 | Hub to element | What the hub did                           | An optional `lb` method     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |

package/skills/loadbare-app/references/data-binding.md

@@ -2,7 +2,7 @@
 
 A page shows server data by naming queries and columns in its HTML, and asks
 the server to change that data by naming requests. The developer writes
-nine `lb-` attributes. The server declares every query a page may show and
+sixteen `lb-` attributes. The server declares every query a page may show and
 every request it may send, and refuses anything it has not declared.
 
 Everything is a query. A query is a name for rows, of kind `row` or `rows`,
@@ -48,6 +48,10 @@ each with its key, and permits the three requests on `roster`; see
 | `lb-show`        | Any element but `<template>`  | The column that decides whether it is present  |
 | `lb-order`       | An element with `lb-query`    | The choice holding the user's order; see [Order](#order) |
 | `lb-filter`      | An element with `lb-query`    | The columns a choice filters; see [Filters](#filters) |
+| `lb-group`       | A `<template>`                | Nothing: it marks a group template; see [Groups](#groups) |
+| `lb-count`       | Any element                   | Nothing: it shows a count of rows; see [Aggregates](#aggregates) |
+| `lb-sum`, `lb-avg`, `lb-min`, `lb-max` | Any element | The column aggregated; see [Aggregates](#aggregates) |
+| `lb-select`      | A checkbox in a row template  | Nothing: it selects its live row; see [Selecting rows](#selecting-rows) |
 | `lb-request`     | Any element                   | The request it sends when it commits           |
 | `lb-url-link`    | An `<a>`                      | A link between pages; see [chrome](./chrome.md#links) |
 | `lb-url-push`    | An element with `lb-request`  | A URL change that pushes a history entry       |
@@ -62,8 +66,14 @@ builder writes a stamp, and a stylesheet or a custom element reads it.
 | `lb-key-value`       | The key of a live row, or of a `row` landed on an element |
 | `lb-row-live`        | The element is a live row                          |
 | `lb-query-row-count` | The number of live rows an element shows           |
+| `lb-group-live`, `lb-group-column`, `lb-group-value` | A group, the column it breaks on, and its value; see [Groups](#groups) |
+| `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested` | What happened to a row; see [What happened to a row](#what-happened-to-a-row) |
+| `lb-row-leaving`, `lb-group-leaving` | A row or group on its way out      |
+| `lb-row-editing`     | The row a form is pointed at; see [Editing a row in one form](#editing-a-row-in-one-form) |
+| `lb-row-selected`    | A row whose `lb-select` is ticked                  |
 | `lb-request-pending` | The element's request is in flight                 |
 | `lb-request-error`   | The element's last request failed                  |
+| `lb-request-refused` | The handler refused it; see [Refusals](#refusals)  |
 | `lb-page`            | The stub of a page, on its `<template>`            |
 | `lb-page-title`      | The text of a page file's `<title>`                |
 
@@ -95,6 +105,10 @@ not `lb-row-live`, so a `row` shown inside another query, such as a total in
 a table's foot, is not one of that query's rows. Select live rows with
 `[lb-row-live]`, never with `[lb-key-value]`.
 
+A `row` query answering `null` found no row. The hub lands every column the
+element names as null and removes its `lb-key-value`; under a row template,
+the live row leaves.
+
 Write `lb-column` on each element that shows a column. The element reads
 from its nearest ancestor row: the live row it is in, or the element a
 `row` landed on. A nested `lb-query` begins a new query, and what is inside
@@ -139,12 +153,16 @@ from its element file, and renders `lb-column-value` itself; see
 A file input receives nothing, and the hub reports it to the console.
 
 The hub hands every value to the browser as the server sent it. What a
-number, a date or a null looks like is decided in the query.
+number, a date or a null looks like is decided in the query, or by a custom
+element that formats it, such as
+[`lb-number` and `lb-date`](./widgets.md#lb-number-and-lb-date). Send a
+column the user sorts or filters raw, and format it in the element.
 
 ### Checkboxes
 
 A checkbox is a control. It is checked when its column is anything but
-`false` or null, and it sends `"true"` or `"false"`:
+`false` or null, and it sends `"true"` or `"false"`
+([miswart](./miswarts.md#checkboxes-and-radio-groups-always-gather-a-value)):
 
 ```html
 <input type="checkbox" lb-column="active" lb-request="lb-row-update" />
@@ -169,8 +187,9 @@ when none is:
 
 In a row template, the hub stamps each radio button's `name` with the
 `name` written, or its column when none is, followed by `-` and the live
-row's key, so each live row holds a group of its own.  Rows not yet entered
-share the empty key, and so share one group.
+row's key, so each live row holds a group of its own
+([miswart](./miswarts.md#radio-button-names-in-a-row-template)).  Rows not yet
+entered share the empty key, and so share one group.
 
 A radio button in a query's row template answers to that query's row, as
 any element there does.  A choice among a query's rows is better made with
@@ -273,7 +292,8 @@ its rows the user may filter, separated by commas. The column of
 ```
 
 A row that does not pass every filter is `hidden`, and a ticked `lb-select`
-in it is cleared. A group whose rows are all hidden is hidden too. An empty
+in it is cleared. A group whose rows are all hidden is hidden too
+([miswart](./miswarts.md#rows-hidden-by-a-filter)). An empty
 choice filters nothing.
 
 A filter is one or more terms, each an operator followed by a value:
@@ -364,8 +384,9 @@ Every change to a list is one a stylesheet can see:
 | `lb-row-leaving`   | A row on its way out                                   |
 | `lb-group-leaving` | A group on its way out                                 |
 
-A row that leaves loses `lb-row-live`, takes `inert`, and is removed once
-its animations finish, at once when there are none. `lb-row-requested` is
+A row that leaves loses `lb-row-live`, takes `inert`
+([miswart](./miswarts.md#leaving-rows-are-inert)), and is removed once its
+animations finish, at once when there are none. `lb-row-requested` is
 cleared at every landing; the others when the hub next touches the row.
 
 A row is moved when its values changed and the rows whose values did not
@@ -920,7 +941,8 @@ The hub stamps the element that committed:
 
 `lb-request-error` covers a non-2xx response, a network failure and a
 timeout alike. The hub aborts a round trip after ten seconds, and sets
-`aria-busy="true"` for as long as `lb-request-pending` is present.
+`aria-busy="true"` for as long as `lb-request-pending` is present
+([miswart](./miswarts.md#busy-elements-carry-aria-busy)).
 
 The hub ignores a commit on an element carrying `lb-request-pending`, so a
 pending button is already disabled and a stylesheet only shows it:
@@ -1034,8 +1056,16 @@ The developer writes `lb-` attributes in markup, and script never assigns
 them. The builder checks the markup of the chrome and of every page, after
 expansion, and refuses to build:
 
-- an `lb-` attribute that is not one of the nine the developer writes
+- an `lb-` attribute that is not one of the sixteen the developer writes
 - `lb-request` naming an `lb-` request other than the three Loadbare provides
+- `lb-query` naming a query the page does not declare; every page and the
+  chrome may name `lb-url` and `lb-choices`, and the chrome names no other
+- `lb-request` naming a request the page does not declare under `handlers`;
+  the chrome sends none
+- one of the three requests for a query whose `crud` entry does not declare
+  it, or any but `lb-row-update` for `lb-url` or `lb-choices`; the query is
+  a form's own when the form carries `lb-query`, and otherwise the nearest
+  `lb-query` around the element
 - `lb-url-link` on anything but an `<a>`
 - `lb-url-push` on an element without `lb-request`
 - `lb-url-unknown` on anything but a `<dialog>`, or outside `<lb-hub>`
@@ -1048,3 +1078,7 @@ expansion, and refuses to build:
   template, or beside `lb-column` or `lb-request`
 - a `command` beginning `--lb-` that is not one of the three commands
 - one of the three commands with no `commandfor`
+
+To know what each page declares, the builder loads its `.queries.ts` and
+`.requests.ts` modules, so their import-time code runs during the build, as
+it does when the server starts.

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.