@loadbare/app 0.21.0 → 0.23.0

package/docs/comparison.md

@@ -421,7 +421,8 @@ directory named by `loadbare.widgets` in its `package.json`, or the whole
 package when that key is absent.  Only tags used in the chrome or a page are
 bundled.  `@loadbare/widgets` ships `lb-input`, `lb-select`, `lb-options`,
 `lb-picker`, `lb-table`, `lb-confirm`, `lb-form`, `lb-insert-dialog`,
-`lb-master`, `lb-checkbox`, `lb-number`, `lb-date` and `lb-unknown-page`.
+`lb-master`, `lb-checkbox`, `lb-number`, `lb-date`, `lb-tel`, `lb-mailto`
+and `lb-unknown-page`.
 
 ### Using web components and other libraries
 
@@ -988,7 +989,7 @@ cross-reference.
 | Owned                                | Count | Names                                                                                                                                                                                                                                                                                                                                                                       |
 | ------------------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `lb-*` attributes a developer writes | 17    | `lb-query`, `lb-column`, `lb-show`, `lb-group`, `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-order`, `lb-filter`, `lb-request`, `lb-select`, `lb-url-link`, `lb-url-parm`, `lb-url-push`, `lb-url-unknown`                                                                                                                                                                     |
-| `lb-*` stamps                        | 23    | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-query-unsorted-count`, `lb-query-order`, `lb-group-live`, `lb-group-column`, `lb-group-value`, `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested`, `lb-row-unsorted`, `lb-row-leaving`, `lb-group-leaving`, `lb-row-editing`, `lb-row-selected`, `lb-request-pending`, `lb-request-error`, `lb-request-refused`, `lb-page`, `lb-page-title` |
+| `lb-*` stamps                        | 28    | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-query-unsorted-count`, `lb-query-order`, `lb-group-live`, `lb-group-column`, `lb-group-value`, `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested`, `lb-row-unsorted`, `lb-row-leaving`, `lb-group-leaving`, `lb-row-editing`, `lb-row-selected`, `lb-request-pending`, `lb-request-error`, `lb-request-refused`, `lb-page`, `lb-page-title`, and on `<lb-hub>` `lb-load-state`, `lb-server-state`, `lb-error`, `lb-pending`, `lb-as-of` |
 | `lb-*` build-time attributes         | 2     | `lb-exp-slot`, `lb-exp-template`                                                                                                                                                                                                                                                                                                                                            |
 | Requests Loadbare provides           | 3     | `lb-row-insert`, `lb-row-update`, `lb-row-delete`                                                                                                                                                                                                                                                                                                                           |
 | Commands for `commandfor`            | 4     | `--lb-edit`, `--lb-new`, `--lb-release`, `--lb-sort`                                                                                                                                                                                                                                                                                                                                   |
@@ -996,7 +997,7 @@ cross-reference.
 | Attribute namespace for expansion    | 1     | `exp-*`                                                                                                                                                                                                                                                                                                                                                                     |
 | Reserved tags                        | 1     | `<lb-hub>`                                                                                                                                                                                                                                                                                                                                                                  |
 | Reserved events                      | 2     | `lb-request`, `lb-request-done`                                                                                                                                                                                                                                                                                                                                             |
-| Queries the hub serves               | 2     | `lb-url`, with columns `lb-path`, `lb-page-label`, `lb-page-unknown`; `lb-choices`, keyed by `lb-path`                                                                                                                                                                                                                                                                      |
+| Queries the hub serves               | 3     | `lb-url`, with columns `lb-path`, `lb-page-label`, `lb-page-unknown`; `lb-choices`, keyed by `lb-path`; `lb-hub`, with columns `lb-load-state`, `lb-server-state`, `lb-error`, `lb-pending`, `lb-as-of` |
 | Builder flags                        | 4     | `--src`, `--out`, `--watch`, `--minify`                                                                                                                                                                                                                                                                                                                                     |
 | Reserved file names and patterns     | 8     | `chrome.html`, `imports.ts`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `<tag>.html`, `<tag>.browser.ts`, `*.css`                                                                                                                                                                                                                                                      |
 | Reserved `package.json` keys         | 1     | `loadbare.widgets`                                                                                                                                                                                                                                                                                                                                                          |

