@loadbare/app 0.20.0 → 0.22.0

package/docs/tutorials/000-getting-started.md

@@ -57,7 +57,7 @@ Add a command to package.json that builds the app.
 ```json
 {
   "scripts": {
-    "dev": "loadbare-app-build --watch & node server.js"
+    "dev": "loadbare-app-build --watch & trap 'kill $! 2>/dev/null' EXIT INT TERM; node server.js"
   }
 }
 ```

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

@@ -159,7 +159,7 @@ runner:
 ```json
 {
   "scripts": {
-    "dev": "loadbare-app-build --watch & tsx server.js"
+    "dev": "loadbare-app-build --watch & trap 'kill $! 2>/dev/null' EXIT INT TERM; tsx server.js"
   }
 }
 ```

package/docs/tutorials/090-using-widget-libraries.md

@@ -90,7 +90,7 @@ publication — that's the same class shape
 [Committing a Control](./080-widget-requests.md) already wrote, packaged and
 given an import specifier instead of living in an application's `src/`.
 It doesn't cover `lb-table`'s footer destination or `lb-picker`'s
-expansion parameters, which are in
+expansion parameters, which each widget's own page covers; see
 [The Basic Widget Library](../reference/widgets.md).
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "files": [
     "dist",
@@ -22,7 +22,9 @@
     "./constants": "./dist/core/lb-constants.js",
     "./types": "./dist/core/lb-types.js",
     "./server": "./dist/server/lb-server.js",
-    "./express": "./dist/server/lb-express.js"
+    "./express": "./dist/server/lb-express.js",
+    "./build": "./dist/build/build.js",
+    "./dev": "./dist/dev/lb-dev.js"
   },
   "scripts": {
     "prepublishOnly": "npm run typecheck && npm run test && npm run build",

package/skills/loadbare-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loadbare-app
-description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; re-sorting a list with `--lb-sort`; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; whether the page loaded and the server answers as the hub's query `lb-hub`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; re-sorting a list with `--lb-sort`; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
 license: Apache-2.0
 metadata:
   package: "@loadbare/app"
@@ -48,7 +48,9 @@ carries, so their import-time code runs then; open a database in
 `contextFor`, not at import.  Then start the server: `createHub` refuses a page that declares a reserved name at startup,
 and the server console reports a query that answers with the wrong kind.
 Restart the server after adding or changing a `.queries.ts` or
-`.requests.ts` file.
+`.requests.ts` file, or run it under the dev server, `devServer` from
+`@loadbare/app/dev`, which rebuilds and restarts it after each change; see
+[`references/dev-server.md`](references/dev-server.md).
 
 ## The shape of an application
 
@@ -73,7 +75,8 @@ server.ts
 The chrome carries `<lb-hub>` inside `<body>`, an empty `<main>` inside the
 hub, and `<script src="/client.js" defer>`.  Everything a user touches sits
 inside `<lb-hub>`.  The chrome belongs to no page, so it names only the
-hub's queries, `lb-url` and `lb-choices`, and sends no declared request.
+hub's queries, `lb-url`, `lb-choices` and `lb-hub`, and sends no declared
+request.
 
 A page is an HTML fragment that lands in `<main>`:
 
@@ -191,8 +194,8 @@ row is filled from the nested query's last answer, whatever order they land
 in.
 
 **A `rows` query declares its order, and the hub places every row by it.**
-An edit sent from inside a list leaves that list's rows where they stand,
-stamped `lb-row-unsorted` where out of order, until the page loads, the
+An edit sent from inside a list, or from a form `--lb-edit` pointed at one
+of its rows, leaves that list's rows where they stand, stamped `lb-row-unsorted` where out of order, until the page loads, the
 user's order or filter changes, or a button with `commandfor` naming the
 list sends `command="--lb-sort"`, which places them with no round trip;
 show it by `[lb-query-unsorted-count]`.  Never refresh to make rows hold
@@ -217,6 +220,15 @@ text for contains.  A choice shows with no round trip, then the server's
 page changes.  A filter that decides which rows the server sends is a query
 parm.
 
+**A page that failed to load says so.**  The hub serves a third query,
+`lb-hub`, and stamps its columns on `<lb-hub>` too: `lb-load-state`
+(`loading`, `loaded`, `failed`), `lb-server-state` (`reachable`, `failing`,
+`unreachable`), `lb-error` (`network`, `timeout` or the HTTP status),
+`lb-pending` and `lb-as-of`.  Show a server that is down from the chrome's
+stylesheet, `lb-hub[lb-load-state="failed"] .load-failed`, rather than
+leaving an empty page; see
+[`references/chrome.md`](references/chrome.md#the-hubs-state).
+
 **Groups are templates.**  A `<template lb-group>` holds a heading and one
 nested `<template>`, the next level or the row template; the nth breaks on
 the order's nth term, to any depth.  Contents land before the nested
@@ -475,12 +487,10 @@ and a condition need none.  A custom element exists to be a control of its
 own, or to act on rows once they land through the hook the hub calls,
 `lbRowsLanded` (the `HubLifecycle` interface).
 
-Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
-`lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`, `lb-confirm`,
-`lb-form`, `lb-insert-dialog`, `lb-master`, `lb-checkbox`, `lb-number`,
-`lb-date`.  The first four are
-form-associated controls that carry `lb-column` and `lb-request`
-themselves.  Install the package and list it in `src/imports.ts`:
+Before writing one, check `@loadbare/widgets`, the basic widget set, which
+the loadbare-widgets skill documents.  Its controls are form-associated and
+carry `lb-column` and `lb-request` themselves.  Install the package and list
+it in `src/imports.ts`:
 
 ```ts
 export default ["@loadbare/widgets"];
@@ -510,9 +520,17 @@ with the package, so no network is needed.
   the request context.
 - [`references/builder.md`](references/builder.md) — the builder's options,
   what it reads, and where it looks.
+- [`references/dev-server.md`](references/dev-server.md) — `devServer` from
+  `@loadbare/app/dev`, and the parts to assemble another from.
 - [`references/css.md`](references/css.md) — how stylesheets are ordered.
 - [`references/widgets.md`](references/widgets.md) — the basic widget
-  library.
+  library as a package; each widget is in the loadbare-widgets skill.
 - [`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.
+
+## The other loadbare skills
+
+`npx loadbare-app skills install` puts this skill where a coding agent finds
+it.  `npx loadbare-widgets skills install` and `npx loadbare-db skills
+install` do the same for the loadbare-widgets and loadbare-db skills.

package/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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,8 +167,8 @@ 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
@@ -312,9 +312,12 @@ puts it somewhere else, so all rows landing again unchanged move nothing.
 A landing that answers a request sent from inside a list moves none of that
 list's rows. The request is from inside the list when the list is the
 nearest element carrying `lb-query` around the element that sent it: a
-control in a live row, or a ghost row. A form elsewhere on the page is not
-inside the list. A user who changes a value sees the value change, and the
-row stays where they were working:
+control in a live row, or a ghost row. A form that
+[`--lb-edit`](#editing-a-row-in-one-form) pointed at a live row finishes an
+edit begun in that row, so its request is from inside the row's list,
+wherever the form sits. Any other form elsewhere on the page is not inside
+the list. A user who changes a value sees the value change, and the row
+stays where they were working:
 
 | The answer                               | The row                                           |
 |------------------------------------------|---------------------------------------------------|
@@ -941,7 +944,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:
@@ -958,8 +962,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.
@@ -1033,6 +1040,12 @@ An `lb-show` in the form reads from the row it was pointed at. With no row,
 every column is null, so `lb-show="!id"` shows only while entering a new
 row.
 
+A request from a form Edit pointed is sent from inside the row's list, so
+the row stays where the user was working, even when the filter would now
+hide it or the order would move it; see
+[Rows the user is working in](#rows-the-user-is-working-in). A form New
+pointed is not inside any list, and its rows are placed by the order.
+
 A successful request from the form lets it go, as Cancel does: the form
 empties, its controls return to their defaults, and the stamps go. A failed
 one leaves the form as the user had it, to correct.
@@ -1245,7 +1258,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/skills/loadbare-app/references/dev-server.md

@@ -0,0 +1,171 @@
+# 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                                                  |
+| `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.
+
+`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 { watch } from "node:fs";
+import { watchApp } 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");
+  },
+});
+watch("config", { recursive: true }, () => void restart());
+
+await watcher.ready;
+await restart();
+await devProxy({ port: 8787, target: 18787, gate: held, isDown: () => app.state === "down" });
+```

package/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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