@loadbare/app 0.16.0 → 0.18.0

package/docs/theory.md

@@ -1,839 +1,113 @@
-# Theory of Loadbare App
-
-by Ken Downs, August 29, 2026.  Revised September 14, 2026.
-
-Loadbare is one man's answer to the expensive development and slow performance
-of modern web apps.  When using modern frameworks, it often feels like
-I am working 
-for the tools instead of the other way around.  After all of that work,
-I have an application that does not respect the user's time, it is
-slow.
-
-My first goal in creating `@loadbare/app` was performance.  I want my
-applications to be very snappy, I want them to respect the user's
-time.  
-
-Efficient development is my second goal, so long as it leads to a
-snappy and performant application.  My intuitive sense here is that
-the enemy of efficient development is what Fred Brooks called
-"accidental difficulties", the time you spend servicing the tools that
-allow you to build the application.  Driving accidental complexity
-as close as possible to zero therefore became the next goal, as that
-would naturally result in developer efficiency.
-
-To begin, I had to redefine some of the popular concepts that govern
-discussion and decisions around front-end development.
-
-## The Principle of Developer Experience
-
-Developer experience is often defined in terms of developer ergonomics,
-leaving out the developer's motivation for wanting to be comfortable.
-So I began by establishing a personal definition of the
-ideal developer experience:
-
-> The Principle of Developer Experience: The best developer experience is
-> creating an application that people use and appreciate.
-
-This principle pre-empts arguments for elegant abstractions and tooling
-that are not obviously and directly contributing to a satisfied
-end user.
-
-This principle combines and aligns business concerns with engineering
-concerns, grounding any solution in the desire to make a useful application.
-
-While no technical solution can magically provide me with the product
-skills to produce an application that users appreciate, I do not
-want the solution to make demands on my time that take me away from
-that goal.
-
-## The Principle of User Experience
-
-The Principle of Developer Experience grounds us in the end user,
-and from here I considered my own largest single complaint about
-web apps: they are so damn slow.
-
-The path to a performant solution puts performance first and all
-design decisions follow from that primacy.  Performance is not something
-to be optimized after a solution has been found by following other
-priorities.
-
-After some research into what people perceive as performant, I came
-upon the number of 300ms.  Faster than that seems abrupt, slower
-seems sluggish.  This led to the next foundation principle:
-
-> The Principle of User Experience: a full server round trip should
-> complete, from user action through durable persistence to final
-> paint, in a median time of 300ms.
-
-This scopes the goal to performance and performance only.  All other
-aspects of the UI are mature, we have a mature inventory of widgets
-for user display and interaction.  We do not need to invent new
-solutions for accessibility, tabs, buttons and so forth.  What we need
-is a way to use the mature solution and respect the user's time.
-
-There is a direct practical implication: if we have a 300ms budget,
-and roughly assume 200ms median wire time, we must split the remaining
-100ms between database, non-db server, and browser.  Since the database
-in the limiting case must provide durable persistence, our ideal
-processing time for browser and app server activity must
-approach zero.  In other words, our solution must be a model citizen,
-chewing up as few cycles as possible while providing the full modern
-experience of a web app, leaving
-as much as possible of the 100ms to the database.
-
-## The Principle of Essential Complexity
-
-Now we move on to developer efficiency.  Fred Brooks gave us a powerful
-way to consider this, when he made the distinction between "essential difficulties"
-and "accidental difficulties", later glossed into
-"essential complexity" and "accidental complexity".
-
-Essential complexity is the inherent difficulty of solving the user's
-problem.  This is where we want to spend our time and effort.
-Accidental complexity is the work demanded by the tools we use to solve
-the problem.  We want to minimize this, always pushing to zero.
-
-So, with apologies to Brooks and Pike, here is my mash-up and restatement
-of their ideas, tuned to the current task:
-
-> Essential complexity should dominate.  Show me your abstractions and tooling and
-> I shall remain mystified.  Show me your tables and your rendering vocabulary
-> and I shall be enlightened - the organization of the code will be self-evident.
-
-## The Search For a Solution
-
-The three principles above give some weight to my intuitive rejection
-of the fat browser frameworks, though it would be truer to say the
-rejection came first.  My extensive experience
-with React, Angular and VueJS left me able to state what I
-had found lacking.  Once stated, the principles made it plain that the
-frameworks' motivations and mine are irrelevant to each other.
-
-This led me to look at the Hypermedia libraries.  After several weeks
-of iterations, I found myself frustrated. These were very clearly
-closer to what I wanted, and the various authors' motivations seemed
-very close to my own, but I was still seeing more tooling concerns
-than I wanted. I seemed to be fighting the libraries, which could
-mean there was some unstated assumption we did not share, or perhaps
-they were solving a problem I did not have.
-
-## Different Views of The Problem
-
-The lightbulb moment came when I found the unstated assumption,
-and found it served a problem I don't have. The solutions I had
-tried all support a DOM that is fully mutable
-at any time for any reason. They
-all provide or expect an HTML templating system that combines
-interpolation of data values with conditional and list rendering,
-controlled by run-time attributes.
-
-But I always think of the front-end as an interface to data that
-is either in a relational store or can be sent to the browser
-in relational shapes: single rows or sets of rows.  I expect the
-DOM to mutate in response to data hydration and refreshes, which
-dramatically reduces the set of required mutations from "could be
-anything at any time" to exactly "refresh these representations
-of the data returned by the server".
-
-There are, of course, other mutations besides
-data. A button may be disabled after click when a request is in
-flight, and must be enabled when the request completes. Some DOM
-nodes become visible or invisible as a result of
-user interaction or data refreshes.  A response may contain error
-information that must be presented to the user. But adding these cases
-only reinforced the emerging hypothesis: there is a knowable
-and closed set of required mutations for the DOM in a
-data-oriented application. A solution that optimizes for that closed
-set does not need the
-complexity required to support arbitrary DOM updates.  This could
-be the path to a solution that is performant and reduces accidental
-complexity.
-
-## The Solution Outline
-
-Now it was time to iterate on a framework for data-oriented applications
-with propositions narrowed to that space:
-
-1. If HTML carries some type of data binding attributes,
-   then the framework can perform all data-driven DOM mutations.
-2. Given a data binding attribute vocabulary, other
-   mutations could be handled with additional attributes, either as natural
-   extensions to data binding, or in other channels that are fully
-   independent and do not interfere with data binding.
-3. Most server code ought to be reducible to responding to requests with
-   data.
-
-Propositions 1 and 3 give hope of meeting our performance requirement.
-The framework task list is small, and tuning it for performance at
-every iteration seems doable.
-
-Proposition 2 gives hope of meeting our requirement that the application
-satisfy the high expectations of a modern UI, with many flexible affordances.
-
-But as promising as these propositions were, they do not yet fully
-cover the requirements listed
-at the top of this essay.  At this point I only had a foundation and
-general direction.
-Going further required more iterations with demos and side projects,
-tying the general ideas to many specific implementation
-decisions.
-
-## Solution Particulars
-
-From here it is no longer useful to trace through the specifics
-of various iterations.  A full recitation of dead ends, aha moments, revisions
-and experiments would be tedious and uninformative.
-
-It would be equally tedious to recap the [Technical Reference](./TECHREF-1.0.md),
-or to flatly list the final mechanisms.  
-
-What follows instead is a basic outline of the mechanisms and 
-decisions as they finally stand, noting how each contributes to
-the major goals and to other nice-to-have goals that are mentioned
-in the course of the text.
-
-### Scope and Boundaries
-
-Before I enumerate the mechanisms, I have to state how the framework
-boundaries fell out of the Principle of Essential Complexity.
-
-The framework does what we do not want to repeat in every application:
-binding data to the DOM, carrying requests and responses, assembling the static
-assets, wiring up the API.  Everything else is the essential
-complexity of creating a particular application: what the data is, how it
-is stored and fetched, who may see it or change it, and how it looks.
-
-Where the framework leaves something to the application, it provides an
-empty slot and has no opinion about what goes in it.  It does not:
-
-- prescribe or prohibit any CSS architecture
-- require or prevent any authentication solution
-- expect or hinder the use of an ORM, or of `@loadbare/db`
-
-Loadbare is for applications, not sites.  Every route is answered with
-the same document, and a path that names no page is found out in the
-browser rather than answered with a 404.  The path names a page, and the
-query string describes what that page has on screen, so the address bar
-is always true and a URL can be reloaded or mailed to someone.
-
-The rule for one-time chores, such as standing up an Express Server,
-is that they stay as close as possible to "set and forget", so that
-their cost is paid once and they are not a tax on 
-application development tasks.
-
-### HTML and Javascript
-
-HTML and Javascript are listed here first.  They achieved the final
-form long before the rest of the framework, drove the builder
-design, and were the seed crystal that everything else formed
-around.  
-
-The framework organizes HTML and Javascript together, expecting
-the HTML to be composed of native elements and custom elements
-with light DOM.  Framework and application code are both built this
-way.
-
-The HTML is static, and is written in `.html` files, and once
-delivered to the browser it remains static.
-
-The framework manipulates the DOM by reading attributes.
-When data arrives, it can do direct scalar assignments 
-or use `<template>` nodes
-that are cloned for lists, with scalar assignments made to
-each cloned instance.
-
-This structure allows for a very simple builder.  The builder
-scans HTML, and when it finds a custom element, it makes sure
-there is either a matching JavaScript file, a matching HTML file,
-or both.  Only the absence of both of them triggers an error, as
-we assume a custom element without a JavaScript class or HTML must
-be a mistake.
-
-Nearly every benefit of the approach falls out of that one
-scan.  Because the builder finds everything by name, it can do
-the following without any configuration and without any new syntax:
-
-- HTML includes for free, no hacky syntax.  When the builder
-  finds a custom element with a matching `.html` file, it expands
-  the element in place, recursively.  
-- Separation of build-time parameters from data binding.
-  An attribute on a custom element can
-  be substituted into its HTML at build time, where it becomes
-  permanent. This might be the label on an input or the text of a button.
-  Once the HTML is all chased down, build-time parameters are
-  constants in the shipped HTML code.
-- Slots.  A custom element can provide the equivalent of named
-  slots, filled by `<template>` elements that the builder resolves.
-- No Javascript imports.  A custom element that is used pulls in
-  its matching script by name.  There is no import graph to maintain,
-  reason about, or break.
-- Tree shaking for free. A script whose element is never used in 
-  the HTML is never shipped.  There is no dead code analyzer, 
-  because dead code was never pulled in.
-- Validation for free.  A custom element with neither a script
-  nor an HTML file is a build error, and it catches the
-  typo'd tag that the browser would otherwise silently ignore.
-- Three static assets.  The build produces one HTML document
-  with every page inside it as a `<template>`, one `client.js`
-  holding the hub and every widget actually used, and one `app.css`
-  holding every stylesheet exactly as it was authored.  This 
-  is an easy builder to code, and leads to easy server code and
-  deployment configurations.
-- CSS neutral.  Because stylesheets are concatenated and nothing
-  is added, removed or scoped, the builder neither requires nor
-  prohibits any particular approach to CSS.
-- JavaScript is part of the DOM tree.  By coupling JavaScript
-  to custom elements, it can always reliably manipulate its
-  children, and find shared code in ancestors.  
-
-At runtime the same structure covers the rest of what a modern UI
-needs.  Lists are handled by the `<template>` mechanism and data
-binding, as already mentioned. Conditional rendering is handled
-by one more attribute, `lb-show`, naming the column that decides
-whether an element is present.  When the value is null or false,
-the hub moves the element into a `<template>` standing where it
-stood, and moves it back out when the value returns.  (Note: this
-last claim is not yet fully proven by a demo or the author's projects.)
-
-Finally, and this is only my opinion, but I find static HTML with data
-binding attributes to be far easier to author, inspect,
-reason about, and maintain than systems like JSX that mix
-together permanent items like a button label with interpolated
-data, lists, and conditional rendering.
-
-### Why the HTML Solution is Performant
-
-The HTML solution is one of two central pillars to my claim
-that `@loadbare/app` can deliver an app that fits into the
-median 300ms allotted to round trips from click to paint.  Everything 
-listed in the previous HTML and Javascript shows that the 
-HTML and Javascript solution makes the framework the "model citizen"
-that does as little work as possible, leaving
-as much budget as we can to the database.
-
-Most of the work happens once, at build time. Widget expansion,
-build time parameters, slots, composition, validation and tree
-shaking are all done by the builder.  None of it is repeated in the
-browser, and none of it is repeated per request on the server.
-
-The solution means that the only runtime work left is work that
-cannot be done until the data arrives.
-
-The application loads once. A session begins with three static
-files: one HTML document, one script and one stylesheet.  They are
-plain static assets, so they can be compressed, cached, and served
-from anywhere.  There are no per-route bundles, no lazy chunks, and
-no waterfall of module requests discovering their imports one at a
-time.  The `--minify` flag shrinks the script and stylesheet further.
-
-The framework is small.  The entire browser framework is the
-"hub" (explained below), which is under a thousand lines 
-of Typescript, comments
-included (as of this writing).  There is no virtual DOM, no component tree, no
-reactivity system and no scheduler to download, parse, or run.
-
-Navigation fetches no HTML and no code.  Every page is already
-in the document as a `<template>`, parsed once by the browser when
-the document loaded.  Moving to a page is a native `cloneNode` of
-that template into `<main>`.  
-
-Only data crosses the wire. The server returns rows as JSON.
-Rows are far smaller than the markup that displays
-them, and the markup is already in the browser.  One interaction is
-one request and one response, carrying back any refreshed or changed
-data.
-
-Only changed data crosses the wire. A request handler names the queries
-it refreshes, so the server re-runs only those, not the whole page.
-Where even that is too much, a request can return a patch: the rows
-that arrived or changed and the keys that went, rather than the
-entire list shipped again.
-
-The server renders nothing.  There is no server-side rendering,
-no server templating, and no hydration step.  A page's server code
-runs its queries and hands back what they returned.  Nearly all of
-the server's time for a request is therefore the database's time,
-which is exactly where the Principle of User Experience wants it.
-
-The framework mutates DOM in response to data refreshes using a 
-closed set of operations. The
-hub finds its targets with the browser's own selector engine, by
-the attributes written in the HTML, and sets a value, some text, or
-an attribute, or moves an element into or out of a template.  No tree is diffed, and no
-element is rebuilt because its data arrived again.  The framework
- never has to
-consider what might have changed, because the response says exactly
-what did.  
-
-Nothing runs between interactions. Once data has landed, the
-hub waits on events.  It keeps no timers, no observers and no
-polling loop, so an idle page costs the browser nothing.
-
-Taken together, the framework's share of a round trip is a small,
-fixed amount of work in the browser, a JSON serialization on the
-server, and little else.   
-
-### Chrome and Naming Conventions
-
-Something else fell out of the HTML and Javascript solution fairly
-early in framework development.  It turned out that a handful of
-hard-coded naming conventions could simplify the builder while
-giving flexibility to file organization.
-
-The builder would require exactly one file named 'chrome.html', 
-anywhere in the source tree, which contains the application skeleton,
-and is processed the same as all other HTML files.
-
-The builder would recognize any page ending in '.page.html' as a 
-navigation target.  
-
-A custom element's JavaScript, if present, should be named
-`my-custom-element.browser.ts`.  The '.browser.' segment requires
-deliberate action to get the code into the browser, eliminating
-configuration files or switches that specify which code in the
-source tree is prohibited or forced into the browser.
-
-A custom element's HTML, if present, should be named `my-custom-element.html`.
-All matching is by name, no configuration required.
-
-The builder scan begins with `.page.html` files and `chrome.html`. All
-logic is simple and already stated: pick up code and HTML for custom
-elements, and do so recursively. That is the entire algorithm.
-
-This means that no special new mechanism was required for 
-application chrome. There is no requirement for how to
-organize application code, and the destiny of every file is evident
-from a directory view.   
-
-### Data Binding
-
-Once it looked like HTML authoring and building was solved, it was time
-to ensure that Data Binding would not crash the party.  If data binding
-exploded into overlapping features and nasty edge cases, all progress would
-halt. 
-
-If the framework browser code is to remain small, performant, and robust,
-and fully expressive, then all of it must be achieved by reducing the
-data binding to a closed set of non-overlapping features.
-
-This meant that the earlier vague idea of "relationally shaped" had to
-become a scoping decision.  The framework browser code will only understand
-rows and sets of rows.  It will not understand a JSON document where child
-rows are embedded in a row, and it will not understand a tree where there are
-children in children in children.  This does not force a relational 
-database, but it does force server code to return data in the shapes of
-rows and sets of rows.
-
-That scoping decision allowed us to reduce the data binding vocabulary
-to one idea: everything is a query.  A query is a name for rows, of kind
-`row` or `rows`, with a key.  The server declares all three facts about a
-query, so the markup names the query and the columns it shows, and
-repeats nothing the server already said.  Three attributes carry the whole
-of it:
-
-| Attribute   | Relational idea            | HTML precedent                                 |
-| ----------- | -------------------------- | ---------------------------------------------- |
-| `lb-query`  | A query, one row or many   | `<select>` or `<form>`, a container of records |
-| `lb-column` | A column                   | `name` on a form control, which field this is  |
-| `lb-show`   | A column deciding presence | `hidden`, whether an element is shown          |
-
-The key never appears in the markup.  The server declares it with the
-query, `rows("id", run)`, and the hub stamps each live row with its
-value as `lb-key-value`, the way an `<option>` carries a `value` apart
-from its text.
-
-A highly simplified page showing
-an invoice and its lines looks like this:
-
-```html
-<section lb-query="invoice">
-  <h2 lb-column="number"></h2>
-  <span lb-column="customer"></span>
-</section>
-
-<table>
-  <tbody lb-query="invoiceLines">
-    <template>
-      <tr><td lb-column="item"></td><td lb-column="amount"></td></tr>
-    </template>
-  </tbody>
-</table>
-```
-
-`invoice` is of kind `row`, and with no row template inside it the row
-lands on the `<section>` itself.  `invoiceLines` is of kind `rows`, and
-the hub clones the row template once per row.
-
-This decision proved decisive in keeping the browser code robust,
-expressive, and performant.
-
-
-### Requests and Request State
-
-Proposition 2 said that once there is a data binding vocabulary, the
-other mutations could be handled with additional attributes, either as
-extensions to data binding or in channels that are independent of it.
-The idea is that user interaction triggers framework browser code
-that "knows what to do", assembling a request driven purely from
-attributes. 
-
-This requirement is satisfied with a single new attribute, `lb-request`.
-Three request names are Loadbare's: `lb-row-insert`, `lb-row-update` and
-`lb-row-delete`.  Any other value names a request the page declares on
-the server.
-
-A request is a name and a position.  The author writes the name, and
-the hub supplies the position from the document, using the same
-ancestor rule that decides where a value lands.  An element commits the
-way HTML already says it does: a form on `submit`, a control on
-`change`, anything else on `click`.  To add a delete button to the
-invoice lines from the previous section, the row template gains one
-element:
-
-```html
-<template>
-  <tr>
-    <td lb-column="item"></td>
-    <td lb-column="amount"></td>
-    <td><button lb-request="lb-row-delete">Remove</button></td>
-  </tr>
-</template>
-```
-
-The button names neither the query nor the key.  When it is clicked,
-the hub reads `invoiceLines` from the nearest ancestor `lb-query` and
-the key from the live row around the button, and sends:
-
-```
-{ name: "lb-row-delete", query: "invoiceLines", key: "42" }
-```
-
-Every request has that one shape: a name, and `query`, `key` and
-`values` as present.  An insert or update gathers `values` from the
-controls around the element that committed: a form's controls, a live
-row's, or the controls whose form owner is the element's.
-
-But we need to be more modern than that.  Nowadays we expect the
-button to be disabled after it is clicked, and to display a wait
-state in case the network is congested.  In other words, the 
-framework browser code needs to notify the event target of its
-request state.
-
-To do this, framework browser code stamps two attributes about a
-request, `lb-request-pending` and `lb-request-error`, and a third about
-a query, `lb-query-row-count`.  The framework browser code ignores a
-commit on an element stamped with `lb-request-pending`, meaning the
-disabled state can be represented entirely by CSS, no JavaScript
-needed.
-
-The developer writes `lb-*` attributes in markup, and script never
-assigns them.  The hub and the builder write only their stamps.  That
-rule is what lets the builder check the markup once, at build time.
-
-Over many iterations I gradually reduced the core attributes to 
-these, from a larger set that had more overlapping behaviors and edge
-cases.  In the end this small set builds on and protects the
-HTML/JavaScript solution. 
-
-### The Hub
-
-So far I have been using the term "framework browser code".  In other
-documents we call it the hub.  
-The hub is one custom element, `<lb-hub>`, and it is the entire
-browser framework.  It has three jobs: navigation, synthetic context, and the data channel.
-
-#### Navigation
-
-As previously stated, the 1.0 builder packages all page HTML into the
-chrome and ships it as `app.html`.  With all pages already present
-in the browser, providing an SPA is fairly simple.
-
-The hub catches anchor clicks, and checks if the anchor contains the
-attribute `lb-url-link`.  If so, the hub interprets a plain primary
-click as in-app navigation, shows the page the `href` names in
-`<main>`, and sends a request to the server for the page data.  The
-query string rides along, so the server always knows what URL the
-browser is showing.
-
-Anchors without the attribute behave as normal links.
-
-#### Synthetic Context
-
-Synthetic context emerged as a useful feature near the very end of
-development.  Realizing that the hub knows about the current URL, we
-had it serve a query of its own, `lb-url`, of kind `row` and keyed by
-`lb-path`.  Its columns are the path, the page's title as
-`lb-page-label`, whether the path names no page as `lb-page-unknown`,
-and one column per query parm.
-
-These can be bound to any HTML, same as any other query the
-application declares, but the hub supplies the row.  The hub also
-answers requests for it: a control writing a query parm is
-`<input lb-column="q" lb-request="lb-row-update">` inside
-`lb-query="lb-url"`, an ordinary row update that the hub answers by
-writing the URL and reloading the page's queries.  A handler on the
-server moves the URL the same way, by returning `url({ q: "5" })`.
-
-There may be more synthetic context in the future.
-
-#### The Data Channel
-
-We have already worked out that the hub is crafting requests,
-stamping request state, and mutating the DOM based on data received
-in responses.
-
-We have implicitly already assigned the hub responsibility for
-the data channel, and here I simply want to say it out loud.
-
-### Server Page Code
-
-Proposition 3 said that most server code ought to be reducible to
-responding to requests with data.  In Loadbare a page is up to three
-files that share a name: `invoice.page.html`, `invoice.queries.ts`
-and `invoice.requests.ts`.  The HTML is the page as the user sees it,
-the queries provide the data, and the requests are what it allows.
-
-Each query is declared with `row(key, run)` or `rows(key, run)`,
-naming its kind and its key.  Every response carries response items,
-each naming its query, kind and key beside the row, the rows, or a
-patch.  Each request declares the work it does and the
-queries to run again afterward.  Here is the delete button from
-Requests and Request State, as the server sees it:
-
-```ts
-// invoice.requests.ts
-import { patch, type Requests } from "@loadbare/app/server";
-
-export const requests: Requests = {
-  crud: {
-    invoiceLines: {
-      rowDelete: {
-        run: async (ctx, { key }) => {
-          await ctx.db.deleteLine(key);
-          return { invoiceLines: patch({ drop: [key] }) };
-        },
-        refresh: ["invoice"],
-      },
-    },
-  },
-};
-```
-
-Deleting a line changes the invoice total, so the entry refreshes
-`invoice`.  `invoiceLines` itself does not need to be queried again, since
-the only change is one row that went away, and `run` says so with a
-patch.  The response carries two response items: the refreshed invoice
-row, and the patch that removes one line.
-
-Loadbare, as it turns out, does not have "endpoints" as such.  If the
-HTML places an `lb-row-delete` inside `lb-query="invoiceLines"`, then the
-server carries a CRUD entry `rowDelete` under object invoiceLines.  A
-declared request is the same, keyed by its name under `handlers`.
-Since the browser and server exist to talk to each other in the same
-language, no additional abstraction is needed.
-
-
-### The Express Server
-
-Loadbare ships no server, and the application writes an ordinary
-Express app.  I was rather surprised myself to find that the simplest
-solution here was to show example code, instead of shipping a shrink-wrapped
-server.  Most frameworks today provide a
-server so completely hidden that a newcomer to the industry can be
-forgiven for not knowing Express is underneath.
-
-The build leaves the server four things to handle: the script, the
-stylesheet, the hub's data channel, and the one HTML document.
-The builder also writes a file,
-`pages.ts`, that gathers every page's queries and requests into one
-hub, so the server imports that hub and never lists the pages itself.
-The part of the server that belongs to Loadbare is four lines:
-
-```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 stay the same as pages are added.  Everything else in the
-file belongs to the application, and that is where authentication,
-sessions, logging and the opening of the database go.
-
-If we tried to ship a server, we'd have to load it with hooks for every
-concern we don't handle, and we'd end up re-inventing Express.  So 
-we don't do that.
-
-### What the Application Provides
-
-What Loadbare leaves to the application is the essential complexity
-named in Scope and Boundaries: what the data is, how it is stored and
-fetched, who may see it, and how it looks.  On the server, all of it
-reaches the page code through one object.
-
-For each request, the application builds a context, `ctx`, in a
-function it hands to the hub in the Express server:
-
-```ts
-function contextFor(req: Request): HubContext {
-  return { db: openDb(req) };
-}
-```
-
-Loadbare passes `ctx` to every query and every request.
-A query finds exactly what the application put there,
-which is usually a database handle opened for the user who made the
-request.  Authentication decides what goes into `ctx`, and the page
-code sees only the result.
-
-How the application reaches its database is also its own choice.  I
-always use `@loadbare/db`, which declares calculated values as part
-of the schema.  Most reads come from one table or a simple view, and
-a write to one table cascades its calculations to related tables, so
-my page code calls the database directly and there is no business
-logic layer in the application at all.  A team not using
-`@loadbare/db` will probably use an ORM or write a business logic
-layer, and it reaches the page code through `ctx` in the same way.
-
-
-### Conclusions Against the Three Principles
-
-As we near the end of the essay, I want to summarize why I believe
-that `@loadbare/app` meets the goals set out at the top of the 
-essay.  I believe that overall we are somewhere well past
-plausible for all claims, but only further iterations and usage
-will tell the tale.  This is a theory document, not a hard proof.
-Performance stats and tables will be published separately.
-
-The first principle stated in this essay was the Developer Experience
-Principle, that the best developer experience was building something
-that people use and appreciate.
-
-No framework can directly give me that wonderful app, so I have to
-elaborate that product talent must be leveraged and never blocked
-by the framework.  If the framework is to help instead of hinder,
-it must smooth the path towards a great user experience, with 
-developer efficiency being a co-equal primary goal.
- 
-#### The User Experience
-
-User experience, in the broad sense, is a solved problem. We have long had a rich
-visual and interaction vocabulary, sufficiently expressive to
-present any form of data and allow interaction with it.  Loadbare need
-invent nothing here, it must only take care not block the correct solutions.
-
-But the orphan out in the barn is performance, which users arguably
-care about more than anything.  
-
-In terms of performance, I believe the claim that Loadbare has a good
-chunk of the answer and is deep into "undeniably plausible".  The framework's
-tasks, footprint and overhead are so small that it cannot help but
-to be faster than the more elaborate alternatives.  This is true in
-both the browser and the server.  Loadbare has precisely zero
-"abstractions" that promise ergonomics while eroding performance.  The
-path from request to server to response to paint contains exactly the
-steps that are essential to the job being done, and nothing more.
-
-If we consider performance as settled as it can get in a theory
-document, we move on to the rest of the User Experience, where
-loadbare follows the principle of not blocking the developer's desired
-solution.  Anything around accessibility, theming or skinning, branding,
-interaction, and responsiveness fit into a widget library and a
-CSS solution.
-
-Consider that HTML is highly accessible when used mindfully, 
-with a handful of aria-* attributes filling in the blanks.  Concerns
-such as contrast and target size are all solved in CSS.  This is why
-loadbare uses plain HTML, light DOM, and allows any structure of CSS: so that
-a designer can specify an accessible design that becomes an 
-accessible widget library that is used to build an accessible app.
-
-#### Essential Complexity
-
-The essential complexity claim I believe is more vulnerable to
-honest critique or different perspectives, so first we'll look at
-it in a condensed form, and then address the best steel man argument
-I can muster.
-
-First, Loadbare has few requirements for project setup.  They are
-one-time, and do not grow at the scale of the app.  Every attempt
-has been made to make them "set and forget".
-
-Second, Loadbare is missing entire categories of developer effort,
-while providing expected benefits.  HTML includes without imports,
-declarative browser data binding and requests, free tree shaking,
-extendable with custom elements, a small set of mechanisms, and 
-nothing to learn about the "the Loadbare way for CSS", among many
-others.
-
-Third, the essential activity of page and widget authoring, where
-almost all of the work is, use nothing more than HTML and JavaScript
-that is naturally coupled to the DOM.  On the server, the queries
-and requests have no boilerplate, setup or teardown requirements.
-
-Fourth, the entire Loadbare vocabulary can fit in a single technical
-reference document, which means it can fit into a person's head or
-an LLM's context window.  
-
-> Full Disclosure: While I have had good success with LLM's coding
-> pages and widgets with the current technical reference, as of
-> this writing all Anthropic models consistently make one serious
-> mistake in .requests.ts files.  They refresh list queries after
-> a patch, which is redundant, inefficient, and usually
-> destroys scroll position.
-
-With those four points made, a reasonable critic could still make an 
-argument that I would not care to dispute.  They may say, "Sure Ken,
-it looks like low accidental complexity to you because you wrote it,
-and you understand it, but all of those data binding attributes and
-that forced relational thinking are really just a swap of one set
-of accidental complexity for another.  The system is really
-'differently accidental' from other frameworks."
-
-I would not dispute this argument because it is more about perspective
-than measurable claims.  It is true that Loadbare forces a declarative syntax
-and "relational shaped" data.  This appears "essential" to me because
-I write database apps.  By accepting it as essential, I get performant
-apps and most of my effort is spent on the apps and not the tooling or
-boilerplate.  But if an existing stack does not easily allow the
-data to be processed into to rows and lists of rows, if the applications affordances
-do not seem to readily fit the vocabulary, then it is not a fit.
-
-In conclusion, we can see simply that Loadbare's claims around 
-accidental and essential complexity are most likely to 
-be true 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.  
-
-## Appendix: Code Shelf Life
-
-Loadbare has a benefit not stated elsewhere in the docs, because it
-really has no place to land: Loadbare app code has a long shelf life.
-
-Pages are HTML and CSS, widgets are custom elements, the server is Express,
-and the page code is queries against the application's own database.  Each of
-those is a standard or a mature tool of its own, so the code written
-today is exposed to very little framework churn tomorrow.  
-
-Every effort has also been made to scope release 1.0 so that future
-features we can imagine now can be made additive.  Consider for
-example the current practice of a monolithic `app.html` containing
-all pages for the app.  If this proves unworkable, or threatens 
-the performance budget, we can add options for alternate solutions
-that do not break existing code. 
-
-## Appendix: Provenance and History
-
-I wrote Loadbare originally in 2003, as "Andromeda", before Node existed
-and even 3 years before we had jQuery.  The foundation of Andromeda
-is now in `@loadbare/db`, the package that encodes business logic
-declaratively and frees me from the ORM and the "logic layer" in the
-application.
-
-Andromeda carried a web layer too, meant to take advantage of the
-enriched database. The conviction that led to Andromeda's UI in
-2003 was that we needed a framework optimized for database 
-applications.  I am just as convinced today as I was then, and the effort
-to provide that framework continues in `@loadbare/app`.
-
+# The Theory of Loadbare/app
+
+Loadbare has multiople opinions, but there are two co-primary drivers
+of all design:
+
+- The user should expect a median round trip of 300ms for server
+  interactions.  
+- Elegant abstractions and reimplementations of 
+  browser behavior must be avoided because they threaten
+  the performance goal, and they introduce accidental 
+  complexity. 
+
+Two early simplifying decisions were that Loadbare would use SQL
+terms, and would split server results into two shapes that are 
+best suited to a UI: a single `row` and a set of `rows`, using
+`column` for the value of a single value in a row.  Loadbare
+does not understand non-atomic column values.
+
+The framework's job then becomes to support displaying or "landing" values
+into the DOM for a given collection of the `row` and `rows` shapes. It
+also must provide the three writes, insert, update and delete, plus
+an escape hatch for bespoke operations on the server.  
+
+Loadbare implements the following opinions on declarative systems.
+- Declarative support for the data shapes and their operations
+  is easier to reason about for the developer, and greatly reduces
+  bugs in application code.
+- Framework support for declarations about SQL shapes is finite
+  and free of edge cases, allowing for creation of a robust
+  framework processor in the browser.
+
+Other opinions include:
+- It would be nice to code straight static HTML, since HTML is
+  up to the task, being mature and stable. When 
+  custom elements with light DOM are added, any bespoke behavior
+  can be supported.
+- Frameworks should not interfere with CSS
+- Code written for loadbare should run reliably on a timeframe
+  measured in decades.  As long as we have browsers, a Loadbare
+  app should run.  
+
+## The 300ms Budget
+
+The first non-negotiable primary goal is a framework where server
+round trips can run in a median 300ms, from click to paint.
+
+Of the 300ms, we allocate 200ms as typical wire time when application
+and user are in the same region, leaving 100ms for everything that
+happens in the browser, the application server, and the database.
+
+Since the database's response time is not under the control of the
+Loadbare/app framework, we realize Loadbare/app must do its job in as 
+little time as possible.  This is how we arrived at the second
+primary opinion of Loadbare/app: to avoid elegant abstractions or
+reimplementations of browser behavior that would threaten the
+performance goal.  Loadbare/app must be thin and get its job done
+in low double-digit milliseconds, leaving as much time as possible
+to the database and such tasks as authentication or picking up
+a connection from the pool.
+
+
+## Ken Random Thought, For later
+
+I often wonder if Loadbare/app does not in fact have "low accidental
+complexity" but instead has "different accidental complexity".
+
+Given the inherent complexity of the browser, any comprehensive 
+solution is going to be non-trivial, so simple measures like vocabulary
+size are not good proxies.
+
+The test, when we put something in, is whether we are following
+SQL and following HTML.
+
+For SQL, we know that we have:
+- a `row`, with landing, insert, update, and delete
+- `rows`, with landing, insert, update, and delete
+
+All of the complexity comes when we map those to HTML, and here again
+HTML has a larger surface area but it is still finite.  
+
+If we end up with 'best practices', and they look like accidental
+complexity, a bunch of stuff you have to learn, the test is whether
+a best practice already exists for HTML or SQL, and whether it makes
+sense in the combination.
+
+
+## LLM-suggested nugget, to be integrated later
+
+On the critique that Loadbare has "different accidents" than React or
+HTMX.  Scoped claim:
+
+> The data vocabulary is SQL data shapes, SELECT and DML applied to
+> HTML.  It invents no new data concepts.  Everything else is a small,
+> closed set covering what any browser app needs: navigation, request
+> status, and showing what changed between results.
+
+Supporting points:
+
+- The developer of a server-bound app must know rows, keys, SELECT and
+  DML regardless of framework.  That knowledge is essential complexity.
+  Applying it to HTML adds a mapping, not new concepts.
+- The same SQL-shape decision that limits the vocabulary keeps the
+  browser processor finite, which is what fits it in the 300ms budget.
+- The non-SQL families today: navigation (`lb-url*`, `lb-path`,
+  `lb-page*`), request lifecycle (`lb-request-*`), changes between
+  result sets (`lb-row-live/leaving/moved/changed`, `lb-group-live/leaving`),
+  and structure (`lb-hub`, `lb-exp-template`, `lb-exp-slot`, `lb-release`).
+- The accidents most likely to accumulate are in the mapping rules SQL
+  does not dictate: which element a row becomes, what a re-landing does,
+  how a key identifies an element.
+- Design rule: a new term must be a SQL concept or belong to a named
+  family.  A new family, or growth in the non-SQL families, is the
+  signal the critique is starting to land.