package/docs/miswarts.md

@@ -60,8 +60,9 @@ group.
 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.
+**Why it terminates.**  It applies only to these two controls.  A
+checkbox lands `"false"` and `""` as unchecked, so it lands what it
+gathered.
 
 ## Rows hidden by a filter
 

package/docs/reference/builder.md

@@ -16,19 +16,27 @@ loadbare-app-build [--src src] [--out dist] [--watch] [--minify]
 | `--watch`  | Build once, then again on every change under `--src` |
 | `--minify` | Minify `client.js` and `app.css`                     |
 
-Run it from the application's own `package.json`:
+During development, [the dev server](./dev-server.md) runs the build in
+watch mode, and restarts the server when it needs to.  To run the builder and
+the server side by side without it, from the application's own
+`package.json`:
 
 ```json
 {
   "scripts": {
-    "dev": "loadbare-app-build --watch & tsx server.ts"
+    "dev": "loadbare-app-build --watch & trap 'kill $! 2>/dev/null' EXIT INT TERM; tsx server.ts"
   }
 }
 ```
 
+The trap stops the watcher when the server exits.  Without it, a
+backgrounded watcher ignores Ctrl-C under `sh` and outlives the server.
+
 `--watch` watches every `.html`, `.ts`, and `.css` file under `--src`, and
