@loadbare/app 0.10.0 → 0.12.0

package/docs/reference/custom-elements.md

@@ -190,6 +190,36 @@ path that closes it.
 Expansion runs over `<template>` contents wherever they occur, so a
 definition's row template ships already expanded, `{{placeholder}}` included.
 
+### Where a custom element can go
+
+HTML limits what an element may hold. A `<p>` holds only phrasing content,
+such as text, `<span>` and `<button>`, and a `<button>` may not hold another
+`<button>`. The parser does not refuse markup that breaks these rules; it
+rearranges it. `<p>Total <div>12</div></p>` becomes a paragraph, then a div,
+then an empty paragraph, with nothing logged.
+
+Each file is parsed on its own, so a page file and an element file each get
+the tree the browser would give them. Expansion then places one inside the
+other, and that join is where a rule can break. A definition containing a
+`<div>` or a `<dialog>` cannot go inside a `<p>`, since the browser would
+close the paragraph early and move the rest of the definition out of its
+element. The build refuses such a page, naming the file, the custom element
+and the path to what would move:
+
+```
+assemble: 'src/pages/ledger.page.html': expand: <lb-confirm> puts <dialog>
+where the browser's parser would not keep it, at p > lb-confirm > dialog.
+```
+
+Put a custom element whose definition holds block content, such as a
+`<div>`, a `<dialog>` or a `<p>`, in a `<div>`, a `<li>`, a `<td>` or another
+element that holds flow content.
+
+Never write a custom element inside a `<select>`, an `<option>` or a
+`<textarea>`. The parser drops the tag inside the first two, and inside a
+`<textarea>` it is text. Both happen when the page file is read, before
+expansion, so the build cannot see the element to report it.
+
 ### What fails at build time
 
 Each of these is reported with the tag and file name, and nothing is
@@ -204,6 +234,8 @@ shipped:
 - a `<template lb-exp-template="name">` naming a destination the definition
   does not have
 - two templates for the same destination
