@loadbare/app 0.18.2 → 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.
@@ -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/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/roadmap.md

@@ -15,13 +15,6 @@ mechanism Release 1.0 already ships. Each is here because deciding it
 speculatively, before a real page forces the question, risks designing the
 wrong thing. Revisit when the described symptom actually shows up.
 
-### Staleness and concurrent writers
-
-Two tabs, or two users, updating the same rows at once. A solo developer
-testing in one browser will not produce this by accident, and retrofitting a
-version or conflict check onto every row after the fact touches every widget
-that writes.
-
 ### A query that pages or limits its rows
 
 The user's order and filters apply to the rows the browser holds. A query
@@ -49,6 +42,31 @@ end up living in the widget while the server remains authoritative for the
 same field. Not yet designed — revisit the first time an application needs
 inline validation.
 
+### Compound foreign keys
+
+A picker is the UI for a foreign key.  `<select lb-query="statuses"
+lb-column="status">` says the row's `status` references a row of
+`statuses`, and offers every one of them.  For a single-column foreign key
+that is exactly right, which is why a query in a row template answers the
+same rows in every live row.
+
+A compound foreign key cannot be expressed.  When `(type, status)`
+references `allowed_statuses(type, status)`, the choices for `status`
+depend on the row's own `type`, and every row is offered every status.
+The database knows the constraint, and the UI cannot say it, so a user is
+offered choices the server will refuse.
+
+A likely direction keeps one query and one answer: the lookup answers every
+allowed pair as ordinary rows, the picker names the columns of its row that
+restrict it, and the hub shows each picker only the rows that match, as it
+already filters the rows it holds.  Two questions come with it:
+
+- Whether the restricting value is the one that landed or the control's
+  current value, so the choices follow an edit before it is saved.
+- What becomes of a chosen value the restriction no longer allows.
+
+Revisit when an application needs a choice restricted by its row.
+
 ## Release 1.1 candidates
 
 Net-new scope, not gaps in 1.0. Release 1.1 will optimize for operational
@@ -128,9 +146,10 @@ breaks nothing.
 
 ### Queries stated by the chrome
 
-A custom element in the chrome naming a query forces every page to declare
-that query, since the page load covers one page's set.  `lb-url` shows the
-pattern from the framework side, and an application has no equivalent.
+The chrome belongs to no page, so the builder refuses an application query
+named there, and a custom element in the chrome cannot show application
+data.  `lb-url` and `lb-choices` show the pattern from the framework side,
+and an application has no equivalent.
 
 A chrome-level query set on `createHub` would close this, and it is additive.
 It takes its place in the [options on `createHub`](#options-on-createhub).
@@ -159,39 +178,6 @@ A query parm write replaces the history entry, and `lb-url-push` pushes
 one.  Which of the two a user wants may be the user's to say, rather
 than the page's.
 
-### Build-time checking of `lb-request` against the declared requests
-
-Release 1.0 resolves every `lb-request` value at request time. A value naming
-no entry under `handlers`, or one of the requests Loadbare provides for a
-query with no entry under `crud`, is found on the first commit: a server
-console warning and an empty answer, described in
-[Page files](./reference/page-files.md). A typo builds cleanly.
-
-The builder already expands each page and walks the finished document in
-`walkMarkup`, tracking the enclosing `lb-query`, so collecting every request
-name together with the query it is issued for needs no new machinery. What
-it lacks is the other half of the comparison: it knows the path of a
-`.requests.ts` file and never reads its contents.
-
-Two routes to the declared names, and the choice is the decision:
-
-- **Load the built module.** Bundle the generated `pages.ts`, import it, and
-  read the keys off the finished objects. Exact, and indifferent to how the
-  object was written. The build then executes application import-time code,
-  and a builder that only reads files stops being that.
-- **Parse the source.** Read the keys statically with the TypeScript compiler
-  API. No application code runs, at the price of a real dependency and of
-  guessing wrong on anything not written as a plain object literal.
-
-Two smaller calls come with either route. The chrome belongs to no page, so
-a request there can only be required of every page or forbidden. A page with
-no requests file makes any request on it an error. The check is sound
-because the developer writes `lb-*` attributes in markup and script never
-assigns them.
-
-The same machinery would then also let `lb-query` names be checked against
-the declared queries.
-
 ### A language server
 
 ...for Loadbare HTML.
@@ -203,6 +189,23 @@ expansion allows a strings file.  We could either preserve the fully
 static build-time system and create multiple versions of `app.html`, or we
 could add label hydration to the page navigation stage.
 
+### Version checks on update and delete
+
+The last write to a row wins, at the grain of the columns each request
+carries, and a write whose outcome matters states its precondition in its
+own SQL; see [crud](./reference/page-files.md#crud).  A plain edit has no
+such precondition: only the value the user saw, or a version standing for
+it, tells that the row changed in between, and the server remembers
+nothing.
+
+A query would declare its version column.  The hub keeps every query's
+last answer, patches included, so it would send the version it holds with
+each update and delete for that query, and the handler would put it in its
+`WHERE`.  No widget changes, and a control committing alone takes part.
+
+Revisit when an application needs a write refused because the row changed
+since the user saw it.
+
 ## Decided against
 
 Settled questions, kept here so they are not reopened.  Each names what was
@@ -222,3 +225,12 @@ attribute value, with no escape for either.
 
 Text has a workaround: `<div>Hello, <span>{{world}}</span></div>` places the
 placeholder in a text node of its own.  Attribute values have none.
+
+### Serving the static files
+
+A router beside `hubRoutes` that serves `client.js`, `app.css` and
+`app.html` would save an application three routes.  It would also decide
+for every application how those files are read, cached and placed among
+its own routes, and whether a path naming no page answers `app.html`.
+Loadbare/app ships no server, and serving the build's output is the
+application's choice, as the rest of its server is.