@loadbare/app 0.5.5 → 0.6.0

package/docs/TECHREF-1.0.md

@@ -0,0 +1,1000 @@
+# What 1.0 release means
+
+This is the complete technical reference to the upcoming Release 1.0.
+
+Method-of-work is to continually revise this document to what we want
+to be true, then revise the code, docs, and tests to ensure it is true.
+
+## Blockers
+
+We cannot declare 1.0 until we determine if these blockers can be
+added later w/o breaking changes.  If we are reasonably confident
+that they can be decided later w/o breaking changes, then we rename
+them to "Out of Scope".  Otherwise, they must be resolved before
+we declare 1.0.
+
+### Data types
+
+Loadbare/app enforces no data types on values between the database and the
+browser.  A uniform and useful approach is difficult to discern, and we do
+not want to pollute 1.0 with a potentially sub-optimal solution.  Until then
+a value is rendered by browser coercion when it lands on an HTML text
+element, or by whatever the widget does when it lands on a widget.
+
+We will then see if a useful solution emerges that Loadbare/app should
+handle.
+
+### Run-time state attributes
+
+The hub stamps `lb-row-count`, `lb-pending` and `lb-error` for a
+stylesheet to read.  Their consumer is CSS rather than code.
+
+- **Decide `data-` against `lb-`.** These are the only names the hub writes
+  outside its own namespace, which is either a deliberate signal that CSS
+  owns them or an inconsistency.
+- **Say what `lb-row-count` holds.** It is stamped and never explained.
+- **Decide whether an unarrived value needs a signal.** The roadmap proposes
+  deriving it from an absent `lb-value`.  Recommend confirming that and
+  adding nothing.
+
+### The widget protocol
+
+Loadbare/app owns every method name beginning with `lb` on a custom element.
+That decision is firm; what the set contains is not.
+
+- **Decide what the build does with an unknown `lb*` method.** An element
+  carrying a method beginning with `lb` that Loadbare/app does not define may
+  be an error, a warning, or ignored.
+- **Decide whether a widget may receive a whole row.** A cell lands one
+  element at a time and offers no escape hatch.  An optional `lbAcceptRow`
+  would sit beside `lbPlaceRow` and `lbRowsLanded`, and this is the most
+  likely first request from a widget author.
+- **Give a widget a way to fire its own request.** A custom widget must
+  reproduce the logic in the hub to fire its own event.  This is a bit of a
+  smell, but was done this way to start because we do not know yet the shape
+  of how the widget could re-use code from the hub.
+
+### Lists
+
+- **Decide what a nested list means.** A list whose rows each hold a list is
+  legal by the nesting rule, and produces strange results when the outer list
+  is updated.  Loadbare/app has no vocabulary for it.
+
+```html
+<div lb-list="departments">
+  <template lb-key="id"><section>
+    <h2 lb-cell="name"></h2>
+    <ul lb-list="members"><template lb-key="id"><li lb-cell="who"></li></template></ul>
+  </section></template>
+</div>
+```
+
+### The server API
+
+- **Give the chrome a way to state its own queries.** A widget in the chrome
+  bound to a query forces every page to declare that query, since the page
+  data run covers one page's set.  `lb-navigation` shows the pattern from the
+  framework side, and an application has no equivalent.  Recommend a
+  chrome-level query set on `createHub`.
+- **State that only `createHub` implements `Hub`.** Otherwise a sixth
+  operation breaks anyone who wrote the interface by hand.
+- **Decide the options-argument shape once.** Global hooks, transaction
+  wrapping, error handling and a CSRF token all want the same trailing
+  parameter on `createHub` and `hubRoutes`.  Build none of them, but pick
+  where they go.
+- **Land `staticRoutes`.** See NEXT.md.  It closes the last place where an
+  application hand-writes facts the builder owns.
+
+### The builder
+
+- **Adopt a configuration file and fold `imports.ts` into it.** It holds
+  `out`, `minify` and `imports`, and lives where `imports.ts` lives now, so a
+  repository with several applications gets one per application.  `--src`
+  stays a flag, since it is what locates the file.  State the precedence
+  between a flag and a key once.  Its key names join the permanent surface,
+  so this lands before 1.0 or not at all.
+- **Take a position on the URL space.** A page name is a filename basename,
+  so `/user/42` resolves to nothing and no page is addressable by row.
+  Deciding against path parameters is a legitimate answer.  Write whichever
+  one down.
+- **Decide CSS pairing.** Naming a stylesheet `<tag>.css` beside its
+  definition would let the builder ship only what survives expansion.
+  Recommend deferring the mechanism and reserving the configuration key, so
+  that it lands as an opt-in rather than as a silent drop.
+- **Land the remaining validations.** One `lb-hub`, one empty `<main>`, and
+  every `lb-` attribute known.  Recommend landing these now, because refusing
+  markup that used to build is the kind of change 1.0 gives up.
+- **Confirm the three output names.** `app.html`, `client.js` and `app.css`
+  are about to be fixed in `staticRoutes` as well as in the builder.
+
+### The internal surface
+
+None of this is surface.  It is listed here because trimming it is free
+today and breaking after 1.0.
+
+- **Drop `./build` from the exports map.** Nothing in the repository imports
+  it, and nothing outside the CLI should call `resolveElements` or
+  `clientEntrySource`.
+- **Audit what the hub does.** It appears to have routines that go beyond
+  what the `lb-*` attribute namespace specifies.
+- **Keep the rest as constants.** The endpoint, `index` and the timeout are
+  linkage between the builder and the hub rather than facts an application
+  varies.  Adding a knob for any of them buys a second shape of application
+  to reason about.
+- **Give the hub a configuration channel without using it.** `<lb-hub>` reads
+  no attributes at all, which is the free landing spot for the roadmap's
+  static-origin split and for a timeout an application eventually outgrows.
+  Reserve the idea, build nothing.
+
+## The build
+
+### Running the builder
+
+```
+loadbare-app-build [--src src] [--out dist] [--watch] [--minify]
+```
+
+`--src` names the tree the builder scans, and is defined under
+[What the builder scans](#what-the-builder-scans).
+
+`--out` names the directory the builder writes into, and defaults to `dist`.
+Every output path in this document is written relative to it, so an
+application that passes `--out` reads `dist/app.html` here as
+`<out>/app.html`.  See [Build outputs](#build-outputs).
+
+`--watch` builds once, then rebuilds on every change to an `.html`, `.ts` or
+`.css` file under `--src`.  A build that throws is reported and the watch
+continues.  There is no dev server and no browser reload.
+
+`--minify` minifies `client.js` and `app.css`.  It leaves `app.html` alone,
+which stays markup an application can read.
+
+The builder bundles `client.js` from a `client-entry.ts` it generates into
+`--out` and leaves there.  Nothing reads it after the bundle, and an
+application neither writes nor imports it.
+
+Every `.css` file in every origin joins `app.css`.  There is no widget, page
+or chrome stylesheet: the builder concatenates them all, with nothing added,
+removed or scoped, so what ships is what was authored.  Within one origin
+they are ordered by filename, the full path breaking a tie, and a
+subdirectory never affects the order.  Origins follow the cascade — this
+package's own widgets, then each package named in `imports.ts`, then `--src`
+last — so an application's own stylesheet always lands after the ones it
+imported.  A file named `00-global.css` sorts first by saying so.
+
+### What the builder scans
+
+#### The current project
+
+The builder scans one directory named by its `--src` parameter,
+which defaults to `src/`.  
+
+The sections below often state something like, "anywhere in 
+the `--src` tree", because Loadbare/app assigns semantic meaning
+to file names, not subdir names.
+
+#### Imported widget libraries
+
+Any number of widget libraries can be used.  They are named
+in the file `imports.ts`, located anywhere in builder `--src`.
+A project can leave out `imports.ts`, or have exactly one, but
+two or more is an error.
+
+```ts
+// imports.ts, anywhere in --src
+export default ["@namespace/widget-library"];
+```
+
+If the named package's `package.json` declares where the widgets
+are, Loadbare scans that.  Otherwise it scans the entire installed
+directory.  The declaration, if present, would look like this:
+
+```json
+"loadbare": { "widgets": "./dist" }
+```
+
+### File names and the builder
+
+The builder finds a file by its name.  A subdirectory carries no meaning, so
+the whole of `--src` is one flat namespace, as stated in
+[What the builder scans](#what-the-builder-scans).
+
+Three kinds of file hold HTML.
+
+| File               | Holds                                | Found in     |
+|--------------------|--------------------------------------|--------------|
+| `chrome.html`      | The one HTML document                | `--src`      |
+| `<stub>.page.html` | One page's markup, as a fragment     | `--src`      |
+| `<tag-name>.html`  | One widget definition, as a fragment | Every origin |
+
+As stated in [Chrome](#chrome), `chrome.html` is a required singleton. 
+
+As stated in [Pages](#pages), the `<stub>` of a `.page.html` is the path the
+page maps to.  The builder puts all pages into `dist/app.html` as HTML `<template>` objects
+that carry `lb-page="<stub>"`.
+
+A widget file is exactly `<kebab-case-name>.html`. A [widget](#widgets) is 
+an HTML custom element, suitable for organizing large HTML trees, or adding
+custom behavior, or both.  A widget definition is named for the tag it expands.
+
+Any other HTML file, one that is not `chrome.html`, or `<stub>.page.html` or
+`<kebab-case-name>.html` will either:
+- be an error if it looks like a widget with capitalization
+- be skipped
+
+## HTML
+
+In a Loadbare/app application, HTML is static after the build, and once
+it is sent to the browser on initial page load, no HTML is ever sent
+again.
+
+### Widget Expansion
+
+The builder executes a process we call "expansion".  When it finds
+a custom element in the HTML it is processing, such as `<my-element>`,
+it looks for the file `<my-element>.html`, and follows the expansion
+rules to place the contents of `<my-element>.html`.
+
+A custom element with no definition file is left alone.  A custom element
+with neither a definition nor a `.browser.ts` script is a build error, as
+stated in [Widgets](#widgets).
+
+#### Build time parameters
+
+A build time parameter is supplied as an attribute on a custom element,
+and is converted to a fixed value within the HTML by the builder.
+
+The attribute value carries an `exp-` prefix, as in `exp-label`, and
+the substitution locations use `{{label}}` (no exp-prefix) inside the
+widget's HTML definition file:
+
+```html
+<!-- lb-input.html, the definition -->
+<label>{{label}} <input readonly="{{readonly}}" /></label>
+```
+
+```html
+<!-- a page -->
+<lb-input lb-cell="name" exp-label="Name"></lb-input>
+```
+
+```html
+<!-- dist/app.html -->
+<lb-input lb-cell="name" exp-label="Name"
+  ><label>Name <input /></label
+></lb-input>
+```
+
+A definition states a default with `{{name|default}}`, as in
+`{{button-label|OK}}`.  Whitespace around the name and around the default is
+discarded.  The default is a literal.
+
+| The attribute is assigned | Expansion defines  | Result                           |
+|---------------------------|--------------------|----------------------------------|
+| `exp-name="text"`         | `{{name}}`         | `text`                           |
+| `exp-name=""`             | `{{name}}`         | An empty string                  |
+| Nothing                   | `{{name|default}}` | `default`                        |
+| Nothing                   | `{{name}}`         | Nothing, and the attribute drops |
+| `exp-name`                | No `{{name}}`      | A build error                    |
+
+Attributes without the `exp-` prefix are ignored during expansion.
+
+A placeholder is the whole of an attribute value or the whole of a text node.
+`title="Hello {{name}}"` ships literally.
+
+A placeholder name carrying a capital is a build error.
+
+A parameter value cannot become markup.
+
+#### Slots and templates
+
+A widget definition may contain any number of named templates and optionally
+one slot.
+
+This simplified definition of `lb-table` names two templates, `head` and
+`foot`, and marks `<tbody>` as the slot.  A page supplies whichever templates
+it wants, and everything else it writes goes to the slot.
+
+```html
+<!-- lb-table.html, the definition -->
+<table>
+  <caption>
+    {{caption}}
+  </caption>
+  <thead lb-template="head"></thead>
+  <tbody lb-slot></tbody>
+  <tfoot lb-template="foot"></tfoot>
+</table>
+```
+
+When we use `lb-table` in HTML, the example below supplies the header
+template and an unnamed template.  The unnamed one names neither `head` nor
+`foot`, so it goes to the slot.  This usage writes no footer.
+
+```html
+<!-- a page -->
+<lb-table lb-list="staff" exp-caption="Everyone, by team">
+  <template lb-template="head">
+    <tr><th>Name</th><th>Role</th></tr>
+  </template>
+  <template lb-key="id">
+    <tr><td lb-cell="name"></td><td lb-cell="role"></td></tr>
+  </template>
+</lb-table>
+```
+
+When a named template is expanded, the `<template>` tag is discarded and its
+contents are placed as children of the tag that names it.  The built document
+holds:
+
+```html
+<!-- dist/app.html -->
+<lb-table lb-list="staff" exp-caption="Everyone, by team"
+  ><table>
+    <caption>
+      Everyone, by team
+    </caption>
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Role</th>
+      </tr>
+    </thead>
+    <tbody>
+      <template lb-key="id">
+        <tr>
+          <td lb-cell="name"></td>
+          <td lb-cell="role"></td>
+        </tr>
+      </template>
+    </tbody>
+    <tfoot></tfoot></table
+></lb-table>
+```
+
+These are build errors:
+
+- A definition with two templates of one name
+- A definition with more than one `lb-slot`
+- A page naming a template the definition does not have
+- A page giving two templates for one name
+- Content written in a widget whose definition has no slot
+
+### Binding
+
+---- UNEDITED ----
+
+Binding attributes determine how the hub updates the DOM, either by
+directly updating a plain HTML element or instructing 
+custom widgets to update themselves.
+
+
+| Attribute    | Assigned By | Behavior                                                                                  |
+|--------------|-------------|-------------------------------------------------------------------------------------------|
+| lb-list      | Developer   | Scopes DOM children to a named set of rows; a nested lb-list or lb-row begins a new scope |
+| lb-row       | Developer   | Scopes DOM children to one named row; a nested lb-list or lb-row begins a new scope       |
+| lb-cell      | Developer   | This DOM node displays this column of the row in scope                                    |
+| lb-key       | Developer   | Names the column that identifies a row, on the row template inside an lb-list             |
+| lb-key-value | Hub         | Stamped on a live row: that row's value of `lb-key`                                       |
+| lb-value     | Hub         | Custom widgets update themselves when this attribute changes                              |
+
+#### How a value lands
+
+A cell lands one of two ways, and the tag name decides which.
+
+| Element                          | Receives the value as    |
+|----------------------------------|--------------------------|
+| A native element                 | Its `textContent`        |
+| A custom element, tag hyphenated | Its `lb-value` attribute |
+
+A native element has no behavior of its own, so its value is its text.  A
+widget owns whatever control it wraps, so it is handed the value and renders
+it itself.
+
+The test is the hyphen in the tag name.  The hub holds no knowledge of any
+particular element, and the same test decides that the hub leaves a widget's
+own clicks alone — see [Requests](#requests).
+
+Nothing an application writes ever sets `lb-value`.  Loadbare writes it and
+the widget it is written on reads it.
+
+The value arrives as the query produced it, with no conversion, so the
+browser decides what a non-string looks like.
+
+A widget sees `attributeChangedCallback` for an `lb-value` already present
+when it upgrades, so a widget cannot tell a first landing from a refresh,
+and does not need to.
+
+### Requests
+
+---- UNEDITED ----
+
+Any element can carry the `lb-action` attribute.  The hub listens for
+events `click` and `submit`, and fires a server request when it catches
+one of those events.
+
+The hub does not act on `click` or `submit` on a custom widget, they
+must fire their own event.  The assumption is a custom widget is present
+because custom behavior is desired, and we don't want the hub to conflict
+with that custom behavior.  A widget is told apart by the hyphen in its tag
+name, the same test that decides how a value lands — see
+[How a value lands](#how-a-value-lands).
+
+| lb-action      | Written on                                        |
+|----------------|---------------------------------------------------|
+| lb-row-insert  | a `<form>` in a list scope                        |
+| lb-row-delete  | anything inside a live row                        |
+| lb-row-update  | a `<form>` inside a live row                      |
+| lb-cell-change | a widget wrapping one control                     |
+| anything else  | must be a named routine in the page's server code |
+
+The wire format is not visible to the user, but uses the same lb-*
+attributes minus their prefix, so that it is intelligible when working on
+Loadbare/app itself.
+
+From a native element the hub sends the action plus whatever binding is in
+scope, and never a scalar value.
+
+```
+{ action: "lb-row-insert",  list: "rosterList", values: {...} }
+{ action: "lb-row-delete",  list: "rosterList", key: "42" }
+{ action: "lb-row-update",  list: "rosterList", key: "42", values: {...} }
+```
+
+A widget builds its own request and adds the value of the control it wraps.
+`lb-select` and `lb-options` send an action and a value and no binding.
+`lb-input` sends the binding as well, and is the only sender of a cell
+change.
+
+```
+{ action: "lb-cell-change", list: "rosterList", key: "42", cell: "name", value: "Ann" }
+{ action: "selectTab",      row: "prefs", cell: "active_tab", value: "two" }
+```
+
+#### The request event
+
+The hub does not send a request the moment it catches a click or a submit.
+It builds the request, dispatches it from the element that acted as a
+bubbling `lb-request` event carrying the request as its `detail`, and a
+listener on the hub sends it.
+
+A widget uses that same event, and it is the only channel a widget has for
+firing a request of its own.  A native element and a hand-written widget
+therefore produce identical events.
+
+An ancestor sees the request on its way up and may stop it.  The event is
+not cancelable, so an interceptor calls `stopPropagation`, not
+`preventDefault`.  This is what makes a confirmation wrapper possible
+without the wrapped element knowing about it.
+
+#### The round trip
+
+A request the hub sends has ten seconds to come back.  Past that the hub
+aborts it and treats it as a failure, since `fetch` imposes no deadline of
+its own.  An application cannot change the deadline.
+
+A round trip fails on a server error, on a network failure, or on that
+deadline, and all three set `lb-error` on the element that dispatched the
+request — see [Request state](#request-state).
+
+A navigation that fails to load its data sets nothing.  No element
+dispatched it, so there is nothing to stamp, and the hub reports it to the
+console.
+
+### Links
+
+---- UNEDITED ----
+
+An anchor carrying `lb-nav-link` navigates inside the application: the hub
+catches the click, pushes the anchor's path onto history, and swaps the page
+host in `<main>`.  An anchor without it is left alone and behaves like any
+other link, so leaving the application is the default and staying in it is
+the opt-in.
+
+| Attribute   | Assigned By | Behavior                                                                                |
+|-------------|-------------|-----------------------------------------------------------------------------------------|
+| lb-nav-link | Developer   | On an `<a>`: the hub shows the page the anchor's path names, without loading a document |
+
+The attribute takes no value.  The hub looks for the nearest ancestor 
+link to determine the path.
+
+Path space is flat.  A path such as `/members` links to the `members.*` files
+on the server.
+
+The bare path `/` resolves to `index`.
+
+A path that names no page is detected in the browser, after a successful
+200: every route gets the same document, so there is no server-delivered
+404.  A chrome that declares an `lb-unknown-page` dialog gets it opened.
+One that declares none gets a console error and nothing on screen.  See
+[Chrome](#chrome).
+
+```html
+<nav>
+  <a href="/" lb-nav-link>Home</a>
+  <a href="/members" lb-nav-link>Members</a>
+  <a href="https://example.com/docs">Docs</a>
+</nav>
+```
+
+See also [Navigation Row lb-navigation](#lb-navigation).
+
+### lb-navigation
+
+---- UNEDITED ----
+
+Status: 1.0-RC.
+
+Current page, published by the hub as a row.  Can be bound anywhere just
+like a server-produced result.
+
+| Cell         | Holds                                                               |
+|--------------|---------------------------------------------------------------------|
+| `page-label` | The text of the link to the current page, empty if no link names it |
+| `page-uri`   | The path as the browser has it, such as `/members`                  |
+
+The `page-uri` is taken from the current URL.  The `page-label` is taken from the first
+`lb-nav-link` link in the document (presumably in a nav bar) that matches the URI.
+
+The row lands before the page is looked up, so a path that names no page has
+it too, and an `lb-unknown-page` dialog, where the chrome has one, displays
+it by naming the row like any other subtree.
+
+It lands only where a subtree names it.  A chrome that displays no
+navigation is not warned about a row with nowhere to go.
+
+```html
+<header lb-row="lb-navigation">
+  <h2 lb-cell="page-label"></h2>
+</header>
+```
+
+See also [Links](#links).
+
+## Application files
+
+### Chrome
+
+The Loadbare/app builder always requires exactly one file
+named `chrome.html`, located anywhere in builder `--src`.
+
+The chrome is the application's single HTML document.  This is
+where the standard landmarks go: header, nav, footer, main.
+
+The file is an HTML document, which must contain:
+- `<lb-hub>` inside `<body>`.  The hub can only act on its children,
+  that is why it is usually nested right below `<body>`. 
+- One empty `<main>` inside `<lb-hub>`.  
+- The script tag for `/client.js`, the javascript bundle.
+
+It may also contain:
+- `/app.css`, the stylesheet bundle
+- A `<dialog>` marked with attribute `lb-unknown-page`, which the hub
+  will display to the user if an attempt is made to navigate to an
+  unknown page.  It goes inside `<lb-hub>`, like everything the hub acts
+  on; the builder rejects one placed elsewhere.
+- The `hidden` attribute on `<body>`, which the hub removes once the first page has landed.
+
+```html
+<!-- src/chrome.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Membership Roster</title>
+    <script src="/client.js" defer></script>
+    <link rel="stylesheet" href="/app.css" />
+  </head>
+  <body hidden>
+    <lb-hub>
+      <header lb-row="lb-navigation">
+        <h1>Membership Roster</h1>
+        <h2 lb-cell="page-label"></h2>
+      </header>
+      <nav>
+        <a href="/" lb-nav-link>Home</a>
+        <a href="/members" lb-nav-link>Members</a>
+        <a href="https://example.org/">Our website</a>
+      </nav>
+      <main></main>
+      <dialog lb-unknown-page lb-row="lb-navigation">
+        The URL <span lb-cell="page-uri"></span> is not in this app.
+      </dialog>
+    </lb-hub>
+  </body>
+</html>
+```
+
+The `lb-row`, `lb-cell` and `lb-nav-link` attributes in that example are
+ordinary Loadbare/app binding.  See [Binding](#binding),
+[Links](#links) and [lb-navigation](#lb-navigation).
+
+### Pages
+
+The page namespace is flat.  Loadbare/app does not care where in the `--src`
+the page files are located, but they must be unique across the application.
+A page `/deep/path/to/mypage.html` is routed to `/mypage`.
+
+Pages are grouped as
+- <stub>.page.html is recognized as navigable and capable of
+  having associated queries and requests
+- <stub>.queries.ts are the queries for a page
+- <stub>.requests.ts respond to the requests from the browser
+
+The <stub> value for a page must match the path used in links,
+so that `<a href='/members' lb-nav-link>Members</a>` has matching
+files `members.pages.html` et al.
+
+#### Page HTML
+
+The markup in `<stub>.page.html` is the same HTML as everywhere else
+in a Loadbare/app application, see [HTML](#html).
+
+The builder wraps each expanded page in `<template lb-page="<stub>">` and
+puts it in the built document.  The application never writes `lb-page`; the
+hub reads it to find the page a path names.
+
+## The server
+
+A page's server half is two files, `<stub>.queries.ts` and
+`<stub>.requests.ts`.  Each pairs with `<stub>.page.html` by sharing its
+stub, as stated in [Pages](#pages).  Either may be absent, and one with no
+matching page is a build error.
+
+### The Express server
+
+Loadbare/app ships no server.  The application writes an ordinary Express
+app.  Express is a peer dependency, installed by the application.
+
+The builder's artifacts oblige that server to handle four things: the
+client script, the stylesheet, the hub's data channel, and the one HTML
+document.
+
+| Handle                       | With                |
+|------------------------------|---------------------|
+| `/client.js`                 | `dist/client.js`    |
+| `/app.css`                   | `dist/app.css`      |
+| `hubRoutes(hub, contextFor)` | The hub's own route |
+| Every other GET              | `dist/app.html`     |
+
+The builder writes `pages.ts` into `--out` whenever any page has a
+`.queries.ts` or a `.requests.ts` file.  It imports each of them, calls
+`createHub()` once over the lot, and exports the result as `hub`.  The
+server imports that rather than maintaining the registry by hand.
+
+```ts
+// server.ts
+import path from "node:path";
+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 { openDb } from "./src/database";
+
+const DIST = path.resolve("dist");
+const app = express();
+
+// All data requests are handled by the hub
+// This example shows an application-specific openDB()
+function contextFor(_req: Request): HubContext {
+  return { db: openDb() };
+}
+app.use(hubRoutes(hub, contextFor));
+
+// Static assets, then the catch-all for app.html
+app.get("/client.js", (_req, res) => res.sendFile(path.join(DIST, "client.js")));
+app.get("/app.css", (_req, res) => res.sendFile(path.join(DIST, "app.css")));
+app.get(/.*/, (_req, res) =>
+  res.type("html").send(readFileSync(path.join(DIST, "app.html"), "utf-8")),
+);
+
+app.listen(8787);
+```
+
+Explaining Express is beyond the scope of this technical reference.  The
+only real requirement is that the catch-all for app.html is at the end,
+so it does not catch any other files.
+
+Give the server the origin root.  The hub reaches its own endpoints by
+absolute path, so an application cannot be hosted under a subpath such as
+`example.com/myapp/`, and anything proxying in front of the server passes
+the whole path space through unchanged.
+
+### Page Queries
+
+`<stub>.queries.ts` exports one object named `queries`, typed `Queries`.
+Each key is a query name, and the markup binds to that name through
+`lb-list` or `lb-row`.
+
+Cardinality belongs to the named query.  One named query always returns a single
+row or an array of rows.  Build a query using `row()` or `list()` to return
+the two shapes.  A query cannot be built without one of these functions.
+
+Queries names cannot begin with `lb-`, that namespace is reserved for
+Loadbare/app queries the hub makes available in the browser, such
+as [lb-navigation](#lb-navigation).
+
+```ts
+// members.queries.ts
+import { list, row, type Queries } from "@loadbare/app/server";
+
+export const queries: Queries = {
+  roster: list((ctx) => ctx.db.members()),
+  summary: row(async (ctx) => ({ count: String(await ctx.db.memberCount()) })),
+};
+```
+
+Every query and every request receives `ctx`, the application's own request
+context.  The application builds it once per request and hands it to the hub,
+see [The Express server](#the-express-server).  Loadbare/app declares it empty
+and never reads it, so a query finds exactly what the application put there,
+which is usually a database handle opened for the authenticated caller.
+
+Queries should not return deltas, deltas are handled in the `.requests.ts` file
+as explained in the next section.
+
+### Page Requests
+
+`<stub>.requests.ts` exports one object named `requests`, typed `Requests`.
+It has three optional keys.
+
+| Key           | Keyed by              | Answers                                            |
+|---------------|-----------------------|----------------------------------------------------|
+| `actions`     | The `lb-action` value | Anything the page chooses to declare               |
+| `crud`        | A query name          | The four reserved `lb-action` values               |
+| `onPageEnter` | Nothing               | Runs once on entering the page, before its queries |
+
+
+The hub resolves an `lb-action` value against `actions`, and a reserved
+operation against `crud` under the bound list name.  A name with no entry
+there logs a server console warning naming the page and the missing entry,
+and answers 200 with `{}`.  The browser applies `{}`, so no cell is set and
+no row is added or removed, and `lb-pending` clears from the element that
+sent the request.  A request carrying no action answers 400, and a `run`
+that throws answers 500.
+
+Every entry under `actions` and `crud` has the same two members.  `run`
+performs the work, and `refresh` names the queries to re-run once the action
+is complete.
+
+`run` receives the same `ctx` and a `where`: the binding in scope when the
+interaction happened, as `list`, `row`, `key`, `cell` and `value`.  Under
+`crud` the `where` carries only what that operation is typed to carry.
+
+`run` may also return results of its own, which are laid over the refreshed
+ones.  That is how a delta reaches the browser: wrap it in `patch()`, naming
+the rows that arrived or changed and the keys that went.
+
+```ts
+// members.requests.ts
+import { patch, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  actions: {
+    resetRoster: {
+      run: (ctx) => ctx.db.resetMembers(),
+      refresh: ["roster"],
+    },
+  },
+  crud: {
+    roster: {
+      rowDelete: {
+        run: async (ctx, where) => {
+          await ctx.db.deleteMember(where.key);
+          return { roster: patch({ drop: [where.key] }) };
+        },
+        refresh: [],
+      },
+    },
+  },
+};
+```
+
+Each key under a `crud` entry is a reserved `lb-action` value with its prefix
+stripped and the rest camel-cased, so the attribute, the wire and this key
+are one vocabulary.  All four operate on a list, because each needs a key and
+a key exists only on a live row.
+
+| `lb-action`      | Key under `crud` | `where` carries        |
+|------------------|------------------|------------------------|
+| `lb-cell-change` | `cellChange`     | `key`, `cell`, `value` |
+| `lb-row-delete`  | `rowDelete`      | `key`                  |
+| `lb-row-insert`  | `rowInsert`      | `values`               |
+| `lb-row-update`  | `rowUpdate`      | `key`, `values`        |
+
+## Widgets
+
+---- UNEDITED ----
+
+A widget is an HTML custom element following these fixed rules:
+- Element name must contain a hyphen, as per hTML rules, like <my-custom-element>
+- HTML code, if present, is `my-custom-element.html`
+- TS code, if present, is in `my-custom-element.browser.ts`.  The
+  'browser' segment is a safety feature, requiring the file to be
+  explicitly named as a browser file, to help prevent unfortunate
+  naming collisions where a server file happens to have the name of
+  a widget and gets built into the browser bundle.
+
+A widget must have either one or the other of HTML and Typescript, and
+it may have both.  If it has neither, the builder reports an error.
+
+To use a widget from a library, add the library to `imports.ts` anywhere
+in the builders `--src`:
+
+```ts
+export default ["@scope/library-name"];
+```
+
+### Widget authoring
+
+---- UNEDITED ----
+
+The expansion grammar, `exp-`, `lb-slot`, `lb-template`, the reserved `LB-`
+namespace, then `lbPlaceRow` and `lbRowsLanded`. One bucket spanning build
+time and run time, because a widget is a definition and a script together.
+
+#### Request state
+
+The hub stamps these on the element that dispatched a request, which is the
+widget itself when a widget fired it.  A widget observes them and reacts; it
+must name them in `observedAttributes` to see them change.
+
+| Attribute      | Written on              | Holds                                           |
+|----------------|-------------------------|-------------------------------------------------|
+| `lb-pending`   | The dispatching element | The round trip is in flight                     |
+| `lb-error`     | The dispatching element | The last round trip failed, cleared on the next — see [The round trip](#the-round-trip) |
+| `lb-row-count` | A list scope            | How many rows the scope is showing              |
+
+The hub writes all three and never reads them.  They are also stamped on
+plain HTML, where a stylesheet is the only consumer: dim a pending button,
+mark a failed one, and style an empty list against `lb-row-count` rather than
+carrying an empty-state element.
+
+#### Row hooks
+
+| Name                            | Implemented By | Behavior                                                    |
+|---------------------------------|----------------|-------------------------------------------------------------|
+| `applyRow(root, row)`           | Loadbare       | Fills one scope from one row                                |
+| `lbPlaceRow(el, row, template)` | Developer      | Optional on a list scope: where a row goes                  |
+| `lbRowsLanded()`                | Developer      | Optional on a list scope: scaffolding derived from the rows |
+
+## Internal linkage
+
+---- UNEDITED ----
+
+The endpoint path, `index` for the bare path, the constant holding the
+request deadline, the generated client entry, and the `./build` export.
+Nobody outside this package reads any of it.  The deadline itself is
+behavior an application sees — see [The round trip](#the-round-trip) — and
+giving it a knob later takes nothing away.
+
+## Cross-reference
+
+Every name Loadbare/app owns, in one place. Each row names the section
+that defines it. The definition lives there and only there.
+
+### Builder flags
+
+Loadbare/app owns every flag in this table.
+
+| Flag       | Default | Names                                     | Defined in                                        |
+|------------|---------|-------------------------------------------|---------------------------------------------------|
+| `--src`    | `src`   | The application's own tree, scanned whole | [What the builder scans](#what-the-builder-scans) |
+| `--out`    | `dist`  | Where the builder writes                  | [Running the builder](#running-the-builder)       |
+| `--watch`  | off     | Rebuild on change under `--src`           | [Running the builder](#running-the-builder)       |
+| `--minify` | off     | Minify `client.js` and `app.css`          | [Running the builder](#running-the-builder)       |
+
+### Reserved file names
+
+Loadbare/app owns every file name and pattern in this table.  A file so
+named carries its meaning wherever it sits in the `--src` tree, so an
+application must not use one of these names for anything else.
+
+| File                    | How many               | Holds                                                    | Defined in                                              |
+|-------------------------|------------------------|----------------------------------------------------------|---------------------------------------------------------|
+| `chrome.html`           | Exactly one            | The application's one HTML document                      | [Chrome](#chrome)                                       |
+| `imports.ts`            | Zero or one            | Default-exports an array of widget library package names | [Imported widget libraries](#imported-widget-libraries) |
+| `<stub>.page.html`      | One per page           | One page's markup, as a fragment                         | [Pages](#pages)                                         |
+| `<stub>.queries.ts`     | Zero or one per page   | That page's queries                                      | [Page Queries](#page-queries)                           |
+| `<stub>.requests.ts`    | Zero or one per page   | That page's requests                                     | [Page Requests](#page-requests)                         |
+| `<tag-name>.html`       | Zero or one per widget | One widget definition, as a fragment                     | [Widgets](#widgets)                                     |
+| `<tag-name>.browser.ts` | Zero or one per widget | One widget's script, `.js` also accepted                 | [Widgets](#widgets)                                     |
+| `*.css`                 | Any number             | A stylesheet, concatenated into `app.css`                | [Running the builder](#running-the-builder)             |
+
+### Build outputs
+
+Loadbare/app owns every file name in this table.  The builder writes them
+into `--out`.  Which of them exist depends on the application: `app.css`
+only when some origin has a stylesheet, `pages.ts` only when some page has a
+`.queries.ts` or a `.requests.ts`.
+
+| Path               | Written           | Holds                                                              | Read by    | Defined in                                  |
+|--------------------|-------------------|--------------------------------------------------------------------|------------|---------------------------------------------|
+| `/app.html`        | Always            | The chrome, built                                                  | The server | [Chrome](#chrome)                           |
+| `/client.js`       | Always            | `<lb-hub>` and every widget the application uses                   | The chrome | [Chrome](#chrome)                           |
+| `/client-entry.ts` | Always            | The generated entry `client.js` is bundled from                    | Nothing    | [Running the builder](#running-the-builder) |
+| `/app.css`         | With a stylesheet | Every stylesheet in the cascade, concatenated                      | The chrome | [Chrome](#chrome)                           |
+| `/pages.ts`        | With page data    | The one `createHub()` call, over every page's queries and requests | The server | [The Express server](#the-express-server)   |
+
+### Reserved package.json keys
+
+Loadbare/app owns every key in this table. A widget library declares them.
+An application never does.
+
+| Key                | Value                     | Means                                                                        | Defined in                                              |
+|--------------------|---------------------------|------------------------------------------------------------------------------|---------------------------------------------------------|
+| `loadbare.widgets` | A path inside the package | Where this package's widgets are. Absent means the whole installed directory | [Imported widget libraries](#imported-widget-libraries) |
+
+### Reserved namespaces
+
+Loadbare/app owns every namespace in this table. Ownership of a name and
+ownership of its behavior are stated separately, because they differ.
+
+| Namespace | Applies to                 | Loadbare owns                                | Defined in                                        |
+|-----------|----------------------------|----------------------------------------------|---------------------------------------------------|
+| `lb-*`    | HTML attributes            | The names and their behavior                 | [The lb-* namespace](#the-lb--namespace)           |
+| `exp-*`   | HTML attributes            | The behavior; widget authors pick the values | [Build time parameters](#build-time-parameters)   |
+| `lb*`     | Methods on custom elements | The names and their behavior                 | [Row hooks](#row-hooks)                           |
+
+#### The lb-* namespace
+
+Every HTML attribute beginning with `lb-` belongs to Loadbare/app.  An
+application writes the ones this table names and invents none of its own,
+because a name Loadbare has not defined today it may define tomorrow.
+
+The prefix reaches past HTML.  A query name cannot begin with `lb-` either,
+which is what keeps the four operations apart from an application's own
+actions on the wire — see [Page Queries](#page-queries).
+
+Each attribute is defined in one section, and this table says which.
+
+| Attribute        | Written by  | Defined in                                        |
+|------------------|-------------|---------------------------------------------------|
+| `lb-list`        | Developer   | [Binding](#binding)                               |
+| `lb-row`         | Developer   | [Binding](#binding)                               |
+| `lb-cell`        | Developer   | [Binding](#binding)                               |
+| `lb-key`         | Developer   | [Binding](#binding)                               |
+| `lb-key-value`   | Hub         | [Binding](#binding)                               |
+| `lb-value`       | Hub         | [How a value lands](#how-a-value-lands)           |
+| `lb-action`      | Developer   | [Requests](#requests)                             |
+| `lb-nav-link`    | Developer   | [Links](#links)                                   |
+| `lb-pending`     | Hub         | [Request state](#request-state)                   |
+| `lb-error`       | Hub         | [Request state](#request-state)                   |
+| `lb-row-count`   | Hub         | [Request state](#request-state)                   |
+| `lb-unknown-page`| Developer   | [Chrome](#chrome)                                 |
+| `lb-slot`        | Widget author | [Slots and templates](#slots-and-templates)     |
+| `lb-template`    | Widget author | [Slots and templates](#slots-and-templates)     |
+| `lb-page`        | Builder     | [Pages](#pages)                                   |
+
+An attribute the builder does not recognize is left alone today.  Refusing
+one is on the list of validations still to land — see
+[The builder](#the-builder).
+
+### Reserved tags
+
+Loadbare/app owns every tag in this table.  An application writes them and
+never defines them.
+
+| Tag        | Written in | Means                          | Defined in        |
+|------------|------------|--------------------------------|-------------------|
+| `<lb-hub>` | The chrome | The application's live element | [Chrome](#chrome) |
+
+### Reserved events
+
+Loadbare/app owns every DOM event in this table, both the name and what its
+`detail` carries.
+
+| Event        | Dispatched from        | Bubbles | Cancelable | Defined in                              |
+|--------------|------------------------|---------|------------|-----------------------------------------|
+| `lb-request` | The element that acted | Yes     | No         | [The request event](#the-request-event) |
+
+### Reserved attributes
+
+Loadbare/app owns every attribute in this table, both the name and its
+behavior.
+
+| Attribute         | Written on                          | Takes a value | Defined in        |
+|-------------------|-------------------------------------|---------------|-------------------|
+| `lb-unknown-page` | A `<dialog>` in chrome              | No            | [Chrome](#chrome) |
+| `lb-page`         | A `<template>`, by the builder only | Yes           | [Pages](#pages)   |