@loadbare/app 0.7.2 → 0.7.4

package/docs/comparison.md

@@ -0,0 +1,1123 @@
+# Loadbare/app and current front-end frameworks
+
+> LLM-authored, not yet revised by a person.  Drafted by Claude on
+> 2026-09-16 against the working tree of `@loadbare/app` 0.7.3, which
+> includes `lb-show`.  Statements about other frameworks are from general
+> knowledge of those projects as of 2026 and carry no per-claim sources.
+
+This document states how `@loadbare/app` differs from the frameworks and
+libraries most used for front-end development today.  It repeats material
+from [Theory](./theory.md), [TECHREF-1.0](./TECHREF-1.0.md),
+[Prior art](./prior-art.md) and
+[Assessing the accidental complexity claim](./analysis-accidental-complexity.md)
+so that it can be read on its own.  Where this document and
+[Theory](./theory.md) disagree, Theory is authoritative.
+
+Loadbare/app has not reached 1.0.  The [Blockers](./TECHREF-1.0.md#blockers)
+section of TECHREF-1.0 lists open decisions, and five of its sections are
+marked `UNEDITED`.  Anything below that describes Loadbare/app describes the
+code as it stands.
+
+## Contents
+
+1. [Summary](#summary)
+2. [The comparison set](#the-comparison-set)
+3. [Stated goals and scope](#stated-goals-and-scope)
+4. [Where state lives](#where-state-lives)
+5. [Rendering](#rendering)
+6. [Templates and markup](#templates-and-markup)
+7. [Components and widgets](#components-and-widgets)
+8. [Data on the wire](#data-on-the-wire)
+9. [Mutations, forms and request state](#mutations-forms-and-request-state)
+10. [Routing and navigation](#routing-and-navigation)
+11. [Build, tooling and checking](#build-tooling-and-checking)
+12. [CSS](#css)
+13. [The server](#the-server)
+14. [Performance profile](#performance-profile)
+15. [Surface area](#surface-area)
+16. [Accessibility](#accessibility)
+17. [Testing](#testing)
+18. [Release history and churn](#release-history-and-churn)
+19. [What Loadbare/app does not do](#what-loadbareapp-does-not-do)
+20. [Requirements and fit](#requirements-and-fit)
+21. [Appendix A: Matrix](#appendix-a-matrix)
+22. [Appendix B: One page, three ways](#appendix-b-one-page-three-ways)
+23. [Appendix C: Glossary of nearest equivalents](#appendix-c-glossary-of-nearest-equivalents)
+
+## Summary
+
+Loadbare/app is a framework for server-bound database applications.  The
+browser receives one HTML document containing every page as a `<template>`,
+one script and one stylesheet.  After that, only JSON rows cross the wire.
+HTML attributes bind elements to named server queries, and one attribute,
+`lb-action`, turns a click or a submit into a request.  The server answers
+every request with rows, sets of rows, or patches to sets of rows, and the
+browser-side runtime, called the hub, writes those values into the elements
+bound to them.
+
+Compared with the client component frameworks (React, Vue, Angular, Svelte,
+Solid), Loadbare/app has no component tree rendered at run time, no
+client-side state, no virtual DOM or reactivity system, and no runtime
+template expressions.
+
+Compared with the server-integrated meta-frameworks (Next.js, Nuxt,
+SvelteKit, React Router 7, Astro), Loadbare/app has no server rendering and
+no hydration, ships no server of its own, and has no route parameters.
+
+Compared with the hypermedia libraries (htmx, Hotwire Turbo, Unpoly),
+Loadbare/app sends JSON rather than HTML after the first load, requires a
+build step, and requires no endpoint design.
+
+Compared with server-driven stateful UI (Phoenix LiveView, Laravel Livewire,
+Blazor Server), Loadbare/app keeps no per-client process or component state
+on the server, and uses ordinary HTTP requests rather than a persistent
+connection.
+
+| Group                    | Rendering happens     | State lives                  | After first load, the wire carries |
+|--------------------------|-----------------------|------------------------------|------------------------------------|
+| Loadbare/app             | Build time, once      | Server database, and the DOM | JSON rows                          |
+| Client component         | Browser, on change    | Browser memory               | JSON (application-designed)        |
+| Meta-frameworks          | Server, then browser  | Server and browser memory    | JSON, RSC payloads, or HTML        |
+| Hypermedia               | Server, per request   | Server, and the DOM          | HTML                               |
+| Server-driven stateful   | Server, per event     | Server memory per client     | DOM diffs or HTML                  |
+
+## The comparison set
+
+| Group                    | Members                                          |
+|--------------------------|--------------------------------------------------|
+| Client component         | React, Vue, Angular, Svelte, Solid               |
+| Meta-frameworks          | Next.js, Nuxt, SvelteKit, React Router 7, Astro  |
+| Hypermedia               | htmx, Hotwire (Turbo and Stimulus), Unpoly       |
+| Server-driven stateful   | Phoenix LiveView, Laravel Livewire, Blazor Server|
+| Sprinkles and components | Alpine.js, Lit                                   |
+
+React Router 7 is the continuation of Remix.  TanStack Query appears below
+where client-side server-state caching is discussed, because React
+applications commonly pair it with a data API.
+
+## Stated goals and scope
+
+Theory states two goals, in order.
+
+1. Performance.  A full round trip, from user action through durable
+   persistence to final paint, should complete in a median of 300ms.
+   Assuming roughly 200ms of wire time leaves 100ms for the database, the
+   application server and the browser together, so the framework's own
+   processing time in the browser and on the server should approach zero.
+2. Developer efficiency, defined as reducing accidental complexity (Brooks):
+   work demanded by the tools rather than by the problem.
+
+The scope follows from a hypothesis stated in Theory: in a data-oriented
+application, the set of DOM changes needed is closed and knowable, so a
+framework optimized for that set does not need the machinery required to
+support arbitrary DOM updates.
+
+Loadbare/app restricts itself to applications whose data can be sent as rows
+and sets of rows.  Theory states that the claims about accidental complexity
+are most likely to hold "when the existing stack can support an application
+that wants data to be rows and tables, or easily mapped into them and out of
+them, and the desired affordances can be easily mapped to the standard set of
+operations against that data."
+
+Each of the other projects in the comparison set presents itself as a
+general-purpose tool for building web user interfaces, and none restricts the
+shape of the data an application works with.
+
+## Where state lives
+
+### Loadbare/app
+
+The hub holds no application data.  There is no store, no signal, no
+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-value` attribute.
+- A list exists as the DOM rows the hub cloned, each stamped with
+  `lb-key-value`.
+- An element hidden by `lb-show` exists inside a `<template>` standing where
+  it stood.
+- The hub keeps two pieces of state of its own: the name of the current page,
+  and, until an insert completes, a record of which controls it read.
+
+The server is the source of truth for everything else, including view state.
+A query takes no argument from the browser; its only input is `ctx`, which
+the application builds from the Express request.  Which record a page shows,
+or which step of a wizard is current, is held on the server where `ctx`
+reaches it.  A reload runs the page's queries again and shows the same state.
+
+A URL names a page and nothing finer.  Whether a page URL may carry
+parameters is an open blocker in TECHREF-1.0.
+
+### Elsewhere
+
+| Project           | Where application state is kept                                                         |
+|-------------------|-----------------------------------------------------------------------------------------|
+| React             | Component state (`useState`, `useReducer`) in the component tree; context; external stores such as Redux or Zustand; server-state caches such as TanStack Query or SWR |
+| Vue               | Reactive proxies (`ref`, `reactive`); Pinia stores                                      |
+| Angular           | Signals, services provided through dependency injection, RxJS observables               |
+| Svelte            | Runes (`$state`, `$derived`); stores                                                    |
+| Solid             | Signals and stores                                                                      |
+| Next.js           | Server Components read data on the server; Client Components hold React state; the client router caches RSC payloads |
+| React Router 7    | Loader data held by the router in the browser; component state                          |
+| SvelteKit, Nuxt   | Load function or `useFetch` data held in the browser; component state                   |
+| htmx, Turbo       | The server, and the HTML currently in the DOM.  Turbo keeps a snapshot cache of visited pages for back navigation |
+| Phoenix LiveView  | Socket assigns in a server process per connected client                                 |
+| Livewire          | Component properties serialized into a snapshot in the page and sent back with each request |
+| Blazor Server     | Component state in server memory, per circuit                                           |
+| Alpine.js         | Reactive objects declared with `x-data`                                                 |
+
+## Rendering
+
+### Loadbare/app
+
+HTML is produced once, by the builder.  Widget expansion, build-time
+parameters, slots and named templates are resolved at build time, and every
+page is placed in the one document as `<template lb-page="name">`.  The
+browser parses that document once.
+
+At run time the hub performs a closed set of operations:
+
+| Trigger                    | Operation                                                                  |
+|----------------------------|----------------------------------------------------------------------------|
+| Navigation                 | Clone the page's `<template>` into `<main>`                                |
+| A value for a native element | Set `textContent`, and set `lb-value`                                    |
+| A value for a form control | Set `value`, and set `lb-value`                                            |
+| A value for a custom element | Set `lb-value`                                                           |
+| A new key in a list        | Clone the row template, stamp `lb-key-value`, fill it, insert it           |
+| A whole list               | 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 any list result      | Stamp `lb-row-count`                                                       |
+| An `lb-show` column        | Move the element into, or out of, a `<template lb-show>`                   |
+| A request starts or ends   | Set or remove `lb-pending` and `aria-busy`; set `lb-error` on failure      |
+| An insert succeeds         | Reset the controls it gathered to their defaults                           |
+
+The hub finds targets with `querySelectorAll` on the attributes written in
+the HTML.  No tree is compared with a previous tree.  A response names what
+changed, so the hub does not determine what changed.  Between interactions
+the hub runs no timers, observers or polling loops.
+
+There is no server-side rendering and no hydration.  The server returns the
+values its queries return, serialized as JSON.
+
+### Elsewhere
+
+| Project          | How the DOM is produced and updated                                                   |
+|------------------|---------------------------------------------------------------------------------------|
+| React            | Components re-run on state change and return an element tree, which is reconciled against the previous tree; keys identify list items |
+| Vue              | Templates compile to render functions producing a virtual DOM; reactivity tracks which components depend on which state |
+| Angular          | Templates compile to instructions; change detection checks bindings, and signals mark views that need updating |
+| Svelte           | The compiler emits code that updates the DOM nodes bound to changed state             |
+| Solid            | JSX compiles to DOM creation code; components run once; signals update bound nodes   |
+| Next.js, Nuxt, SvelteKit, React Router 7 | HTML is rendered on the server per request or at build time, then hydrated in the browser (in Next.js, the Client Components), after which the client framework renders |
+| Astro            | HTML rendered at build or request time; interactive islands are hydrated per `client:*` directive |
+| htmx             | The server renders HTML fragments per request; htmx swaps them into a target          |
+| Turbo            | The server renders pages; Turbo replaces the body, a `<turbo-frame>`, or applies Turbo Stream actions; page refreshes can morph |
+| Phoenix LiveView | The server re-renders changed parts of a template and sends diffs over a WebSocket; the client patches the DOM |
+| Livewire         | The server re-renders component HTML; the client morphs the DOM                       |
+| Blazor Server    | The server renders the component tree, computes a diff, and sends it over SignalR     |
+| Alpine.js        | Directives on server-rendered HTML update bound nodes from reactive data              |
+| Lit              | Tagged template literals update the dynamic parts of a template, by default inside a shadow root |
+
+## Templates and markup
+
+### Loadbare/app
+
+The HTML written in `.html` files is the HTML that ships, after expansion.
+Attribute values in the `lb-` namespace are names: a query name, a column
+name, or an action name.  No attribute value is an expression.
+
+There are two kinds of placeholder, and they run at different times.
+
+- Build time.  A widget definition writes `{{name}}` or `{{name|default}}` as
+  a whole attribute value or a whole text node.  The tag supplies it with an
+  `exp-name` attribute.  An unsupplied placeholder with no default drops the
+  attribute.  The value becomes permanent in the shipped HTML.
+- Run time.  Data lands through `lb-cell`, `lb-list` with a keyed
+  `<template>`, and `lb-show`.  There is no run-time interpolation into
+  attribute values or text.
+
+Interpolation inside a longer string, such as `title="Hello {{name}}"`, is
+listed as decided against in the [Roadmap](./roadmap.md#decided-against).
+
+| Task              | Loadbare/app                                  | React (JSX)                          | Vue                                  | Angular                               | Svelte                        | Alpine.js                                  |
+|-------------------|-----------------------------------------------|--------------------------------------|--------------------------------------|---------------------------------------|-------------------------------|--------------------------------------------|
+| Show a value      | `<span lb-cell="name">`                       | `{row.name}`                         | `{{ row.name }}`                     | `{{ row.name }}`                      | `{row.name}`                  | `<span x-text="row.name">`                 |
+| Keyed list        | `<template lb-key="id">` inside `lb-list`     | `rows.map(r => <li key={r.id}>)`     | `<li v-for="r in rows" :key="r.id">` | `@for (r of rows; track r.id)`        | `{#each rows as r (r.id)}`    | `<template x-for="r in rows" :key="r.id">` |
+| Condition         | `lb-show="column"`                            | `{cond && <X />}`                    | `v-if`, `v-show`                     | `@if (cond) { }`                      | `{#if cond}`                  | `x-if`, `x-show`                           |
+| Expression in markup | Not supported                              | Any JavaScript expression            | JavaScript expressions               | Template expressions                  | JavaScript expressions        | JavaScript expressions                     |
+| Build-time constant | `exp-label="Name"` into `{{label}}`          | A prop                               | A prop                               | An input                              | A prop                        | Not applicable                             |
+
+In htmx and Turbo, markup for data is produced by whatever server template
+language the application uses.  LiveView uses HEEx, with `{@value}`
+interpolation, `:for` and `:if`.
+
+### Conditions
+
+`lb-show` names a column.  `null` and `false` are off; every other value is
+on, including the string `"false"`.  An element that is off is moved into a
+`<template lb-show="column">` standing where it stood, and moved back when the
+column turns on.  It is not rendered, focused, clicked, announced or gathered.
+Values keep landing inside the template, so the element returns current.  The
+builder ships every `lb-show` element already inside its template.
+
+| Framework                        | A false branch                                                        | State kept | Updated while hidden |
+|----------------------------------|-----------------------------------------------------------------------|------------|----------------------|
+| Loadbare/app `lb-show`           | Moved into a `<template>` in place                                    | yes        | yes                  |
+| Alpine `<template x-if>`         | Destroyed and removed; recloned on show                               | no         | no                   |
+| Knockout `if`                    | Contents re-rendered on show                                          | no         | no                   |
+| Angular `@if` / `*ngIf`          | View destroyed unless detached and reinserted by hand                 | if detached | no                  |
+| Aurelia `if.bind`                | Removed; views cached and reused by default                           | yes        | not documented       |
+| Vue `v-if` in `<KeepAlive>`      | Detached, not unmounted                                               | yes        | no                   |
+| Lit `cache()`                    | DOM kept in a `DocumentFragment`                                      | yes        | on swap-in           |
+| Polymer `dom-if`                 | `display: none`                                                       | yes        | yes                  |
+| React `<Activity mode="hidden">` | `display: none`, Effects destroyed                                    | yes        | yes, at lower priority |
+
+Sources for the rows other than Loadbare/app are in
+[Prior art](./prior-art.md#conditional-rendering-elsewhere).
+
+A condition that is not data, such as an open menu, has no column.  The
+reference directs it to `<details>`, a stylesheet, or a widget.
+
+## Components and widgets
+
+### Loadbare/app
+
+A widget is a custom element defined by one or two files sharing its tag
+name, found by the builder anywhere in the source tree:
+
+| File                    | Holds                                               |
+|-------------------------|-----------------------------------------------------|
+| `<tag-name>.html`       | Markup the tag expands into, at build time          |
+| `<tag-name>.browser.ts` | A class registered with `customElements.define`     |
+
+A tag with neither file is a build error.  A module named `<tag-name>.ts`
+without `.browser` is not bundled, and the build error names it.
+
+- Light DOM throughout.  Loadbare/app uses no shadow DOM.
+- No base class.  A widget extends `HTMLElement`.
+- No props at run time.  Build-time parameters arrive as `exp-` attributes.
+  Data arrives as the `lb-value` attribute, which the widget observes through
+  `attributeChangedCallback`.  The browser calls that callback for an
+  attribute already present at upgrade, so first render and refresh are one
+  code path.
+- Composition at build time.  `lb-slot` marks where authored content goes;
+  `lb-template` names additional destinations filled by
+  `<template lb-template="name">`.  A definition may use other widgets; a
+  cycle is a build error.
+- A widget sends a request by dispatching a bubbling `lb-request`
+  `CustomEvent`.  The hub adds the scope (`list` or `row`, `key`, `cell`).  An
+  ancestor may stop the event.
+- A list widget may implement `lbPlaceRow(el, row, template)` to decide where
+  a row goes, and `lbRowsLanded()` to build scaffolding such as group
+  headings.  The hub does the cloning, matching, removal and counting.
+- Method names beginning with `lb` on a custom element are reserved.
+
+Widget libraries are npm packages listed in `imports.ts`.  The builder scans
+each listed package for `<tag>.html` and `<tag>.browser.js` files, in the
+directory named by `loadbare.widgets` in its `package.json`, or the whole
+package when that key is absent.  Only tags used in the chrome or a page are
+bundled.  `@loadbare/widgets` ships `lb-input`, `lb-select`, `lb-options`,
+`lb-table`, `lb-picker` and `lb-unknown-page`.
+
+### Using web components and other libraries
+
+The following follow from the builder and hub code.
+
+- A third-party custom element used in markup must have a script or a
+  definition in some origin, or the build fails.  A package that does not name
+  its files `<tag>.browser.js` can be used by writing `<tag>.browser.ts` in the
+  application's own tree that imports the package's module.
+- A `.browser.ts` file is bundled by esbuild and may import any package
+  esbuild resolves.  A custom element may mount another framework's component
+  tree inside itself.
+- The hub does not turn a click on a hyphenated element into a request.  A
+  third-party element carrying `lb-action` sends nothing unless it dispatches
+  `lb-request` itself.
+- A bound value lands on a third-party element as `lb-value`.  The element
+  displays it only if it observes that attribute.
+- Gathering for `lb-row-insert` and `lb-row-update` reads `<input>`, `<select>`
+  and `<textarea>` elements found with `querySelectorAll`, which does not
+  enter a shadow root.
+
+### Elsewhere
+
+| Project     | Unit                               | Inputs                        | Children                          | Style scope                 |
+|-------------|------------------------------------|-------------------------------|-----------------------------------|-----------------------------|
+| React       | Function returning JSX             | Props                         | `children` prop, render props     | None built in               |
+| Vue         | Single-file component (`.vue`)     | Props, emits                  | Default and named slots           | `<style scoped>` available  |
+| Angular     | Class with `@Component` decorator  | Inputs, outputs, signals      | Content projection (`ng-content`) | Emulated encapsulation by default |
+| Svelte      | `.svelte` file                     | `$props()`                    | Snippets                          | Scoped by default           |
+| Solid       | Function returning JSX, run once   | Props                         | `children`                        | None built in               |
+| Lit         | `LitElement` subclass              | Reactive properties, attributes | `<slot>` in shadow DOM          | Shadow DOM by default       |
+| Stimulus    | Controller class attached by `data-controller` | Values, targets  | Server-rendered HTML              | None                        |
+| LiveView    | Function components and LiveComponents | Assigns                   | Slots                             | None built in               |
+
+React 19 added full support for custom elements, including setting
+properties, so web components can be used in React applications directly.
+Component libraries written for one framework (for example MUI for React or
+Vuetify for Vue) are not usable in another without a wrapper.
+
+## Data on the wire
+
+### Loadbare/app
+
+Every request from the hub is `POST /lb?page=<name>` with a JSON body.
+
+- An empty body asks for the page's whole query set.  The server runs the
+  page's `onPageEnter`, then every query the page declares.
+- A body with an `action` runs that action and its refresh set.
+- A request without an action answers 400.  A `run` that throws answers 500.
+
+Every response has one shape: an object keyed by query name.
+
+| Value            | Means                                               |
+|------------------|-----------------------------------------------------|
+| An object        | One row, for a name declared with `row()`           |
+| An array         | The whole set, and its order, for a `list()`        |
+| `{ rows, drop }` | A patch to a `list()`: upsert these, remove these keys |
+
+A cell holds one value.  A set of values is a list of its own.  A row never
+contains rows.  Master-detail is a row and a list answered under two names.
+Many masters with their details is one list of joined rows, grouped for
+display by a widget's `lbPlaceRow`.
+
+The application designs no endpoints, routes or serialization format.  The
+names in the markup are the keys in the page's `.queries.ts` and
+`.requests.ts` files.  The browser can reach only the queries, actions and
+CRUD operations a page declares; any other name answers `{}` and logs a
+server warning.
+
+Values are not converted.  The hub hands each value to the browser as the
+query produced it.  Formatting a date or an amount is done in the query.
+Data types are an open blocker in TECHREF-1.0.
+
+### Elsewhere
+
+| Project           | Data requests after first load                                                  |
+|-------------------|---------------------------------------------------------------------------------|
+| React, Vue, Angular, Svelte, Solid (client only) | Whatever the application designs: REST, GraphQL, tRPC, or other |
+| Next.js           | Server Functions as POST requests identified by a `Next-Action` header; navigations fetch RSC payloads |
+| React Router 7    | Loader data fetched by `.data` requests; actions posted to the route URL        |
+| SvelteKit         | Load data from `__data.json`; form actions posted to `?/actionName`             |
+| Nuxt              | Server routes under `server/api` (Nitro), fetched with `useFetch` or `$fetch`   |
+| htmx              | Any HTTP verb to any URL named in `hx-get`, `hx-post` and related attributes; HTML response |
+| Turbo             | Ordinary page and form requests; HTML responses; Turbo Stream responses        |
+| Phoenix LiveView  | Events and diffs over a WebSocket                                               |
+| Livewire          | POST requests carrying component snapshots and calls                            |
+| Blazor Server     | SignalR messages                                                                |
+
+## Mutations, forms and request state
+
+### Loadbare/app
+
+`lb-action` names what an interaction asks for.  A value beginning with `lb-`
+is one of four reserved operations; any other value is an action the page
+declares.
+
+| `lb-action`      | Written on                                  | Carries                         | Server key under `crud` |
+|------------------|---------------------------------------------|---------------------------------|-------------------------|
+| `lb-row-insert`  | A `<form>`, or a button in a `<tr>`, in a list | `list`, `values`             | `rowInsert`             |
+| `lb-row-update`  | A `<form>` or a button in a live row        | `list`, `key`, `values`         | `rowUpdate`             |
+| `lb-row-delete`  | Anything inside a live row                  | `list`, `key`                   | `rowDelete`             |
+| `lb-cell-change` | A widget wrapping one control               | `list`, `key`, `cell`, `value`  | `cellChange`            |
+| Any other name   | Any element                                 | Scope in effect, and a widget's `value` | Under `actions`  |
+
+- Position comes from the document.  `list` or `row` comes from the nearest
+  ancestor scope, `key` from the nearest live row, `cell` from the element's
+  own `lb-cell`.  The author writes the action and not the position.
+- Values are gathered from the nearest `<form>`, `<tr>` or live row around
+  the element, the way a button submits its form owner.
+- A native element sends on click, a form on submit.  A widget sends its own.
+- A declared action carries no argument list.
+- A single-row scope is read-only for the four operations, because each needs
+  a key and a key exists only on a live row in a list.
+
+On the server, each entry has `run` and `refresh`.  `run` does the work and
+may return results, such as a `patch()`.  `refresh` names queries to run
+again.  What `run` returns is laid over the refreshed results.
+
+The hub stamps the dispatching element:
+
+| Attribute      | Means                                                      |
+|----------------|------------------------------------------------------------|
+| `lb-pending`   | The round trip is in flight; `aria-busy="true"` is set with it |
+| `lb-error`     | The last round trip from this element failed               |
+
+A native button or form performed again while it carries `lb-pending` is
+ignored.  A widget is not held back.  A round trip has a ten-second deadline,
+after which it is aborted and treated as a failure.  `lb-error` records that
+a round trip failed, and carries no message.
+
+After a successful `lb-row-insert`, the hub resets each control it gathered
+to its default, as `form.reset()` does, unless the control was edited during
+the round trip.  A failed insert resets nothing.
+
+The browser displays only values the server returned.  There is no
+optimistic update.  Per-keystroke validation is an open question in the
+roadmap.
+
+### Elsewhere
+
+| Project          | Sending a mutation                                   | Refreshing afterward                                        | Pending state                          | Optimistic update         |
+|------------------|------------------------------------------------------|-------------------------------------------------------------|----------------------------------------|---------------------------|
+| React            | `<form action={fn}>`, event handlers                  | Application code                                            | `useActionState`, `useFormStatus`, `useTransition` | `useOptimistic`  |
+| TanStack Query   | `useMutation`                                         | `invalidateQueries` by query key                            | `isPending`                            | `onMutate`                |
+| Next.js          | Server Functions                                      | `revalidatePath`, `revalidateTag` in the function           | React hooks                            | `useOptimistic`           |
+| React Router 7   | `<Form>`, `useFetcher`, route `action`                | Loaders on the page revalidate by default; `shouldRevalidate` opts out | `useNavigation`, `fetcher.state` | Application code from pending form data |
+| SvelteKit        | Form actions in `+page.server.ts`, `use:enhance`      | `use:enhance` reruns load functions by default; `invalidate` for targeted reruns | Application code in `use:enhance` | Application code |
+| Angular          | Event bindings, `HttpClient`                          | Application code                                            | Application code                       | Application code          |
+| htmx             | `hx-post`, `hx-put`, `hx-delete` on any element       | The HTML response; `hx-swap-oob`; `HX-Trigger` response header | `htmx-request` class, `hx-indicator`, `hx-disabled-elt` | Not built in |
+| Turbo            | Forms; a successful non-GET submission redirects      | Re-render after redirect; Turbo Streams                     | `aria-busy` on the form, `data-turbo-submits-with` | Not built in |
+| Phoenix LiveView | `phx-click`, `phx-submit`, `phx-change`               | Assign changes re-render                                    | `phx-click-loading` and related classes, `phx-disable-with` | `JS` commands |
+| Livewire         | `wire:click`, `wire:submit`, `wire:model`             | Component re-render                                         | `wire:loading`                         | Not built in              |
+
+## Routing and navigation
+
+### Loadbare/app
+
+- A page is `<name>.page.html`, found anywhere under `--src`.  The directory
+  carries no meaning; page names are unique across the application.
+- The path `/members` names the page `members`.  The path `/` names `index`.
+- There are no route parameters, nested routes or per-page layouts.  The
+  chrome, `chrome.html`, is the one document surrounding every page.
+- An anchor carrying `lb-nav-link` navigates inside the application: the hub
+  calls `history.pushState`, clones the page template into `<main>`, then
+  fetches the page's data.  An anchor without the attribute is an ordinary
+  link.  `popstate` navigates back and forward.
+- Navigation fetches no HTML and no code.  Every page's markup is already in
+  the document.
+- The server answers every GET with the same `app.html` and status 200.  A
+  path that names no page is detected in the browser, which opens a
+  `<dialog lb-unknown-page>` if the chrome has one.
+- The hub publishes its own row, `lb-navigation`, with `page-uri` and
+  `page-label` (the text of the matching `lb-nav-link` anchor), bound like
+  any server row.
+- The hub reads `location.pathname` only.  A query string does not reach the
+  server.
+- The application must be served from the origin root.  The hub reaches
+  `/lb`, `/client.js` and `/app.css` by absolute path.
+- The hub does not change `document.title`, move focus, or restore scroll
+  position on navigation.
+
+### Elsewhere
+
+| Project          | Routes declared by                                  | Parameters                    | Layouts                     | Unknown path           |
+|------------------|-----------------------------------------------------|-------------------------------|-----------------------------|------------------------|
+| Next.js (App Router) | Directories under `app/` with `page.tsx`        | `[id]`, `[...slug]` segments  | Nested `layout.tsx`         | `not-found.tsx`, status 404 from the server |
+| Nuxt             | Files under `pages/`                                | `[id]` segments               | `layouts/`, nested routes   | Error page, status 404 |
+| SvelteKit        | Directories under `src/routes/` with `+page.svelte` | `[id]` segments               | Nested `+layout.svelte`     | `+error.svelte`, status 404 |
+| React Router 7   | Route config or file conventions                    | `:id` segments                | Nested routes with `<Outlet>` | Catch-all route      |
+| Angular          | `Routes` array                                      | `:id` segments                | Nested router outlets       | `**` wildcard route    |
+| Vue Router       | Routes array                                        | `:id` segments                | Nested `<RouterView>`       | Catch-all route        |
+| Phoenix LiveView | `live` routes in the router                         | `:id` segments, `handle_params` | Root and app layouts      | Status 404 from the server |
+| htmx, Turbo      | Server routes                                       | Server routes                 | Server templates            | Server status          |
+
+A client-routed single-page application served by a catch-all route also
+answers 200 for an unknown path, as Loadbare/app does.
+
+## Build, tooling and checking
+
+### Loadbare/app
+
+```
+loadbare-app-build [--src src] [--out dist] [--watch] [--minify]
+```
+
+- Four flags.  No configuration file.  An open blocker proposes one.
+- Files are classified by name: `chrome.html`, `*.page.html`,
+  `*.queries.ts`, `*.requests.ts`, `imports.ts`, `*.css`, `<tag>.html`,
+  `<tag>.browser.ts`.
+- Origins are scanned in order: `@loadbare/app` itself (which supplies
+  `lb-hub`), each package in `imports.ts`, then `--src`.  A later origin
+  overrides an earlier one for the same tag.
+- The client bundle is built by esbuild from a generated entry that imports
+  the script of every custom element left in the assembled document.  A
+  widget script whose tag is never used is never imported.
+- Outputs: `app.html`, `client.js`, `app.css` when there is a stylesheet,
+  `pages.ts` when there is page data, and `client-entry.ts`.
+- `--watch` rebuilds on changes to `.html`, `.ts` and `.css` files.  There is
+  no dev server, no hot module replacement and no browser reload.
+- `app.html` is formatted with Prettier and never minified.
+
+Checked at build time, as errors:
+
+- a tag with neither a definition nor a script
+- a module named for a tag without `.browser`
+- two files claiming one tag in one origin
+- a cycle among definitions
+- an `exp-` attribute the definition does not declare, and a placeholder name
+  containing a capital
+- slot and template errors: two slots, two templates of one name, a template
+  naming a missing destination, content in a definition with no slot
+- `lb-cell` outside every scope, `lb-key` on anything but a list's row
+  template, `lb-list` and `lb-row` on one element
+- `lb-show` on a `<template>`, on a row template's root, or with no row
+  around it
+- `lb-unknown-page` on anything but a `<dialog>` inside `<lb-hub>`
+- a `.queries.ts` or `.requests.ts` with no matching page
+
+Checked when the server starts: a query or action name beginning with `lb-`.
+
+Not checked at build time: that an `lb-list` or `lb-row` name matches a
+declared query, that an `lb-action` matches a declared action or CRUD entry,
+that an `lb-` attribute is one Loadbare defines, that the chrome contains one
+`<lb-hub>` and one empty `<main>`.  The first two are a roadmap item; the
+last two are listed under the builder blockers.  A language server is a
+roadmap item.
+
+### Elsewhere
+
+| Project          | Build and dev tooling                                   | Template type checking                        | Editor tooling                  |
+|------------------|---------------------------------------------------------|-----------------------------------------------|---------------------------------|
+| React            | Chosen by the application or its framework; Create React App was deprecated in February 2025 | TypeScript checks JSX | TypeScript language service |
+| Next.js          | Turbopack or webpack; dev server with Fast Refresh      | TypeScript; typed routes                      | TypeScript plugin               |
+| Vue, Nuxt        | Vite; dev server with HMR                               | `vue-tsc`                                     | Vue language tools (Volar)      |
+| Angular          | Angular CLI (esbuild, Vite dev server)                  | Strict template type checking in the compiler | Angular Language Service        |
+| Svelte, SvelteKit| Vite; dev server with HMR                               | `svelte-check`                                | Svelte language server          |
+| Solid            | Vite                                                    | TypeScript checks JSX                         | TypeScript language service     |
+| React Router 7   | Vite                                                    | TypeScript; generated route types             | TypeScript language service     |
+| Astro            | Vite                                                    | `astro check`                                 | Astro language tools            |
+| htmx, Alpine.js  | None required; a script tag                             | None                                          | Community extensions            |
+| Hotwire (Rails)  | Import maps or a JavaScript bundler                     | None for Turbo attributes                     | Community extensions            |
+| Phoenix          | esbuild and Tailwind through Mix                        | Compile-time warnings for declared component attributes | Elixir language server |
+
+## CSS
+
+### Loadbare/app
+
+The builder concatenates every `.css` file from every origin into `app.css`.
+Nothing is scoped, renamed, added or removed.
+
+- Order: each package in `imports.ts`, in first-mention order, then the
+  application's own `--src`.  Within an origin, files sort by filename, with
+  the full path breaking a tie.  Directories do not affect the order.
+- Stylesheets are paired with nothing.  Every stylesheet in every listed
+  package ships whether or not its widgets are used.  Pairing a stylesheet
+  with a tag is a roadmap item.
+- Light DOM means every selector reaches every element, in the chrome and in
+  widgets.
+- The hub stamps attributes a stylesheet can select on: `lb-value`,
+  `lb-pending`, `lb-error`, `lb-row-count`.  An empty list is styled with
+  `[lb-row-count="0"]`.
+
+### Elsewhere
+
+| Project     | Built-in scoping                                                          |
+|-------------|---------------------------------------------------------------------------|
+| React       | None; applications choose CSS Modules, CSS-in-JS, Tailwind, or global CSS |
+| Next.js     | CSS Modules, global CSS, Sass and Tailwind supported by the build         |
+| Vue         | `<style scoped>` adds a data attribute per component; CSS Modules         |
+| Angular     | Emulated encapsulation adds attributes per component by default; shadow DOM and none available |
+| Svelte      | Component styles scoped by a generated class by default                   |
+| Lit         | Shadow DOM scoping by default                                             |
+| htmx, Turbo, Alpine.js | None                                                           |
+| Phoenix     | None built in; Tailwind configured by default in new projects             |
+
+## The server
+
+### Loadbare/app
+
+Loadbare/app ships no server.  It ships:
+
+- `createHub(pages)`, an engine with no HTTP code, in `@loadbare/app/server`
+- `hubRoutes(hub, contextFor)`, an Express 5 router, in
+  `@loadbare/app/express`.  Express is an optional peer dependency.
+- `pages.ts`, generated by the builder, which imports every page's queries
+  and requests and exports `hub`
+
+The application's server handles four things:
+
+```ts
+app.use(hubRoutes(hub, contextFor));
+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.sendFile(path.join(DIST, "app.html")));
+```
+
+These lines do not change as pages are added.
+
+`contextFor(req)` returns `ctx`, which Loadbare passes to every query and
+request and never reads.  Its type is declared by the application through
+TypeScript declaration merging on `HubContext`.  Authentication, sessions,
+logging, database access, and any ORM or business-logic layer are the
+application's, placed in Express middleware and in `ctx`.
+
+A page's server half:
+
+| File                 | Exports    | Contents                                                     |
+|----------------------|------------|--------------------------------------------------------------|
+| `<name>.queries.ts`  | `queries`  | Named queries, each built with `row()` or `list()`           |
+| `<name>.requests.ts` | `requests` | `onPageEnter`, `actions` by name, `crud` by list name        |
+
+A query's signature is `(ctx) => Row` or `(ctx) => Row[]`.  An answer whose
+shape disagrees with its declaration is dropped with a warning.
+
+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.
+
+### Elsewhere
+
+| Project          | Server                                                                             |
+|------------------|------------------------------------------------------------------------------------|
+| React, Vue, Angular, Svelte, Solid (client only) | None; the application supplies an API server        |
+| Next.js          | Next.js server, or adapters for hosting platforms; Middleware or Proxy; Route Handlers |
+| Nuxt             | Nitro server with presets for hosting platforms                                    |
+| SvelteKit        | Adapters (Node, static, platform-specific); hooks in `hooks.server.ts`             |
+| React Router 7   | Request handler with adapters for Node, Express and platforms                      |
+| Astro            | Static output, or server adapters                                                  |
+| htmx             | Any server that returns HTML                                                       |
+| Hotwire          | Any server; integrated with Rails                                                  |
+| Phoenix LiveView | Phoenix                                                                            |
+| Livewire         | Laravel                                                                            |
+| Blazor Server    | ASP.NET Core                                                                       |
+
+## Performance profile
+
+### Loadbare/app
+
+First load of any path:
+
+| Request                  | Returns                                    |
+|--------------------------|--------------------------------------------|
+| `GET /<path>`            | `app.html`: the chrome and every page as a `<template>` |
+| `GET /client.js`         | The hub and every used widget, one bundle  |
+| `GET /app.css`           | Every stylesheet, one file                 |
+| `POST /lb?page=<name>`   | The page's query results as JSON           |
+
+The three static files are fixed at release and can be compressed, cached,
+and served from a CDN.  There are no per-route bundles, lazy chunks or module
+waterfalls.  The page template is cloned into `<main>` before its data
+request is sent.  An optional `<body hidden>` in the chrome keeps the
+document hidden until the first page is in place.
+
+Measured on this working tree:
+
+| Item                                           | Size         |
+|------------------------------------------------|--------------|
+| Hub source, `lb-hub.browser.ts` and `lb-apply.ts` | 929 lines, comments included |
+| Hub alone, esbuild `--minify`                  | 8,302 bytes  |
+| Hub alone, minified then `gzip -9`             | 3,377 bytes  |
+
+Each navigation is one POST.  Each interaction is one POST whose response
+carries the refreshed and patched results.  On the server, a page's queries
+run one after another in declaration order, then the response is serialized
+as JSON.  No HTML is rendered on the server after the build.
+
+`app.html` grows with the number and size of pages, and all of it is parsed
+on first load.  Lazy loading of page templates is a roadmap item.  Theory
+states that performance measurements will be published separately; none are
+published as of this writing.
+
+### Elsewhere
+
+| Project          | First load                                                        | Navigation                                     | Interaction                              |
+|------------------|-------------------------------------------------------------------|------------------------------------------------|------------------------------------------|
+| Client-only SPA  | HTML shell, framework and application bundles, often split by route; data requests | Route chunk if not loaded; data requests | State update and re-render; data requests |
+| Next.js, Nuxt, SvelteKit, React Router 7 | Server-rendered HTML, framework and route bundles, hydration | RSC payload or loader data, route chunks | Server Function or action request; revalidation |
+| Astro            | HTML; JavaScript only for hydrated islands                        | Full page load, or client router if enabled    | Island-local                             |
+| htmx             | Server-rendered HTML and the htmx script                          | Full page, or `hx-boost` body swap             | HTML fragment per request                |
+| Turbo            | Server-rendered HTML and Turbo                                    | Fetch full page HTML, replace body             | Form request and page or stream response |
+| Phoenix LiveView | Server-rendered HTML, then a WebSocket connection and mount       | `<.link patch>` and `<.link navigate>` over the socket | Event over the socket, diff back |
+| Blazor Server    | Server-rendered HTML, then a SignalR circuit                      | Over the circuit                               | Event over the circuit, diff back        |
+
+## Surface area
+
+TECHREF-1.0 lists every name Loadbare/app owns in one cross-reference.
+
+| Owned                               | Count | Names                                                         |
+|-------------------------------------|-------|---------------------------------------------------------------|
+| `lb-*` HTML attributes              | 16    | `lb-list`, `lb-row`, `lb-cell`, `lb-show`, `lb-key`, `lb-key-value`, `lb-value`, `lb-action`, `lb-nav-link`, `lb-pending`, `lb-error`, `lb-row-count`, `lb-unknown-page`, `lb-slot`, `lb-template`, `lb-page` |
+| Reserved `lb-action` values         | 4     | `lb-row-insert`, `lb-row-update`, `lb-row-delete`, `lb-cell-change` |
+| `lb*` methods on custom elements    | 2     | `lbPlaceRow`, `lbRowsLanded`                                  |
+| Attribute namespace for expansion   | 1     | `exp-*`                                                       |
+| Reserved tags                       | 1     | `<lb-hub>`                                                    |
+| Reserved events                     | 1     | `lb-request`                                                  |
+| Synthetic rows                      | 1     | `lb-navigation`                                               |
+| Builder flags                       | 4     | `--src`, `--out`, `--watch`, `--minify`                       |
+| Reserved file names and patterns    | 8     | `chrome.html`, `imports.ts`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `<tag>.html`, `<tag>.browser.ts`, `*.css` |
+| Reserved `package.json` keys        | 1     | `loadbare.widgets`                                            |
+| Server functions                    | 5     | `row`, `list`, `patch`, `createHub`, `hubRoutes`              |
+| Browser exports                     | 2     | `applyRow`, `applyData`                                       |
+
+The technical reference, TECHREF-1.0.md, is 1,181 lines.  Theory states that
+the vocabulary fits in an LLM's context window, and discloses that Anthropic
+models writing `.requests.ts` files consistently refresh a list query after
+returning a patch for it.
+
+The other projects in the comparison set do not publish a comparable
+cross-reference, so no count is given for them here.
+
+## Accessibility
+
+### Loadbare/app
+
+- Pages and widgets are native HTML in light DOM.  Loadbare/app adds no ARIA
+  roles and no elements of its own except `<lb-hub>`, `<template>` for
+  absent branches, and the custom elements an application writes.
+- `aria-busy="true"` is set and removed with `lb-pending`.
+- An element hidden by `lb-show` is inside template content, so it is not in
+  the accessibility tree.
+- A widget's markup is in the document and in view-source.
+- On navigation the hub does not move focus, announce the new page, or change
+  `document.title`.
+- Checkboxes and radio buttons are not implemented for landing or gathering.
+
+### Elsewhere
+
+Next.js includes a route announcer for client navigation.  SvelteKit moves
+focus and announces the page title after client navigation.  Nuxt provides a
+`<NuxtRouteAnnouncer>` component for an application to place.  React Router
+and Vue Router leave announcements and focus to the application.  In shadow
+DOM components (Lit by default), `id` references such as `aria-labelledby`
+and `<label for>` do not cross the shadow root boundary.
+
+## Testing
+
+### Loadbare/app
+
+[Testing](./testing.md) documents how the package tests itself, in four
+tiers, with `node:test` run through `tsx`, and jsdom for the browser tiers.
+No browser test runner is installed.
+
+For an application:
+
+- A query is `{ kind, run }`, and `run(ctx)` is a function returning rows.
+- A request entry is `{ run, refresh }`, and `run(ctx, where)` is a function.
+- `createHub(pages)` returns an object whose methods take a page name and a
+  `ctx`, with no HTTP server.
+- `applyData(root, data)` lands a response on any DOM root.
+- A widget is a custom element.
+
+The documentation describes no testing approach for applications.
+
+### Elsewhere
+
+| Project          | Common testing tools                                          |
+|------------------|---------------------------------------------------------------|
+| React            | Vitest or Jest with React Testing Library; Playwright         |
+| Vue              | Vitest with Vue Test Utils; Playwright                        |
+| Angular          | TestBed with Jasmine and Karma, or Jest or Vitest; Playwright |
+| Svelte           | Vitest with Svelte Testing Library; Playwright                |
+| htmx, Turbo      | Server-side tests of HTML responses; Playwright or Capybara   |
+| Phoenix LiveView | `Phoenix.LiveViewTest`, which drives a LiveView without a browser |
+
+## Release history and churn
+
+### Loadbare/app
+
+Loadbare/app is at 0.7.3 and has not reached 1.0.  TECHREF-1.0 lists items
+to decide before 1.0 because they would be breaking changes afterward.
+Theory states that 1.0 is scoped so that foreseeable features can be added
+without breaking existing code.
+
+Application code consists of:
+
+| Part             | Standard or dependency                                  |
+|------------------|---------------------------------------------------------|
+| Pages and chrome | HTML                                                    |
+| Styles           | CSS                                                     |
+| Widgets          | Custom Elements v1 and `<template>`                     |
+| Server           | Express 5                                               |
+| Page server code | TypeScript functions taking `ctx`                       |
+| Binding          | The `lb-*` vocabulary                                   |
+
+The W3C HTML Templates specification was published as a Working Draft in
+2013 (see [Prior art](./prior-art.md)).  Autonomous custom elements have been
+supported in every major browser since Chromium-based Edge shipped in January
+2020.  Express 5.0 was released in September 2024.
+
+Loadbare's history begins with Andromeda in 2003, whose data layer is now
+`@loadbare/db`.
+
+### Elsewhere
+
+| Date           | Change                                                                    |
+|----------------|---------------------------------------------------------------------------|
+| September 2016 | Angular 2 released, incompatible with AngularJS                           |
+| February 2019  | React 16.8 introduces Hooks                                               |
+| September 2020 | Vue 3 released, with the Composition API                                  |
+| December 2021  | AngularJS support ends                                                    |
+| October 2022   | Next.js 13 introduces the App Router alongside the Pages Router           |
+| December 2023  | Vue 2 reaches end of life                                                 |
+| June 2024      | htmx 2.0 released                                                         |
+| October 2024   | Svelte 5 released, replacing reactive declarations with runes             |
+| November 2024  | React Router 7 released, absorbing Remix                                  |
+| December 2024  | React 19 released, with Actions and stable Server Components              |
+| February 2025  | Create React App deprecated                                               |
+
+## What Loadbare/app does not do
+
+Each item is current behavior or an open item named in TECHREF-1.0 or the
+Roadmap.
+
+| Area                          | Status in 0.7.3                                                        |
+|-------------------------------|------------------------------------------------------------------------|
+| Nested data                   | A row never holds rows.  Trees are sent as joined rows.                 |
+| Record URLs and view parameters | A URL names a page.  Parameters are an open blocker.                  |
+| Query arguments from the browser | None.  Selection is server state reached through `ctx`.              |
+| Checkboxes, radio buttons, file inputs | Not landed and not gathered.  Open blocker.                    |
+| Data types and formatting     | No conversion.  Queries format values.  Open blocker.                  |
+| Error messages                | `lb-error` carries no message.                                         |
+| Field validation              | No mechanism.  Per-keystroke validation is a roadmap question.         |
+| Optimistic updates            | None.                                                                  |
+| Concurrent writers            | No version or conflict check.  Roadmap question.                       |
+| Server push                   | None.  No WebSocket or server-sent events.                             |
+| Offline or local-first use    | None.                                                                  |
+| Server-side rendering for crawlers | None.  Every path answers the same document with status 200.      |
+| Subpath hosting               | Not possible.  The hub uses absolute paths.                            |
+| Chrome-level queries          | A widget in the chrome bound to a query requires every page to declare it.  Open blocker. |
+| A widget receiving a whole row | Not available.  Open blocker.                                         |
+| A nested list per outer row   | A nested list receives the same rows in every outer row.  A new outer row's nested list stays empty until its name lands again.  Open blocker. |
+| Configurable request deadline | Fixed at ten seconds.                                                  |
+| Internationalization          | Roadmap item.                                                          |
+| Lazy page loading             | Roadmap item.                                                          |
+| Per-widget CSS shipping       | Roadmap item.                                                          |
+| Dev server, HMR               | None.                                                                  |
+| Language server               | Roadmap item.                                                          |
+| Browser tests of the framework | Not written.                                                          |
+
+## Requirements and fit
+
+Theory states the fit condition: data that is, or maps readily to, rows and
+sets of rows, and affordances that map to the standard operations on that
+data.
+
+Theory also states the strongest objection it knows of and does not dispute
+it: that the binding attributes and the required relational shape exchange
+one set of accidental complexity for another, and that the system is
+"differently accidental" from other frameworks.
+
+The table lists requirements an application may have, and whether each
+approach provides them without additional libraries.
+
+| Requirement                                   | Loadbare/app 0.7.3 | Client component + API | Meta-frameworks | Hypermedia | Server-driven stateful |
+|-----------------------------------------------|--------------------|------------------------|-----------------|------------|------------------------|
+| Pages bound to relational query results       | yes                | application code       | application code | server templates | server templates |
+| No endpoint or route design                   | yes                | no                     | partly (actions, loaders) | no | partly (routes, events) |
+| No client-side state management               | yes                | no                     | no              | yes        | yes                    |
+| No build step                                 | no                 | no                     | no              | yes        | depends on stack       |
+| Server-rendered HTML for crawlers             | no                 | no                     | yes             | yes        | yes                    |
+| Route parameters and record URLs              | no                 | yes                    | yes             | yes        | yes                    |
+| Optimistic updates                            | no                 | yes                    | yes             | no         | partly                 |
+| Offline or local-first operation              | no                 | with libraries         | with libraries  | no         | no                     |
+| Real-time server push                         | no                 | with libraries         | with libraries  | extensions, Turbo Streams over WebSocket | yes |
+| Nested JSON documents                         | no                 | yes                    | yes             | server templates | yes              |
+| Client-only interaction (canvas, editors, drag and drop) | through custom elements | yes | yes      | through scripts | through hooks     |
+| Works while the server is unreachable         | no                 | with caching           | with caching    | no         | no                     |
+| No persistent connection                      | yes                | yes                    | yes             | yes        | no                     |
+| Server code in any language                   | no (Node, TypeScript) | yes                 | no (JavaScript, TypeScript) | yes | no (Elixir, PHP, .NET) |
+| Stable 1.0 or later                           | no                 | yes                    | yes             | yes        | yes                    |
+
+## Appendix A: Matrix
+
+| Aspect               | Loadbare/app                         | Client component                | Meta-frameworks                         | Hypermedia                      | Server-driven stateful          |
+|----------------------|--------------------------------------|---------------------------------|-----------------------------------------|---------------------------------|---------------------------------|
+| State                | Server; DOM                          | Browser memory                  | Server and browser memory               | Server; DOM                     | Server memory per client        |
+| Rendering            | Build time                           | Browser                         | Server, then browser                    | Server per request              | Server per event                |
+| Markup language      | HTML with `lb-*` names               | JSX or template syntax with expressions | JSX or template syntax           | Server templates with `hx-*` or `data-turbo-*` | HEEx, Blade, Razor  |
+| Components           | Light-DOM custom elements            | Framework components            | Framework components                    | Server partials; Stimulus controllers | Server components         |
+| Wire                 | One POST endpoint, JSON rows         | Application-designed            | Framework-defined                       | HTML over HTTP                  | WebSocket or snapshot POSTs     |
+| Mutation refresh     | Declared `refresh` names; patches    | Application code or query invalidation | Revalidation                     | Response HTML                   | Re-render                       |
+| Routing              | Flat page names; no parameters       | Router library                  | File-based, with parameters and layouts | Server routes                   | Server routes                   |
+| Build                | `loadbare-app-build`, esbuild        | Vite and others                 | Vite, Turbopack, others                 | None required                   | Stack-specific                  |
+| CSS                  | Concatenated, unscoped               | Varies                          | Varies, scoped options                  | None                            | None built in                   |
+| Server               | Application's Express app            | Application's API               | Framework server or adapters            | Any                             | Phoenix, Laravel, ASP.NET Core  |
+
+## Appendix B: One page, three ways
+
+An invoice page shows the invoice's number and customer, a table of its
+lines, and a Remove button per line.  Removing a line changes the invoice
+row, so the invoice is refreshed.
+
+### Loadbare/app
+
+```html
+<!-- invoice.page.html -->
+<section lb-row="invoice">
+  <h2 lb-cell="number"></h2>
+  <span lb-cell="customer"></span>
+</section>
+
+<table>
+  <tbody lb-list="invoiceLines">
+    <template lb-key="id">
+      <tr>
+        <td lb-cell="item"></td>
+        <td lb-cell="amount"></td>
+        <td><button lb-action="lb-row-delete">Remove</button></td>
+      </tr>
+    </template>
+  </tbody>
+</table>
+```
+
+```ts
+// invoice.queries.ts
+import { list, row, type Queries } from "@loadbare/app/server";
+
+export const queries: Queries = {
+  invoice: row((ctx) => ctx.db.currentInvoice()),
+  invoiceLines: list((ctx) => ctx.db.currentInvoiceLines()),
+};
+```
+
+```ts
+// invoice.requests.ts
+import { patch, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  crud: {
+    invoiceLines: {
+      rowDelete: {
+        run: async (ctx, where) => {
+          await ctx.db.deleteLine(where.key);
+          return { invoiceLines: patch({ drop: [where.key] }) };
+        },
+        refresh: ["invoice"],
+      },
+    },
+  },
+};
+```
+
+Which invoice is current is held on the server and reached through `ctx`.
+The button carries `lb-pending` and `aria-busy` while the request is in
+flight.  The request sent is
+`{ "action": "lb-row-delete", "list": "invoiceLines", "key": "42" }`.  The
+response carries the refreshed `invoice` row and a patch dropping key `42`.
+
+### Next.js (App Router)
+
+```tsx
+// app/invoices/[id]/page.tsx
+import { db } from "@/lib/db";
+import { deleteLine } from "./actions";
+
+export default async function InvoicePage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  const invoice = await db.invoice(id);
+  const lines = await db.invoiceLines(id);
+  return (
+    <>
+      <section>
+        <h2>{invoice.number}</h2>
+        <span>{invoice.customer}</span>
+      </section>
+      <table>
+        <tbody>
+          {lines.map((line) => (
+            <tr key={line.id}>
+              <td>{line.item}</td>
+              <td>{line.amount}</td>
+              <td>
+                <form action={deleteLine.bind(null, id, line.id)}>
+                  <button>Remove</button>
+                </form>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </>
+  );
+}
+```
+
+```ts
+// app/invoices/[id]/actions.ts
+"use server";
+import { revalidatePath } from "next/cache";
+import { db } from "@/lib/db";
+
+export async function deleteLine(invoiceId: string, lineId: string) {
+  await db.deleteLine(lineId);
+  revalidatePath(`/invoices/${invoiceId}`);
+}
+```
+
+The invoice is addressed by URL.  `revalidatePath` causes the page's Server
+Component to render again, and the response carries the new RSC payload for
+the page.  A pending state on the button requires a Client Component using
+`useFormStatus`.
+
+### htmx with Express
+
+```html
+<!-- rendered by the server for GET /invoices/7 -->
+<section hx-get="/invoices/7/header" hx-trigger="line-deleted from:body">
+  <h2>INV-0007</h2>
+  <span>Acme</span>
+</section>
+
+<table>
+  <tbody hx-target="closest tr" hx-swap="outerHTML">
+    <tr>
+      <td>Widget</td>
+      <td>12.00</td>
+      <td><button hx-delete="/invoices/7/lines/42">Remove</button></td>
+    </tr>
+  </tbody>
+</table>
+```
+
+```ts
+// server.ts, alongside the route and template that render the full page
+app.delete("/invoices/:id/lines/:line", async (req, res) => {
+  await db.deleteLine(req.params.line);
+  res.set("HX-Trigger", "line-deleted").send("");
+});
+
+app.get("/invoices/:id/header", async (req, res) => {
+  const invoice = await db.invoice(req.params.id);
+  res.send(
+    `<h2>${escapeHtml(invoice.number)}</h2><span>${escapeHtml(invoice.customer)}</span>`,
+  );
+});
+```
+
+The empty response replaces the row, which removes it.  The `HX-Trigger`
+header fires `line-deleted`, and the section requests its own fragment.  The
+application designs three routes and renders three HTML responses, and
+escapes values in them.  The button carries the `htmx-request` class while
+the request is in flight.
+
+## Appendix C: Glossary of nearest equivalents
+
+Each equivalent is approximate.
+
+| Loadbare/app                  | Nearest equivalents elsewhere                                                    |
+|-------------------------------|----------------------------------------------------------------------------------|
+| Hub                           | Client runtime; router plus data layer                                           |
+| Chrome (`chrome.html`)        | Root layout (`app/layout.tsx`, `+layout.svelte`); application shell              |
+| Page (`<name>.page.html`)     | Route component; page template                                                   |
+| Query (`row()`, `list()`)     | Loader (React Router 7); load function (SvelteKit); data read in a Server Component |
+| `onPageEnter`                 | LiveView `mount`; code at the top of a loader                                    |
+| Declared action               | Route action (React Router 7); form action (SvelteKit); Server Function; LiveView `handle_event` |
+| `crud` operation              | Resource controller action (Rails); REST verb on a row                           |
+| `refresh`                     | Revalidation; `invalidateQueries`; `revalidatePath`                              |
+| `patch({ rows, drop })`       | Keyed partial update; Turbo Stream `append`/`replace`/`remove`; LiveView `stream_insert`/`stream_delete` |
+| Landing                       | Render and commit; swap; patch                                                   |
+| `lb-list`, `lb-row`, `lb-cell` | IE4 `DATASRC` and `DATAFLD`; `v-for` and `{{ }}`; `x-for` and `x-text`         |
+| `lb-key`                      | `key` (React, Vue); `track` (Angular); keyed `each` (Svelte)                     |
+| `lb-show`                     | `v-if`, `@if`, `{#if}`, `x-if`                                                   |
+| `lb-value`                    | A prop; an observed attribute                                                    |
+| `lb-action`                   | `hx-post`; `phx-click`; `wire:click`; `<form action>`                            |
+| `lb-request` event            | `htmx:beforeRequest`; a component `emit`                                         |
+| `lb-pending`                  | `htmx-request` class; `phx-click-loading`; `useFormStatus().pending`; `wire:loading` |
+| `lb-error`                    | `htmx:responseError`; an error boundary                                          |
+| `lb-row-count`                | An empty-state conditional in a template                                         |
+| `lb-nav-link`                 | `<Link>`; `hx-boost`; Turbo Drive                                                |
+| `lb-navigation`               | `useLocation`; `page.url` (SvelteKit); `$route` (Vue Router)                     |
+| Widget                        | Component; custom element                                                        |
+| Expansion                     | Server-side include; partial; build-time component render (Astro)                |
+| `exp-` parameter              | A prop fixed at build time                                                       |
+| `lb-slot`, `lb-template`      | Default slot and named slots; `ng-content` with `select`                         |
+| `lbPlaceRow`, `lbRowsLanded`  | Custom list rendering; a render prop                                             |
+| `ctx` / `HubContext`          | `event.locals` (SvelteKit); loader `context` (React Router 7); request-scoped dependency injection |
+| `imports.ts`                  | Installing and registering a component library                                   |
+| `pages.ts`                    | Generated route manifest                                                         |