-reports a failed build to the console without stopping. It runs no dev server
-and reloads no browser.
+reports a failed build to the console without stopping. It runs no server
+and reloads no browser. A program that builds or watches as part of its own
+work imports `buildApp` and `watchApp` from `@loadbare/app/build` instead;
+see [Assembling your own](./dev-server.md#assembling-your-own).
 
 `--minify` leaves `app.html` alone.
 

package/docs/reference/chrome.md

@@ -277,7 +277,58 @@ 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
-[The Basic Widget Library](./widgets.md#lb-unknown-page).
+[The Basic Widget Library](./widgets.md).
+
+## The hub's state
+
+The hub serves a third query of its own, `lb-hub`: one row, keyed by
+`lb-path`, saying whether the page's data arrived and whether the server
+answers. A page whose load failed shows its markup with nothing landed on
+it, and without this row nothing on the page can tell a list that is empty
+from a server that is down.
+
+| Column            | Holds                                                                  |
+|-------------------|------------------------------------------------------------------------|
+| `lb-load-state`   | `loading`, `loaded` or `failed`: the page load for the URL showing     |
+| `lb-server-state` | `reachable`, `failing` or `unreachable`: how the latest round trip went |
+| `lb-error`        | Empty, or why the latest round trip failed                             |
+| `lb-pending`      | How many round trips are in flight, page loads and requests together   |
+| `lb-as-of`        | When rows last came from the server, as an ISO timestamp               |
+
+- `lb-load-state` is `loading` while the page load is in flight, `loaded`
+  once the server answered it, and `failed` when it did not. A request whose
+  answer moves the URL and carries the page's queries loads the page too. A
+  load overtaken by a newer one says nothing, and a request that fails
+  later leaves the page `loaded`, since what it shows did arrive.
+- `lb-server-state` is `reachable` when the server answered, a refusal
+  included; `failing` when it answered with an HTTP error status; and
+  `unreachable` when no answer came, because the network failed or the
+  ten-second deadline passed. It is empty until the first round trip
+  returns.
+- `lb-error` is `network`, `timeout`, or the status the server answered
+  with, such as `500`. The next answer empties it.
+- `lb-as-of` is unchanged by a refusal, which brings no rows.
+
+The hub also stamps each column on `<lb-hub>` itself, as the attribute of
+the same name, and leaves off one that is empty. A stylesheet reaches the
+whole document that way, and the markup names the query only to show its
+text:
+
+```css
+.load-failed { display: none; }
+lb-hub[lb-load-state="failed"] .load-failed { display: block; }
+lb-hub[lb-load-state="failed"] main { opacity: 0.4; }
+lb-hub:not([lb-pending="0"]) .banner { cursor: progress; }
+```
+
+```html
+<p class="load-failed" lb-query="lb-hub">
+  This page did not load: the server is <span lb-column="lb-server-state"></span>
+  (<span lb-column="lb-error"></span>).
+</p>
+```
+
+Nothing writes `lb-hub` but the hub. The builder refuses a request for it.
 
 ## Preventing the first-load blink
 

package/docs/reference/data-binding.md

@@ -119,9 +119,9 @@ from its nearest ancestor row: the live row it is in, or the element a
 it reads from that query's rows.
 
 An element with `lb-query` and `lb-column` both shows the rows of its own
-query and holds the column of the row around it. This
-[`<lb-options>`](./widgets.md#lb-options) lists the accounts and holds its
-row's `account`:
+query and holds the column of the row around it. This `<lb-options>`, from
+[`@loadbare/widgets`](./widgets.md), lists the accounts and holds its row's
+`account`:
 
 ```html
 <lb-options lb-query="accounts" lb-column="account">
@@ -167,24 +167,27 @@ option for the value shows no selection.
 
 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, or by a custom
-element that formats it, such as
-[`lb-number` and `lb-date`](./widgets.md#lb-number-and-lb-date). Send a
+element that formats it, such as `lb-number` and `lb-date` in
+[`@loadbare/widgets`](./widgets.md). 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"`
-([miswart](../miswarts.md#checkboxes-and-radio-groups-always-gather-a-value)):
+A checkbox is a control. It sends `"true"` or `"false"`
+([miswart](../miswarts.md#checkboxes-and-radio-groups-always-gather-a-value)),
+and it is checked when its column is anything but `false`, null, `"false"`
+or `""`:
 
 ```html
 <input type="checkbox" lb-column="active" lb-request="lb-row-update" />
 ```
 
-Checked follows the rule `lb-show` follows, so a query spells a flag as a
-boolean, and the string `"false"` is checked. Unchecked sends `"false"`
-rather than nothing, so a flag can be set back. The checkbox's `value`
-attribute means nothing to the hub.
+A checkbox lands what it sends, so it shows the same state after a round
+trip through a query whose values are strings, such as `lb-url` or
+`lb-choices`. A query parm the URL does not carry lands as `""`, so the
+checkbox is unchecked. Unchecked sends `"false"` rather than nothing, so a
+flag can be set back. The checkbox's `value` attribute means nothing to the
+hub.
 
 ### Radio buttons
 
@@ -464,8 +467,9 @@ are heading rows beside their rows:
 Content after the nested template lands after the group's rows, which is
 where a group's footer goes.
 
-A heading is filled from its group's first row, so it may show a column
-other than the one the group breaks on. A row an edit from inside the list
+A heading is filled from its group's first row as an element in a row is,
+`href`s from `lb-url-parm` included, so it may show a column other than the
+one the group breaks on. A row an edit from inside the list
 moved to another group stays under its old heading, and the heading shows
 the row as it stood, until the rows are placed again. The hub stamps each top-level
 element of a group with `lb-group-live`, `lb-group-column` and
@@ -944,7 +948,8 @@ nothing is not sent.
 
 For a query the hub serves, `lb-url` or `lb-choices`, the hub answers
 `lb-row-update` itself, with no round trip; see
-[Query parms](./chrome.md#query-parms) and [Choices](#choices).
+[Query parms](./chrome.md#query-parms) and [Choices](#choices). The third,
+`lb-hub`, takes no request.
 
 A key comes from a live row, or from an element a `row` landed on, so all
 three work against either kind:
@@ -961,8 +966,11 @@ update from a form or a live row sends every control it gathers. The
 application writes one `rowUpdate` for both, setting the columns `values`
 names, as an SQL UPDATE does.
 
-After a successful insert gathered from a form, the hub resets the form. A
-failed insert leaves the entry for the user to correct.
+After a successful insert gathered from a form, the hub resets the form,
+unless the answer landed the new row on it. A form over a `row` query not
+yet entered, whose insert answers `url()` to the new key, then shows the row
+just saved, on record. A failed insert leaves the entry for the user to
+correct.
 
 Leave `lb-request` off a control inside a form or a live row that sends its
 own update, or the same edit is written twice.
@@ -1254,7 +1262,9 @@ A reset of any form, whether the hub's, a reset button's or a script's,
 returns its controls to their defaults, and the hub removes
 `lb-column-value` from each of them. A cancelled reset keeps both.
 
-A page load that fails lands nothing and is reported to the console. A load
+A page load that fails lands nothing and is reported to the console, and
+the query `lb-hub` says so; see [The hub's state](./chrome.md#the-hubs-state).
+A load
 started by a request for `lb-url` stamps the element that sent it, as any
 request stamps its element.
 

package/docs/reference/dev-server.md

@@ -0,0 +1,178 @@
+# The Dev Server
+
+`@loadbare/app/dev` runs an application while it is being written. After
+any change, to markup, CSS, a query, a handler, a server module or the
+server's entry file, the developer refreshes the browser. Nothing is ever
+restarted by hand, a refresh never meets a refused connection, and it never
+loads a half-written `client.js`.
+
+```ts
+// dev.ts
+import { devServer } from "@loadbare/app/dev";
+
+await devServer({ server: "server.ts" });
+```
+
+```json
+{
+  "scripts": {
+    "dev": "node dev.ts"
+  }
+}
+```
+
+## Why a refresh is enough
+
+- **The static output is read per request.** The server reads
+  `dist/app.html`, and sends `client.js` and `app.css` from disk, so markup,
+  CSS and browser code need only a rebuild.
+- **Only server modules need a restart.** `dist/pages.ts` and everything it
+  imports are loaded once, and Node cannot unload a module. A new process is
+  the honest answer, and a Loadbare server starts in well under a second.
+- **The URL holds the page's state.** A refresh returns the user to the
+  same page, row and query parms, so swapping code into a live page buys
+  almost nothing.
+
+## What it does
+
+```
+browser --> devServer :port --> the application's server :appPort (a child)
+                |
+                +-- the build, watching src (in process)
+```
+
+1. Builds `dist/`, then rebuilds whenever an `.html`, `.ts` or `.css` file
+   under `src` changes.  A burst of changes, such as an editor's save or a
+   branch switch, is one build.
+2. Runs the application's server as a child process, exactly as it runs in
+   production, on `appPort`.
+3. Restarts that server after a build when a server-side file changed: any
+   `.ts` under `src` other than a `.browser.ts`, or a change to the page
+   registry `dist/pages.ts`, which a page gained or lost changes. It also
+   restarts it when the server's entry file changes. CSS, HTML and browser
+   code never restart it.
+4. Holds every request while a build runs or the server restarts, and sends
+   it on when both are done.
+5. Keeps serving the last good build when a build fails, and says why in
+   the console.
+6. Answers 502, "The app server is down; see the dev console.", when the
+   server has exited, for example on a throw at import, and starts it again
+   on the next save.
+7. Says plainly when its port is in use, and exits.
+8. Passes everything else through, method, path, headers and body,
+   `POST /lb/*` included.
+9. Stops the server however the dev server ends: Ctrl-C, a kill, or a
+   crash.
+
+The application's server reads its port from the environment, as the
+[server recipe](./server.md) does:
+
+```ts
+app.listen(Number(process.env.PORT ?? 8787));
+```
+
+## Options
+
+Every option but `server` has a default.
+
+| Option    | Default                          | Meaning                                                |
+|-----------|----------------------------------|--------------------------------------------------------|
+| `server`  | (required)                       | The application's server entry file                    |
+| `port`    | `PORT` from the environment, or `8787` | The port the browser uses                        |
+| `host`    | `127.0.0.1`                      | The host that port listens on                          |
+| `appPort` | `port + 10000`                   | Where the application's server listens                 |
+| `portEnv` | `PORT`                           | The variable the application's server reads its port from |
+| `node`    | `["--env-file-if-exists=.env"]`  | Node's arguments before the entry file                 |
+| `src`     | `src`                            | The builder's source tree                              |
+| `out`     | `dist`                           | The builder's output                                   |
+| `log`     | the console                      | Where progress goes, one line at a time                |
+
+A server written in TypeScript runs under Node's own type stripping, Node
+22.18 and later. For a runner such as tsx, name it in `node`:
+`node: ["--import", "tsx"]`.
+
+`devServer` resolves once the first build is done and the server accepts
+connections, with `{ port, close() }`.
+
+## Assembling your own
+
+`devServer` is a short composition of parts that are exported on their own.
+An application that wants something else, such as other files that restart
+the server, a second server, or a reload pushed to the browser, builds its
+own from them.
+
+| Part         | From                   | Does                                                         |
+|--------------|------------------------|--------------------------------------------------------------|
+| `watchApp`   | `@loadbare/app/build`  | Builds, rebuilds on a change, and reports each build         |
+| `buildApp`   | `@loadbare/app/build`  | Builds once                                                  |
+| `watchTree`  | `@loadbare/app/build`  | Reports each changed file under a directory                  |
+| `appServer`  | `@loadbare/app/dev`    | The application's server as a child process, restarted on demand |
+| `gate`       | `@loadbare/app/dev`    | Holds requests while any reason to hold them stands          |
+| `devProxy`   | `@loadbare/app/dev`    | The browser's port, passing requests through a gate          |
+
+`watchApp({ src, out, minify, onStart, onBuilt })` builds at once, then
+again on each change. `onStart(changed)` is called as a build begins, with
+the files under `src` that changed, relative to it, and an empty list for
+the first. `onBuilt(outcome)` is called as it ends, with `{ ok: true,
+changed, built }` or `{ ok: false, changed, error }`; `built.files` lists
+what was written. Builds never overlap: changes during one are gathered into
+the next. It returns `{ ready, close() }`, where `ready` resolves with the
+first build's outcome. Paths resolve against the working directory.
+
+`buildApp({ src, out, minify })` builds once, and throws when the build
+fails. A build writes nothing until every output is ready, so a failed one
+leaves the last good build in place. `loadbare-app-build` is a thin command
+over these two.
+
+`watchTree(root, onFile)` calls `onFile(file)` for each file under `root`
+that is changed, added or removed, with its path relative to `root`. It
+watches each directory, including those made later, so a file saved by
+replacing it, as `sed -i` and many editors save, is reported on every save.
+Node's `fs.watch` with `recursive: true` loses such a file on Linux after
+its first save. It returns `{ close() }`. `watchApp` watches `src` with it.
+
+`appServer({ entry, port, portEnv, node, log })` returns `{ restart(),
+stop(), state }`. `restart()` stops the server if it runs, starts it, and
+resolves once it accepts connections, or has exited instead. `state` is
+`starting`, `running`, `down` for a server that exited on its own, or
+`stopped`. Once stopped, it never starts again. The child is killed when
+this process exits, however it exits.
+
+`gate()` returns `{ close(reason), open(reason), wait(), isOpen }`. Each
+`close` is matched by its own `open`, and `wait()` resolves once every
+close has been. A build and a restart can each hold requests without one
+ending the other's hold.
+
+`devProxy({ port, host, target, gate, isDown })` listens on `port` and
+passes every request to `target` once the gate is open, answering 502 while
+`isDown()` is true. It resolves with the listening server, and rejects with
+a plain message when the port is in use.
+
+A dev server that also restarts on a change to `config/`:
+
+```ts
+import { watchApp, watchTree } from "@loadbare/app/build";
+import { appServer, devProxy, gate } from "@loadbare/app/dev";
+
+const held = gate();
+const app = appServer({ entry: "server.ts", port: 18787 });
+const restart = async () => {
+  held.close("server");
+  await app.restart();
+  held.open("server");
+};
+
+const watcher = watchApp({
+  onStart: () => held.close("build"),
+  onBuilt: async (outcome) => {
+    console.log(outcome.ok ? outcome.built.summary : outcome.error.message);
+    if (outcome.changed.some((f) => f.endsWith(".ts"))) await restart();
+    held.open("build");
+  },
+});
+watchTree("config", () => void restart());
+
+await watcher.ready;
+await restart();
+await devProxy({ port: 8787, target: 18787, gate: held, isDown: () => app.state === "down" });
+```

package/docs/reference/names.md

@@ -103,6 +103,7 @@ assigns one.
 | `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-load-state`, `lb-server-state`, `lb-error`, `lb-pending`, `lb-as-of` on `<lb-hub>` | Hub | [The hub's state](./chrome.md#the-hubs-state) |
 | `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)                 |
@@ -110,12 +111,13 @@ assigns one.
 ## Reserved queries
 
 The hub serves these in the browser.  Every page and the chrome may name
-them, and a page declares neither.
+them, and a page declares none.
 
 | 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)  |
+| `lb-hub`     | `row` | `lb-path` | `lb-path`, `lb-load-state`, `lb-server-state`, `lb-error`, `lb-pending`, `lb-as-of` | [The hub's state](./chrome.md#the-hubs-state) |
 
 No query parm is reserved: a column of `lb-url` whose name begins with
 `lb-` is never a query parm.
@@ -175,6 +177,8 @@ accessor or field named `lb` and a capital.
 | -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
 | `@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/dev`        | `devServer`, `appServer`, `gate`, `devProxy`, `DOWN_MESSAGE`     | [The Dev Server](./dev-server.md)              |
+| `@loadbare/app/build`      | `buildApp`, `watchApp`                                           | [Assembling your own](./dev-server.md#assembling-your-own) |
 | `@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)              |
@@ -244,6 +248,15 @@ imports them rather than writing a string.
 | `URL_COLUMN_PATH`         | `lb-path`                               |
 | `URL_COLUMN_PAGE_LABEL`   | `lb-page-label`                         |
 | `URL_COLUMN_PAGE_UNKNOWN` | `lb-page-unknown`                       |
+| `HUB_QUERY`               | `lb-hub`                                |
+| `HUB_COLUMN_LOAD_STATE`   | `lb-load-state`                         |
+| `HUB_COLUMN_SERVER_STATE` | `lb-server-state`                       |
+| `HUB_COLUMN_ERROR`        | `lb-error`                              |
+| `HUB_COLUMN_PENDING`      | `lb-pending`                            |
+| `HUB_COLUMN_AS_OF`        | `lb-as-of`                              |
+| `HUB_LOAD_LOADING`, `HUB_LOAD_LOADED`, `HUB_LOAD_FAILED` | `loading`, `loaded`, `failed`           |
+| `HUB_SERVER_REACHABLE`, `HUB_SERVER_FAILING`, `HUB_SERVER_UNREACHABLE` | `reachable`, `failing`, `unreachable`   |
+| `HUB_ERROR_NETWORK`, `HUB_ERROR_TIMEOUT` | `network`, `timeout`                    |
 | `ATTR_URL_LINK`           | `lb-url-link`                           |
 | `ATTR_URL_PARM`           | `lb-url-parm`                           |
 | `ATTR_URL_PUSH`           | `lb-url-push`                           |

package/docs/reference/overview.md

@@ -19,6 +19,7 @@ serves, and the custom elements those pages are made of.
 | [`imports.ts`](./builder.md#widgets-from-packages)       | The packages this app takes widgets from  |
 | [`loadbare-app-build`](./builder.md#running-the-builder) | Configuring the build command             |
 | [CSS](./css.md)                                          | How the builder packages css              |
+| [The dev server](./dev-server.md)                        | Refresh after any change, never restart   |
 
 ## Application Pages
 

package/docs/reference/server.md

@@ -35,7 +35,7 @@ app.get(/.*/, (_req, res) =>
   res.type("html").send(readFileSync(path.join(DIST, "app.html"), "utf-8")),
 );
 
-app.listen(8787);
+app.listen(Number(process.env.PORT ?? 8787));
 ```
 
 ## What the server serves
@@ -96,16 +96,21 @@ The limit covers every page's requests.
 ## Running the server
 
 Run the server under a TypeScript-capable runner. The builder writes
-`dist/pages.ts`, which exports `hub`, as TypeScript:
+`dist/pages.ts`, which exports `hub`, as TypeScript. During development,
+[the dev server](./dev-server.md) runs it, and restarts it when a server
+module changes:
 
 ```json
 {
   "scripts": {
-    "dev": "loadbare-app-build --watch & tsx server.ts"
+    "dev": "node dev.ts"
   }
 }
 ```
 
+The server reads its port from `PORT`, which is how the dev server tells it
+where to listen.
+
 Node 22.18 and later also runs it with no runner at all, since Node strips
 TypeScript types itself. `dist/pages.ts` imports each `.requests.ts` and
 `.queries.ts` file by its full name, extension included, because Node looks