@loadbare/app 0.19.0 → 0.19.1

package/docs/reference/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/docs/reference/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/docs/reference/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.
@@ -230,13 +243,20 @@ export const requests: Requests = {
 ```
 
 Declare every request the page allows. The builder refuses markup naming a
-request the page does not declare, and the server refuses one that arrives
-anyway; see [The markup checks](./data-binding.md#the-markup-checks).
+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   |
 |-----------------|-------------|------------------|
@@ -295,8 +315,9 @@ export const requests: Requests = {
 ```
 
 Declare every request the query permits. The builder refuses markup sending
-a request a query does not declare, and the server refuses one that arrives
-anyway. A query with no `crud` entry permits none.
+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
@@ -374,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.
@@ -440,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/docs/reference/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.

package/docs/tutorials/040-displaying-data.md

@@ -130,7 +130,7 @@ requests to the correct page code.
 import express from "express";
 import { readFileSync } from "node:fs";
 import { hubRoutes } from "@loadbare/app/express";
-import { hub } from "./dist/pages";
+import { hub } from "./dist/pages.ts";
 import { openDb } from "./src/database";
 
 const app = express();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "type": "module",
   "files": [
     "dist",

package/skills/loadbare-app/SKILL.md

@@ -278,8 +278,8 @@ fetched to be edited is another page, with that row as its master.
 Each works on a `row` query as well as a `rows` query, since the element a
 `row` lands on carries its key.  Every other request name is a declared
 request, under `handlers`.  The build refuses markup naming a query or
-request the page does not declare, and the server refuses one that arrives
-anyway.
+request the page does not declare.  One that arrives anyway, from a script,
+is warned about on the server console and answered with nothing.
 
 **An empty key is a row not yet entered.**  A `row` query answering with an
 empty key, or a form `--lb-new` pointed, carries `lb-key-value=""`.  The hub
@@ -392,10 +392,13 @@ lb-query="lb-url">` in the chrome for it.
 whole data channel.
 
 **The developer writes `lb-*` attributes in markup, and script never
-assigns them.**  The builder refuses any `lb-` attribute other than
-`lb-query`, `lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-request`,
-`lb-url-link`, `lb-url-push` and `lb-url-unknown`.  Everything else with the
-prefix is a stamp the hub or the builder writes.
+assigns them.**  The builder refuses any `lb-` attribute other than the
+sixteen in [Attributes](references/names.md#attributes): `lb-query`,
+`lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-group`, `lb-count`,
+`lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-select`, `lb-request`,
+`lb-url-link`, `lb-url-push` and `lb-url-unknown`.  `lb-exp-slot` and
+`lb-exp-template` are expansion's, and never reach the page.  Everything
+else with the prefix is a stamp the hub or the builder writes.
 
 **`lb-` belongs to Loadbare.**  The application should never name anything
 with the `lb-` prefix anywhere: no attribute, query, column, request, custom
@@ -500,7 +503,6 @@ with the package, so no network is needed.
 - [`references/css.md`](references/css.md) — how stylesheets are ordered.
 - [`references/widgets.md`](references/widgets.md) — the basic widget
   library.
-- [`references/TECHREF-1.0.md`](references/TECHREF-1.0.md) — the reserved
-  names, what a URL names and
-  [query parms](references/TECHREF-1.0.md#query-parms).  Read it before designing around something the other
-  references do not mention.
+- [`references/names.md`](references/names.md) — every name Loadbare
+  owns, the constants, and the section defining each.  Check a name here
+  before designing around something the other references do not mention.

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

@@ -44,11 +44,16 @@ The builder classifies by name, not location.
 | `*.queries.ts`             | A page's queries, matched by base name            |
 | `imports.ts`               | The packages this app takes widgets from          |
 | `*.css`                    | A stylesheet — see [CSS](./css.md)                |
-| Any other `.html`          | A widget definition, named for the tag it defines |
+| `<tag-name>.html`          | A widget definition, named for the tag it defines |
 | `<tag>.browser.ts`         | A widget script, named for the tag it registers   |
 
 Give the application exactly one `chrome.html` and at most one `imports.ts`.
-Give every `.requests.ts` and `.queries.ts` a `.page.html` of the same base name.
+Give every `.requests.ts` and `.queries.ts` a `.page.html` of the same base name;
+one with no page is a build error.
+
+A widget definition is exactly `<kebab-case-name>.html`. Any other `.html`
+file is an error when it looks like a definition with capitals in its name,
+and is skipped otherwise.
 
 Name a widget script `<tag>.browser.ts`, not `<tag>.ts`. Only a file whose
 name carries `.browser` is bundled for the browser; every other module under
@@ -141,6 +146,10 @@ 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.
 
+It also writes `client-entry.ts`, the generated entry `client.js` is bundled
+from, and leaves it there. Nothing reads it after the bundle, and an
+application neither writes nor imports it.
+
 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`
 from `pages.ts` — see [The Express Server](./server.md) for the rest of the

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

@@ -103,6 +103,12 @@ server's row lands, so a chrome shows where the page is with no code:
 | `lb-page-unknown` | `true` when no page's stub matches the path             |
 | Any other name    | The query parm of that name, or empty when it is absent |
 
+The path names a page, never a resource: `/accounts/42` is not a way to
+reach account 42, and an application designs no endpoints. The query string
+describes what that page has on screen, `/accounts?acct=23`, and never
+commands. The server remembers nothing about the view, so a URL reloads,
+bookmarks and mails as the same view.
+
 A path names a page by its stub: `/members` shows `members.page.html`, and
 `/` shows `index.page.html`. A page's title is the text of the `<title>` its
 page file carries; see [page files](./page-files.md#the-page-title). The hub
@@ -139,11 +145,17 @@ Write `lb-url-link` on an `<a>` to move between pages:
 </nav>
 ```
 
-On a plain primary click, the hub pushes a history entry for the `href`,
-path and query string both, and shows the page it names. A click with a
-modifier key or another button, and a link without `lb-url-link`, behave as
-the browser has them behave. Back and Forward show the page at the URL they
-arrive at.
+On a plain primary click, the first button with no modifier key and not
+already handled, the hub pushes a history entry for the `href`, path and
+query string both, and shows the page it names. Any other click, and a link
+without `lb-url-link`, behave as the browser has them behave, so leaving the
+application is the default and staying in it is the opt-in. The attribute
+takes no value. Back and Forward show the page at the URL they arrive at.
+
+Path space is flat: `/members` shows `members.page.html` wherever under
+`--src` it sits. The query string is kept, so
+`/transactions?date_begin=2026-09-01` opens the page narrowed to those
+dates.
 
 ### Query parms
 
@@ -170,11 +182,28 @@ pushes one instead when the element carrying `lb-request` also carries
 
 The hub answers the request itself, with no round trip, then reloads the
 page's queries at the new URL. The page stays in place, and rows that come
-back keep their place.
+back keep their place. A request that leaves the URL as it was does
+nothing. `lb-page-label` and `lb-page-unknown` are the hub's, and a request
+never sets them.
+
+A request that gives `lb-path` a new value enters that page, pushes a
+history entry, and the new URL carries only the query parms the request
+names.
 
 A control whose column the URL does not carry lands empty, so every control
 inside `lb-query="lb-url"` shows what the address bar says, after a reload
-and after Back alike.
+and after Back alike
+([miswart](./miswarts.md#lb-url-lands-every-parm-it-names)).
+
+Loadbare assigns no parm a meaning, and a column of `lb-url` whose name
+begins with `lb-` is never a query parm.
+
+A query parm is user input. A query still takes no argument from the
+browser, and a parm arrives the way the session cookie does, as part of the
+request the context is built from, but a user who types `?acct=99999`
+influences what a query returns. Validate it where the application reads
+it; a per-session database role means an id outside the caller's reach
+finds nothing.
 
 An order or a filter the hub applies to rows the page already holds is not
 a query parm. It is a [choice](./data-binding.md#choices), which holds until
@@ -198,8 +227,13 @@ show the path:
 ```
 
 When no page's stub matches the path, `lb-page-unknown` is `true`,
-`lb-page-label` is null, `<main>` keeps the page it had, and the hub calls
-`showModal()` on the dialog.
+`lb-page-label` is null, `<main>` keeps the page it had, the hub calls
+`showModal()` on the dialog, and reports the path to the console. A chrome
+with no dialog shows nothing. `lb-url` lands before the page is looked up,
+so the dialog shows the path by naming it like any other element.
+
+Every route gets the same document, so an unknown path is found out in the
+browser after a successful 200, and there is no server-delivered 404.
 
 `@loadbare/widgets` ships this dialog as `<lb-unknown-page>`, for a chrome
 that would rather write one tag; see

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

@@ -41,7 +41,6 @@ Serve it at `/app.css` and link it from the chrome:
 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
 

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

@@ -250,30 +250,8 @@ takes part in data binding in one of four ways: it is a control, it renders
 a value, it sends a request, or it holds rows.
 
 Import every Loadbare name from `@loadbare/app/constants`, and never write
-one as a string literal:
-
-| Constant               | Value                |
-|------------------------|----------------------|
-| `ATTR_QUERY`           | `lb-query`           |
-| `ATTR_COLUMN`          | `lb-column`          |
-| `ATTR_SHOW`            | `lb-show`            |
-| `ATTR_REQUEST`         | `lb-request`         |
-| `ATTR_COLUMN_VALUE`    | `lb-column-value`    |
-| `ATTR_KEY_VALUE`       | `lb-key-value`       |
-| `ATTR_ROW_LIVE`        | `lb-row-live`        |
-| `LIVE_ROW`             | `[lb-row-live]`      |
-| `ATTR_QUERY_ROW_COUNT` | `lb-query-row-count` |
-| `ATTR_REQUEST_PENDING` | `lb-request-pending` |
-| `ATTR_REQUEST_ERROR`   | `lb-request-error`   |
-| `REQUEST_ROW_INSERT`, `REQUEST_ROW_UPDATE`, `REQUEST_ROW_DELETE` | The requests Loadbare provides |
-| `LB_ROW_REQUESTS`      | All three, in one array |
-| `LB_EVENT_NAME`        | `lb-request`, the event every request travels as |
-| `LB_DONE_EVENT_NAME`   | `lb-request-done`, the event that says how it turned out |
-| `SHOW_NOT`             | `!`, written before a column in `lb-show` |
-| `URL_QUERY`            | `lb-url`             |
-| `CHOICES_QUERY`        | `lb-choices`         |
-| `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
-| `LB_RESERVED_PREFIX`   | `lb-`                |
+one as a string literal: `ATTR_COLUMN_VALUE` rather than `"lb-column-value"`.
+[Constants](./names.md#constants) lists them all.
 
 A custom element reads `lb-` attributes and never assigns one. The developer
 writes them in markup, and the hub and the builder write their stamps.