@loadbare/app 0.10.0 → 0.11.0

package/docs/TECHREF-1.0.md

@@ -109,6 +109,13 @@ But the allowed values may depend on other values in the row.
 - **Land the remaining validations.** One `lb-hub` and one empty `<main>`.
   Recommend landing these now, because refusing markup that used to build is
   the kind of change 1.0 gives up.
+- **Decide whether the build validates HTML.** A page can be well formed and
+  still break HTML's rules for what an element may hold, such as a `<div>`
+  inside a `<p>`.  The parser rearranges it silently, the same way at build
+  time and in the browser, so nothing reports it.  Checking those rules is a
+  validator's job, and html-validate is one the builder could run on the
+  source or on the expanded output.  Deciding it after 1.0 is free if it
+  lands as an opt-in, and it may need a configuration key.
 - **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.
 
@@ -251,6 +258,12 @@ A custom element with no element file is left alone.  A custom element
 with neither an element file nor a `.browser.ts` script is a build error, as
 stated in [Custom elements](#custom-elements).
 
+Each file is parsed on its own, and expansion joins them through the DOM,
+which applies none of HTML's rules for what an element may hold.  The browser
+reads the shipped text by those rules, so a join it would rearrange, such as
+a definition's `<dialog>` inside a page's `<p>`, is a build error naming the
+file, the custom element and the path to what would move.
+
 #### Build time parameters
 
 A build time parameter is supplied as an attribute on a custom element,
@@ -418,6 +431,7 @@ query.
 | -------------------- | -------------------------------- |
 | `lb-column-value`    | The value it set                 |
 | `lb-key-value`       | The row's key                    |
+| `lb-row-live`        | Nothing; it marks a live row     |
 | `lb-query-row-count` | The number of live rows it holds |
 
 The markup names a query and the columns it shows.  The kind and the key are
@@ -425,7 +439,8 @@ the server's, and the markup states neither.
 
 The row template is the first `<template>` among the descendants of an
 element with `lb-query`, outside any nested `lb-query`.  A live row is an
-element the hub cloned from a row template for one row.
+element the hub cloned from a row template for one row, and carries
+`lb-row-live`.
 
 | Kind   | Row template | The hub                             |
 | ------ | ------------ | ----------------------------------- |
@@ -498,6 +513,13 @@ refresh, and does not need to.
 
 The hub matches each row to a live row by its key.  It stamps
 `lb-key-value` on each live row, and on an element a `row` lands on itself.
+It stamps `lb-row-live` on each live row and nowhere else, so a `row`
+landed inside another query, such as a total in a table's foot, is not one
+of that query's rows.  A stylesheet or a custom element selects live rows
+with `[lb-row-live]`, and never with `[lb-key-value]`.
+
+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.
 
 All rows decide membership and order: every row is placed in the order
 given, and a live row whose key did not arrive is removed.  A patch touches
@@ -1390,9 +1412,33 @@ class NoteField extends HTMLElement {
 }
 ```
 
+A control that is not yet upgraded when its column lands receives
+`lb-column-value` alone, since the hub sets `value` only on a control.  That
+happens to an element the builder shipped absent, and to one whose
+definition loads after the hub lands.  A control takes the stamp up the
+first time it connects, and never again.
+
 A custom element that is not a control receives `lb-column-value` and
 renders it; its content is never replaced.
 
+### Lifecycle
+
+| The hub                                  | A custom element sees                        |
+| ---------------------------------------- | -------------------------------------------- |
+| Shows a page                             | `constructor`, `connectedCallback`           |
+| Creates a live row, before placing it    | `constructor`                                |
+| Places a live row the first time         | `connectedCallback`                          |
+| Places it again, 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 shipped absent       | `constructor`, `connectedCallback`           |
+
+A listener on the element itself goes in the constructor, which reads no
+attribute and no child.  A child is looked up when it is needed.
+`connectedCallback` runs on every move and is written to run again; work
+done once per instance goes behind a flag.
+
 ### Row hooks
 
 | Method                          | Implemented By | The hub calls it                                   |
@@ -1505,6 +1551,7 @@ it may define tomorrow.
 | `lb-exp-template` | Developer     | An element file, and a `<template>` | [Slots and templates](#slots-and-templates)   |
 | `lb-column-value` | Hub           | Every element set from a column     | [How a column lands](#how-a-column-lands)     |
 | `lb-key-value`    | Hub           | A live row, and an element a `row` lands on | [Rows](#rows)                         |
+| `lb-row-live`     | Hub           | A live row                          | [Rows](#rows)                                 |
 | `lb-query-row-count` | Hub        | An element with a row template      | [Rows](#rows)                                 |
 | `lb-request-pending` | Hub        | The element that issued a request   | [Request state](#request-state)               |
 | `lb-request-error`   | Hub        | The element that issued a request   | [Request state](#request-state)               |
@@ -1566,6 +1613,8 @@ imports them rather than writing a string.
 | `ATTR_SHOW`               | `lb-show`                               |
 | `ATTR_COLUMN_VALUE`       | `lb-column-value`                       |
 | `ATTR_KEY_VALUE`          | `lb-key-value`                          |
+| `ATTR_ROW_LIVE`           | `lb-row-live`                           |
+| `LIVE_ROW`                | `[lb-row-live]`, the selector for a live row |
 | `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
 | `ATTR_REQUEST`            | `lb-request`                            |
 | `ATTR_REQUEST_PENDING`    | `lb-request-pending`                    |

package/docs/comparison.md

@@ -133,7 +133,7 @@ observable, and no client cache of query results.
 - A value that has landed exists in the DOM: as `textContent` or `value`, and
   as the `lb-column-value` stamp.
 - The rows of a `rows` query exist as the live rows the hub cloned, each
-  stamped with `lb-key-value`.
+  stamped with `lb-row-live` and `lb-key-value`.
 - The URL is a row too: the hub serves the query `lb-url`, whose columns are
   the path, the page label and the query parms.
 - An element hidden by `lb-show` exists inside a `<template>` standing where
@@ -187,7 +187,7 @@ At run time the hub performs a closed set of operations:
 | A value for another native element | Set `textContent`, and stamp `lb-column-value`                     |
 | A value for a custom element that is not a control | Stamp `lb-column-value`                            |
 | A `row` with no row template | Land it on the element itself, stamp `lb-key-value`                      |
-| A new key through a row template | Clone the row template, stamp `lb-key-value`, fill it, insert it     |
+| A new key through a row template | Clone the row template, stamp `lb-row-live` and `lb-key-value`, fill it, insert it |
 | All rows                   | Place every row in the order given, remove rows whose keys did not arrive  |
 | A patch                    | Upsert the rows named, remove the keys named, leave other rows in place    |
 | After rows land            | Stamp `lb-query-row-count`                                                 |
@@ -628,7 +628,7 @@ Nothing is scoped, renamed, added or removed.
 - Light DOM means every selector reaches every element, in the chrome and in
   widgets.
 - The hub stamps attributes a stylesheet can select on: `lb-column-value`,
-  `lb-key-value`, `lb-request-pending`, `lb-request-error`,
+  `lb-key-value`, `lb-row-live`, `lb-request-pending`, `lb-request-error`,
   `lb-query-row-count`.  An empty `rows` query is styled with
   `[lb-query-row-count="0"]`.
 
@@ -685,6 +685,27 @@ A page's server half:
 A query's `run` is `(ctx) => Row` or `(ctx) => Row[]`.  An answer whose
 shape disagrees with its declaration is dropped with a warning.
 
+A page's queries are that page's view model, computed on the server: a
+backend-for-frontend scoped to one page, whose answers are the values the
+page shows.
+
+|                  | Data layer (repository, ORM, API) | Backend-for-frontend | Loadbare/app page files |
+|------------------|-----------------------------------|----------------------|-------------------------|
+| Serves           | Any consumer                      | One client application | One page              |
+| Shaped by        | Entities                          | A client's screens   | One page's elements     |
+| Answers with     | Domain objects, independent of any UI | Data the client still turns into a view | Values as the page shows them, formatted and worded |
+| Client-side work | Mapping, state, view models, components | View models, components | None: the hub lands each column on the element that names it |
+| Keeps the rules  | Yes, in code                      | Usually not          | No: the application keeps them beneath, in its database or in code its handlers share |
+| Reused by        | Many screens                      | One application's screens | No other page      |
+
+A typical stack runs database, ORM or repository, service, API contract,
+client store, view model, component and template.  A Loadbare/app page keeps
+three places: the database with the application's rules, the page files that
+say what one page asks and answers, and the markup that says where each
+answer goes.  Reuse does not happen through a layer.  Two pages showing the
+same data repeat a query's shape or share a database view, and shared
+wording goes in a helper module.
+
 The data channel carries no CSRF token.  Where an options argument for
 hooks, transaction wrapping, error handling and CSRF would go is an open
 blocker.  Serving the static files from a separate origin is a roadmap item.
@@ -761,7 +782,7 @@ TECHREF-1.0 lists every name Loadbare/app owns in one cross-reference.
 | Owned                               | Count | Names                                                         |
 |-------------------------------------|-------|---------------------------------------------------------------|
 | `lb-*` attributes a developer writes | 7    | `lb-query`, `lb-column`, `lb-show`, `lb-request`, `lb-url-link`, `lb-url-push`, `lb-url-unknown` |
-| `lb-*` stamps                       | 7     | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
+| `lb-*` stamps                       | 8     | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
 | `lb-*` build-time attributes        | 2     | `lb-exp-slot`, `lb-exp-template`                              |
 | Requests Loadbare provides          | 3     | `lb-row-insert`, `lb-row-update`, `lb-row-delete`             |
 | `lb*` methods on custom elements    | 2     | `lbPlaceRow`, `lbRowsLanded`                                  |

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,6 +260,8 @@ 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`   |
@@ -244,6 +278,46 @@ 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).
 
+### 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 +327,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 +376,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 +422,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
 
@@ -401,7 +488,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 +498,11 @@ 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 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.
 

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

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.11.0",
   "type": "module",
   "files": [
     "dist",

package/skills/loadbare-app/SKILL.md

@@ -219,8 +219,14 @@ for rows added or edited, `patch({ drop })` for keys removed, with
 `refresh: []`.  List a query in `refresh` only when its membership or order
 changed in a way the handler cannot name.
 
-**Format values in the query.**  The hub does no type conversion.  What a
-number, date or null looks like is decided on the server.
+**A page's queries are its view model, not a data layer.**  Each answers
+one page's elements in the form they show: formatted dates and amounts, and
+the words a reader sees, such as "12 postings".  The hub does no type
+conversion, so what a number, date or null looks like is decided on the
+server.  A value the page reads back stays data: a column on a control, the
+key, an `lb-show` condition, a value a stylesheet selects on.  What pages
+share goes beneath them, in a database view or a helper module, never in a
+layer between the page and its queries.
 
 **A URL's path names a page, never a resource.**  Do not design
 `/accounts/42`.  A row is addressed by `query` and `key`, taken from where
@@ -279,6 +285,13 @@ element (`static formAssociated = true`) with a `value` property that fires
 on `change`.  Any other custom element keeps its content and receives the
 column as its `lb-column-value` attribute.
 
+**A custom element connects many times.**  It is moved, never rebuilt: the
+hub places every live row again on each set of all rows, and parks an
+`lb-show` element in a template while it is off, so `connectedCallback` runs
+on every move.  Listen on the element itself in the constructor, look a
+child up when it is needed, and in a control take up `lb-column-value` once,
+on first connect, since a value can land before the element upgrades.
+
 **Name a custom element script `<tag>.browser.ts`.**  A plain `<tag>.ts`
 stays on the server and the tag goes unregistered.
 
@@ -296,6 +309,13 @@ A custom element is `<tag>.html`, `<tag>.browser.ts`, or both, and a tag
 with neither is a build error.  The HTML is expanded at build time into the
 tag's children; the class is an ordinary custom element with no base class.
 
+Place a custom element where HTML allows what its definition holds.  One
+whose definition has a `<div>` or a `<dialog>` cannot sit inside a `<p>`, and
+the build refuses it; see
+[Where a custom element can go](references/custom-elements.md#where-a-custom-element-can-go).
+Never write one inside `<select>`, `<option>` or `<textarea>`, where the
+parser loses the tag before the build can report it.
+
 Reach for one only when plain HTML cannot do the job.  A set of rows, a form
 and a condition need none.  A custom element exists to be a control of its
 own, or to place and scaffold rows through the two hooks the hub calls,
@@ -322,10 +342,12 @@ with the package, so no network is needed.
 - [`references/data-binding.md`](references/data-binding.md) — landing,
   gathering, requests, conditions and request state.  Start here for
   anything in a page.
-- [`references/page-files.md`](references/page-files.md) — queries,
-  `onPageEnter`, handlers, `crud`, refresh and patch, and `url()`.
+- [`references/page-files.md`](references/page-files.md) — what page
+  files are, queries, `onPageEnter`, handlers, `crud`, refresh and patch,
+  and `url()`.
 - [`references/custom-elements.md`](references/custom-elements.md) —
-  expansion, parameters, slots, destinations, and custom element code.
+  expansion, parameters, slots, destinations, and custom element code and
+  when it runs.
 - [`references/chrome.md`](references/chrome.md) — the chrome, and the URL
   as the query `lb-url`.
 - [`references/server.md`](references/server.md) — the Express server and