+- a custom element placed where the browser's parser would move its
+  contents; see [Where a custom element can go](#where-a-custom-element-can-go)
 
 An unfilled `{{placeholder}}` is not among these. That is presence
 propagation working as intended, indistinguishable from an author who left
@@ -228,12 +260,16 @@ one as a string literal:
 | `ATTR_REQUEST`         | `lb-request`         |
 | `ATTR_COLUMN_VALUE`    | `lb-column-value`    |
 | `ATTR_KEY_VALUE`       | `lb-key-value`       |
+| `ATTR_ROW_LIVE`        | `lb-row-live`        |
+| `LIVE_ROW`             | `[lb-row-live]`      |
 | `ATTR_QUERY_ROW_COUNT` | `lb-query-row-count` |
 | `ATTR_REQUEST_PENDING` | `lb-request-pending` |
 | `ATTR_REQUEST_ERROR`   | `lb-request-error`   |
 | `REQUEST_ROW_INSERT`, `REQUEST_ROW_UPDATE`, `REQUEST_ROW_DELETE` | The requests Loadbare provides |
 | `LB_ROW_REQUESTS`      | All three, in one array |
 | `LB_EVENT_NAME`        | `lb-request`, the event every request travels as |
+| `LB_DONE_EVENT_NAME`   | `lb-request-done`, the event that says how it turned out |
+| `SHOW_NOT`             | `!`, written before a column in `lb-show` |
 | `URL_QUERY`            | `lb-url`             |
 | `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
 | `LB_RESERVED_PREFIX`   | `lb-`                |
@@ -244,6 +280,64 @@ writes them in markup, and the hub and the builder write their stamps.
 Loadbare reserves method names beginning with `lb` on a custom element, for
 the methods it calls; see [Holding rows](#holding-rows).
 
+### What the hub and an element say to each other
+
+Each direction has one mechanism for each kind of message:
+
+| Direction      | What                                       | How                         | Today |
+|----------------|--------------------------------------------|-----------------------------|-------|
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error` |
+| Hub to element | State the platform already names           | A property                  | A control's `value` |
+| Hub to element | Work the hub needs done now, while landing | An optional `lb` method     | `lbPlaceRow`, `lbRowsLanded` |
+| Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
+| Element to hub | A moment                                   | A bubbling event            | `lb-request`, and `change`, `click` and `submit` |
+
+State is an attribute: a stylesheet can select on it, and an element that
+upgrades late still finds it. A method is for work the hub cannot go on
+without, done by one element at one point in landing. A moment is an event,
+because the element that cares is often an ancestor of the one it concerns,
+and an event reaches it knowing neither.
+
+### When its code runs
+
+The hub creates, places and parks elements, and each of those reaches a
+custom element as the browser's lifecycle callbacks. It is the same instance
+from its constructor on, however often it moves:
+
+| What the hub does                                  | Callbacks, in order                         |
+|----------------------------------------------------|---------------------------------------------|
+| Shows a page                                       | `constructor`, `connectedCallback`          |
+| Creates a live row, filled before it is placed     | `constructor`                               |
+| Places a live row for the first time               | `connectedCallback`                         |
+| Places it again, as it does on every set of all rows | `disconnectedCallback`, `connectedCallback` |
+| Removes a live row                                 | `disconnectedCallback`                      |
+| Turns `lb-show` off                                | `disconnectedCallback`, `adoptedCallback`   |
+| Turns `lb-show` on                                 | `adoptedCallback`, `connectedCallback`      |
+| Turns on an element the builder shipped absent     | `constructor`, `connectedCallback`          |
+
+The builder ships every `lb-show` element inside its template, and nothing
+in a template is upgraded, so such an element has no instance until its
+column first turns on. See
+[Conditional rendering](./data-binding.md#conditional-rendering).
+
+So each kind of work has one place:
+
+1. **A listener on the element itself goes in the constructor.** It is
+   attached once and survives every move, and a live row gets its own
+   because each row is a new instance. An event from a child bubbles to the
+   element, so the listener needs no child to exist yet. The constructor
+   reads no attribute and no child: an element made with
+   `document.createElement` has neither when it runs.
+2. **A child is looked up when it is needed**, in a handler, a getter,
+   `lbPlaceRow` or `lbRowsLanded`, and never held from setup.
+3. **`connectedCallback` runs on every move**, so it is written to run
+   again. It rearranges the element's own children into a state it checks
+   for first, or adds a listener to `document` or `window`, which
+   `disconnectedCallback` removes. Work done once per instance that needs
+   the element's attributes, such as a control taking up a value that landed
+   before it upgraded, goes behind a flag there; see
+   [Being a control](#being-a-control).
+
 ### Being a control
 
 A form-associated custom element with a `value` property that fires `change`
@@ -253,10 +347,20 @@ and commits its `lb-request` on `change`:
 
 ```ts
 // src/star-rating.browser.ts
+import { ATTR_COLUMN_VALUE } from "@loadbare/app/constants";
+
 class StarRating extends HTMLElement {
   static formAssociated = true;
   #internals = this.attachInternals();
   #value = "";
+  #connected = false;
+
+  connectedCallback() {
+    if (this.#connected) return;
+    this.#connected = true;
+    const stamped = this.getAttribute(ATTR_COLUMN_VALUE);
+    if (stamped !== null) this.value = stamped;
+  }
 
   get value(): string {
     return this.#value;
@@ -292,6 +396,14 @@ customElements.define("star-rating", StarRating);
 Dispatch `change` with `bubbles: true`, as a native control's does, when the
 user commits an edit. Setting `value` from the hub fires nothing.
 
+A control can receive its value before it is a control. An element the
+builder shipped absent, or one whose definition loads after the hub has
+landed, is not upgraded when its column lands, so the hub cannot set its
+`value` and the value arrives as `lb-column-value` alone. Take the stamp up
+the first time the control connects, as `connectedCallback` does above, and
+never again: after that the hub sets `value` itself, and a later move must
+not undo an edit.
+
 A form owns a form-associated custom element the way it owns an `<input>`,
 including through the HTML `form` attribute, so a form gathers it on submit.
 Write `formResetCallback` to restore the default value: the hub resets a form
@@ -330,14 +442,9 @@ List `ATTR_COLUMN_VALUE` in `observedAttributes`. The browser calls
 upgrades, as well as for one that changes afterward, so the first render and
 every later one go through the one callback.
 
-A custom element carrying `lb-show`, or inside an element that does, is
-moved into a template while its column is off and back out when it turns on
-— see [Conditional rendering](./data-binding.md#conditional-rendering).
-Going in, it sees `disconnectedCallback` and then `adoptedCallback`; coming
-out, `adoptedCallback` and then `connectedCallback`. It is the same instance
-throughout, and it still receives its column while it is away, so write
-`connectedCallback` to run more than once, as a live row the hub reorders
-already requires.
+A custom element carrying `lb-show`, or inside an element that does, still
+receives its column while it is away, so it returns current; see
+[When its code runs](#when-its-code-runs).
 
 ### Sending a request
 
@@ -363,6 +470,39 @@ missing a field its name needs, and stamps the dispatching element with
 
 Let the event bubble, so an ancestor can stop it before the hub sends it.
 
+### Hearing how it turned out
+
+Once what a request brought back has landed, or its round trip has failed,
+the hub dispatches `lb-request-done` from the element that committed. It
+bubbles, so the element that cares need not be the one that committed: a
+dialog hears it from the form inside it.
+
+```ts
+import { LB_DONE_EVENT_NAME } from "@loadbare/app/constants";
+import type { HubRequestDone } from "@loadbare/app/types";
+
+this.addEventListener(LB_DONE_EVENT_NAME, (e) => {
+  const { request, items, error } = (e as CustomEvent<HubRequestDone>).detail;
+  if (error) return;
+  const item = items.find((i) => i.query === request.query);
+  const created = item?.patch?.rows?.[0];
+  if (created) this.choose(String(created[item!.key]));
+});
+```
+
+`items` is every response item that landed because of the request, in
+order. An answer that moved the URL contributes its `lb-url` item, which
+carries a key only the server knew, and the page load. `error` is set when
+the round trip failed, and then nothing landed. A new row's key is in the
+answer only when the handler returned it in a patch: a refresh sends all
+rows, and nothing marks which one is new.
+
+By the time the event is dispatched, `lb-request-pending` is gone and the
+page is as the answer left it. A request that was never sent, because the
+hub or an ancestor stopped it, gets no `lb-request-done`. An element the
+answer removed, such as the row a delete took away, dispatches the event
+outside the document, and no ancestor it had there hears it.
+
 ### Holding rows
 
 The hub lands every row template itself. A plain element carrying `lb-query`
@@ -401,7 +541,7 @@ Everything else is the hub's:
 | Cloning     | Clones the row template once per new key                 |
 | Matching    | Fills the live row already showing that key              |
 | Removing    | Removes the live rows the response says are gone         |
-| Stamping    | Stamps each live row with `lb-key-value`                 |
+| Stamping    | Stamps each live row with `lb-row-live` and `lb-key-value` |
 | Counting    | Stamps `lb-query-row-count` with the number of live rows |
 
 `lbPlaceRow` receives the live row already filled and not yet in the
@@ -411,6 +551,20 @@ template, in arrival order. `lb-options.browser.ts` and
 `lb-table.browser.ts` in [`@loadbare/widgets`](./widgets.md) are two
 different placements over the same landing.
 
+A custom element the builder shipped absent under `lb-show` has not
+upgraded while its column is off, so it has no `lbPlaceRow` when rows land
+on it then, and the hub places them before the template. When the column
+first turns on and the element upgrades, the hub lands the query's last
+answer on it again, as all rows, so every row goes through `lbPlaceRow` and
+`lbRowsLanded` runs. Once upgraded it stays so: when its branch goes away and
+comes back, it has placed every row that landed meanwhile, and nothing is
+landed again.
+
+A custom element that walks its own rows finds them with `LIVE_ROW` from
+`@loadbare/app/constants`, never by `lb-key-value`: an element a `row` lands
+on carries a key too, and may sit among the rows, as a total in a table's
+foot does.
+
 Style an empty query against `lb-query-row-count` rather than carrying an
 empty state in the custom element — see
 [Counting rows](./data-binding.md#counting-rows).

package/docs/reference/data-binding.md

@@ -58,6 +58,7 @@ builder writes a stamp, and a stylesheet or a custom element reads it.
 |----------------------|----------------------------------------------------|
 | `lb-column-value`    | The value the hub set from a column                |
 | `lb-key-value`       | The key of a live row, or of a `row` landed on an element |
+| `lb-row-live`        | The element is a live row                          |
 | `lb-query-row-count` | The number of live rows an element holds           |
 | `lb-request-pending` | The element's request is in flight                 |
 | `lb-request-error`   | The element's last request failed                  |
@@ -86,8 +87,11 @@ any nested `lb-query`:
 | `rows` | no           | Lands nothing                          |
 
 A live row is an element the hub cloned from a row template for one row.
-The hub stamps it with `lb-key-value`, the row's key. An element a `row`
-lands on itself carries `lb-key-value` as well.
+The hub stamps it with `lb-row-live`, and with `lb-key-value`, the row's
+key. An element a `row` lands on itself carries `lb-key-value` as well, but
+not `lb-row-live`, so a `row` shown inside another query, such as a total in
+a table's foot, is not one of that query's rows. Select live rows with
+`[lb-row-live]`, never with `[lb-key-value]`.
 
 Write `lb-column` on each element that shows a column. The element reads
 from its nearest ancestor row: the live row it is in, or the element a
@@ -153,6 +157,9 @@ membership and order: a live row whose key did not arrive is removed. A
 patch changes only the rows it names, and every other live row keeps its
 content and its place.
 
+A key is unique within a query. Two rows with one key in the same answer,
+or two live rows showing one key, are reported on the console.
+
 A live row's root counts as a column when it carries `lb-column`, which is
 how an `<option>`, whose content is text, shows the column it is.
 
@@ -161,6 +168,28 @@ a row goes and add scaffolding around the rows; see
 [Holding rows](./custom-elements.md#holding-rows) and
 [The Basic Widget Library](./widgets.md).
 
+### What arrives later
+
+The hub keeps each query's last answer until the page changes, with any
+patch since applied to it. An element that names a query and arrives after
+that query's answer is filled from what was kept, at the end of the landing
+that follows its arrival. Such an element is a picker in a new live row, or
+scaffolding a custom element builds around its rows, such as a ghost row. So
+a query nested in another query's rows need not land again, or land after
+the outer query, for a new outer row to show its choices.
+
+A custom element the builder shipped absent has not upgraded while its
+`lb-show` column is off, so rows that land on it then are not placed by it.
+When the column first turns on and the element upgrades, the hub lands the
+kept answer on it again, and every row goes through its `lbPlaceRow`. So a
+table that groups its rows can sit under `lb-show`. See
+[Holding rows](./custom-elements.md#holding-rows).
+
+Nothing is answered from what the hub kept: a request always goes to the
+server, and a query re-runs only when a response names it. A patch that
+arrives before all of a query's rows is not kept, since it is not the whole
+of anything.
+
 A `rows` query on an element with no row template lands nothing. That is the
 insert form above: it sits inside `lb-query="roster"` so its request is for
 `roster`, and it shows none of its rows.
@@ -218,6 +247,14 @@ have the query answer with a boolean or a null. A row that does not carry
 the column leaves the element as it is, so a query answers with the column
 in every row.
 
+Write `!` before the column to reverse it. One column then decides between
+two elements, rather than a column and its opposite, which could disagree:
+
+```html
+<h2 lb-show="chosen" lb-column="title"></h2>
+<p lb-show="!chosen">Choose a batch.</p>
+```
+
 `lb-show` reads from the nearest ancestor row, as `lb-column` does. On an
 element that also carries `lb-query`, the column belongs to the row around
 it, so this picker takes its choices from `groups` and whether it is present
@@ -456,6 +493,11 @@ An ancestor may stop the event, and the request is not sent. A custom
 element may dispatch the event itself; see
 [Sending a request](./custom-elements.md#sending-a-request).
 
+Once the answer has landed, or the round trip has failed, the hub dispatches
+a bubbling `lb-request-done` event from the same element, carrying the
+request and what landed because of it, or the error; see
+[Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out).
+
 ## The URL
 
 The hub serves one query of its own, `lb-url`: one row holding the path, the
@@ -488,3 +530,4 @@ expansion, and refuses to build:
 - `lb-url-unknown` on anything but a `<dialog>`, or outside `<lb-hub>`
 - `lb-show` on a `<template>`, or on a row template's root
 - `lb-show` with no `lb-query` around it
+- `lb-show="!"` or `lb-show="!!column"`, which reverse no column

package/docs/reference/page-files.md

@@ -16,6 +16,35 @@ every other path names the page whose stub it is.
 Put the files anywhere under `src/`. The builder pairs them by stub, not by
 directory; `src/pages/` is the convention.
 
+## What the page files are
+
+A page's queries are that page's view model, answered on the server. Each
+is shaped for the elements that name it, on one page, so it answers in the
+form the page shows: a date formatted, an amount with its separators, and
+the phrase a reader sees, such as "no postings yet" or "12 postings",
+rather than a count for the browser to word. The hub does no conversion,
+so there is no later place for that work to go. The markup says where each
+value goes, and the query says what it is.
+
+A value the page reads back, rather than only shows, stays data:
+
+| Value                              | Read back by                    | So it is                          |
+|------------------------------------|---------------------------------|-----------------------------------|
+| A column that lands on a control   | The request that gathers it     | What the handler expects to receive |
+| The key column                     | Every request from the row      | What the handler looks the row up by |
+| A column `lb-show` names           | The hub                         | `null` or `false` for off         |
+| A column a stylesheet selects on   | `[lb-column-value="…"]`         | A fixed token, not wording        |
+
+The page files are not a data layer; they sit on one. The application
+opens its own database and keeps its rules there, or in code its handlers
+share, and the page files stay thin because integrity is not their job.
+
+What two pages share goes beneath them, not between. Two pages showing the
+same data each write the query, or both read a database view. Shared
+wording and shared parm reading go in a helper module the queries import.
+Everything that belongs to one page stays in one place, so a change to a
+page touches that page's files.
+
 ## HTML
 
 Write the page as a fragment. The fragment lands in `<main>`, which
@@ -194,6 +223,9 @@ Every value in `values` is a string, as a control's value is.
 ### refresh and patch
 
 List in `refresh` every query whose whole answer the request changed.
+Never list one only to fill what the request's answer creates, such as the
+picker in a new row: the hub fills that from the query's last answer. See
+[What arrives later](./data-binding.md#what-arrives-later).
 
 Return answers from `run` to state a narrower change than re-running a query
 would. What `run` returns is keyed by query name and laid over the refreshed
@@ -207,8 +239,33 @@ queries:
 | `patch({ drop: [...] })` | These keys are gone; the rest stand         |
 
 Return a patch for a change the request knows the extent of — one row added,
-one row dropped, one row edited — and leave `refresh` empty. Re-run the query
-instead when membership or order changed in a way the request cannot name:
+one row dropped, one row edited — and leave `refresh` empty. A refreshed
+`rows` query sends every row, and the hub places every row again, which moves
+each element and takes focus from the control the user is in.
+
+A change that seems to need a refresh usually has a patch:
+
+- A placeholder row standing in for an empty set or section: drop its key in
+  the patch that adds the first real row, and add it back in the patch that
+  drops the last.
+- A row whose position changes: the rows host places it, as
+  [`lb-table`](./widgets.md#lb-table) does by `data-sort`.
+- A row whose other columns change with the edit: re-read the row and patch
+  it.
+- Rows the database removes with a deleted one: select their keys before the
+  delete and drop them too.
+
+An update or a delete always has a patch, since it names its row by key and
+removing a row never reorders the rest. `createHub` refuses at startup a
+`crud` `rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names
+that same query. An insert may refresh its own query: where a new row goes
+depends on whether its host places it, which the server cannot see.
+
+Each request's `refresh` is its own, and every query in it needs its own
+reason. A list shared by several requests is a warning sign.
+
+Re-run the query when membership or order changed in a way the request
+cannot name:
 
 ```ts
 resetRoster: {

package/docs/what-does-loadbare-extend.md

@@ -0,0 +1,124 @@
+# What Does Loadbare Extend?
+
+> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
+> 2026-09-27 against `@loadbare/app` 0.10.0.
+
+The question: what is `@loadbare/app`'s foundation, the thing it adds to
+rather than replaces, and does the package stand on that foundation the way
+`@loadbare/db` stands on Postgres?
+
+The short answer: the browser half of `@loadbare/app` is honestly "HTML+", in
+the same way `@loadbare/db` is "Postgres+".  The package as a whole is not.
+The framing that covers all of it, and ties it to db, is relational rather
+than HTML.
+
+## The precise reading
+
+### Where "extension to HTML" is literally true
+
+- **It uses the platform's own extension point.**  Custom elements are how
+  HTML is meant to be extended.  The whole browser runtime is one custom
+  element, `<lb-hub>`.  Custom elements are also the only way Loadbare lets an
+  application split up markup or ship behaviour.  There are no components, no
+  JSX, and no expressions evaluated at run time.
+- **The attributes copy HTML's own ideas.**  [Theory](./theory.md#data-binding)
+  already sets this out in a table:
+  - `lb-column` works like `name`.
+  - `lb-query` works like `<form>` or `<select>`, a container of records.
+  - `lb-show` works like `hidden`.
+  - `lb-key-value` works like an `<option>`'s `value` sitting apart from its
+    text.
+- **HTML decides behaviour wherever it already has an opinion.**  Commits
+  follow HTML's events: a form on submit, a control on change, anything else
+  on click.  Gathering follows the form owner, including `form="…"`.  Resets
+  go through `formResetCallback`.  Busy state uses `aria-busy`.  The unknown
+  page is a real `<dialog>`, and links are real `<a href>`.
+- **What ships is plain HTML.**  It can be read in view-source, it uses light
+  DOM, and CSS is left untouched.  A page that shows no data is just an HTML
+  file.
+- **There is historical precedent.**  IE4's `datasrc`/`datafld` really was
+  data binding added to HTML, and [Prior art](./prior-art.md) finds its
+  vocabulary maps almost one to one onto Loadbare's.
+
+### Where it is inaccurate or strained
+
+- **The attributes don't conform to the spec.**  HTML sets aside `data-*` for
+  author attributes, and a validator will flag `lb-*`.  htmx and Alpine have
+  the same problem, so it's defensible.  But a literal claim of "extension to
+  HTML" is only half true: Loadbare uses one of the sanctioned extension
+  points (custom elements) fully and skips the other (`data-*`).
+- **Build-time expansion is a preprocessor.**  `exp-` parameters and `{{…}}`
+  are a small template language that runs before HTML exists.  The output is
+  HTML; the source a developer writes is not quite HTML.
+- **Navigation overrides HTML's model on purpose.**  HTML's model is one
+  document per URL.  Loadbare ships every page as a `<template>` in one
+  document and answers every route with `app.html`, with no 404.  Keeping the
+  address bar truthful softens this, but it is still a replacement.
+- **The wire is JSON, not hypermedia.**  In the ecosystem, "extends HTML"
+  usually means htmx's argument that HTML is unfinished hypertext.  Loadbare
+  rejects that model after the first load.  Calling it an HTML extension
+  invites exactly the comparison [Theory](./theory.md) spends paragraphs
+  getting out of.
+- **Half of what a developer writes isn't HTML.**  `queries.ts` and
+  `requests.ts`, with `row`/`rows`/`patch`, crud entries and refresh lists,
+  have no HTML counterpart at all.
+
+## The db comparison
+
+db earns "Postgres+" because it passes four tests:
+
+1. What it builds is plain Postgres, inspectable with psql.
+2. Its vocabulary extends Postgres's own concepts: the foreign key becomes the
+   channel for values flowing down and aggregates flowing up.
+3. A developer can drop to plain SQL anywhere.
+4. Postgres does the heavy lifting.
+
+The browser half of app passes all four:
+
+1. The output is plain HTML.
+2. The vocabulary extends `name`, `form` and `hidden`.
+3. Any HTML works, and a custom element is still just a custom element.
+4. The platform does the work: `cloneNode` of templates, the selector engine,
+   form owners, `showModal`, the History API.
+
+The rule behind it is the same as db's: **defer where the foundation has an
+answer, and add only where it is silent.**  HTML is silent about data, and
+that's where the seven attributes live.
+
+The difference is that db never overrides Postgres.  It adds to Postgres and
+replaces the application's logic layer.  app overrides HTML twice, in
+navigation and on the wire, both for the 300ms budget.  Those are deliberate
+departures, not add-ons.
+
+## How it feels
+
+- **Writing a page** feels like writing HTML: forms and tables with a few
+  attributes, much like data-bound HTML in 1999 without the ActiveX.
+- **Writing a widget** feels like writing web components.
+- **Writing `requests.ts`** feels like neither.  A nested declaration such as
+  `crud.invoiceLines.rowDelete.{run, refresh}` feels like a framework's
+  configuration map.  db has no equivalent seam, because its DSL reads as DDL
+  all the way down.  That file is where the "HTML+" feel breaks.
+
+## A better framing
+
+The idea that runs through every layer of app is not HTML.  It is the
+**row**: query, row, rows, column and key.  That's where the scope decision in
+[Theory](./theory.md#data-binding) lands, and it's what the protocol carries.
+HTML is the surface, and relations are the substance.
+
+Framed that way, the two packages form one story rather than two:
+
+- **db** is the relational model with derived values, built on Postgres.
+- **app** is the relational model shown and edited on screen, with HTML as its
+  surface.
+- **The row** is the only thing that crosses between them.
+
+So "Relational+ from end to end, with Postgres at one end and HTML at the
+other" is accurate everywhere.  "HTML+" is accurate only for page and widget
+authoring.  It also explains the server half: `queries.ts` and `requests.ts`
+aren't HTML because they're the relational half of the contract.
+
+"HTML+" still works as a description of how page authoring feels.  It fails
+as a statement of what the package is, and it pulls readers toward the
+hypermedia comparison Loadbare would rather avoid.

package/package.json

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