@loadbare/app 0.7.3 → 0.8.0

package/docs/theory.md

@@ -1,53 +1,68 @@
 # Theory of Loadbare App
 
-by Ken Downs, August 29, 2026.
-
-Loadbare is one man's answer to the extreme expense and slow performance
-of modern web apps.  When using modern frameworks, it seems to me that
-they are composed entirely of accidental complexity, I seem to be always working
-for the tools instead of the other way around.
-
-I wanted a new way to develop web apps that reduced accidental complexity
-as far as possible to zero, and gave me snappy performant apps.
-
-This essay describes the analysis and conclusions that led to the
-design and implementation of the Loadbare application layer.
+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
 
-First I had to find my way out of the cruft that clutters
-the front end discussions of today, and establish a "Principle zero" that
-could be a starting point.  This is it:
+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 why we do what we do.
+concerns, grounding any solution in the desire to make a useful application.
 
-This principle also
-pre-empts arguments for seemingly elegant abstractions and tooling that
-cannot be obviously and easily shown to contribute directly to an
-application that end users use and appreciate.
+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,
+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. 
-
-It seems to me that the front end industry, as represented by the
-fat browser frameworks, has abandoned performance completely.
+web apps: they are so damn slow.
 
-I wanted to put performance front and center, and design around
-it instead of optimizing for it later.
+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 
+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 persitence to final
+> 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
@@ -56,414 +71,728 @@ 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.
 
-But we do have a practical implication: if we have a 300ms budget,
+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 non-db server activity must
+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 of the 100ms as possible to the database.
+as much as possible of the 100ms to the database.
 
-## The Primacy of Essential Complexity
+## 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".  These terms have since been glossed into
-"essential complexity" and "accidental complexity", and I will
-use the complexity versions to be intelligble to the casual reader.
+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 to being vanishingly small.
+the problem.  We want to minimize this, always pushing to zero.
 
-Because I believe there is some objective truth to my subjective feeling
-that the fat browser frameworks have become nothing but accidental complexity, 
-it seemed necessary to state the princple of the Primacy of 
-Essential Complexity, which borrows phrasing from both Brooks and
-Pike to establish that:
+So, with apologies to Brooks and Pike, here is my mash-up and restatement
+of their ideas, tuned to the current task:
 
-> Essential Complexity Dominates.  Show me your abstractions and tooling and
-> I shall remain mystified.  Show me your tables and your visual vocabulary
+> 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 stated above, once articulated, allowed me to
-clarify my rejection of the fat browser frameworks: nowhere do they
-state the same motivations that I have, and their illustrations and
-examples make clear their motivations are irrelevent to mine and
-vice-versa.  In fact, my
-extensive experience with React, Angular and VueJS contributed to 
-my articulation of these principles, the principles state what I found
-lacking in the fat browser frameworks.
+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
+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 do not blame the hypermedia libraries, I think I was
-fighting them.  But that simply told me we differed on an assumption,
-and that assumption remained unidentified and unstated. 
+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
 
-It turns out that all of the tools and frameworks I could find are
-supporting something I don't need: a DOM that is fully mutatable at
-any time, for any reason deemed necessary by the developer.  They
+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.  All of them must chase down the
-consequences of the decision to allow a fully mutatable DOM.  Those
-consequences spill into the usage and tooling around the frameworks
-and libraries.  The arbitrarily mutatable DOM was the source of my
-intuitive sense that I was dealing with too much accidental complexity.
-
-## The Loadbare Split
-
-Finally I had the foundational idea for a framework that splits code
-between a static "host" application and an active data channel, with
-some small framework library updating only data values in the DOM
-by following data-binding attributes in the HTML.
-
-(As a side note, I originally considered calling Loadbare "liveload"
-to draw the association to a bridge.  The static HTML is the bridge,
-the data that refreshes the page is the "live load" (traffic) travelling
-on it.  Alas, it seemed too close to 'livereload' and I gave it up.)
-
-The static host application is pure HTML, including custom elements
-with Light DOM.  User interactions send requests to the server which
-returns data objects.  The HTML contains attributes identifying how
-elements are bound to data, so the framework can update them.
-
-This should be self-evidently efficacious for scalar cells and
-rows.  Something like `<span lb-row="siteStats" lb-cell="visitCount"></span>`
-or the same type of addressing for an input makes it trivial to 
-both hyrdrate and refresh forms, and to gather a form's values
-to send to the server.
-
-List processing, such as for an HTML SELECT and complex tables took a bit
-longer to figure out, but the principle could be extended.  Any list
-element can accept a `<template>` that describes how to build its 
-items.  The data channel must expand to allow "patch" operations,
-removing or adding one row instead of reshipping the entire 
-query, but that is also straightforward.
-
-So a purist might say, "hey you are still manipulating the DOM".
-Of course we are, it is an application, not a static site.  But the
-point is that the HTML can be written, read, and reasoned
-about as a static artefact, while still being dynamic at runtime.
-
-The model can also be extended for trees, but my current projects
-do not require this, so it is not implemented as of this writing.
-
-## Choosing the Mechanisms
-
-So now I had three principles and one architectural decision that 
-seemed to make it all possible. The next step was to pick the
-fewest number of mechanisms that would work.  
-
-On the benefit side, the fewer mechanisms there are the easier
-it would be to create the solution and to use the solution.  Fewer
-mechanisms makes for a system that is easier to learn, and easier
-to teach to an LLM.
-
-On the cost-avoidance side, each mechanism is
-an invitation to accidental complexity around the use of the
-mechanism, so they must be kept at a minimum. 
-
-### Browser Application Code
-
-Using plain HTML, extended with custom elements that do not use Shadow
-DOM has so far, apparently, completely solved the browser for me.
-
-In my humble opinion,
-Javascript belongs in the browser to enhance default behavior, and
-the enhancements ought to always be scoped to a custom element and
-its children.  A custom element neatly satisfies this.  
-
-Custom elements give an nice answer to the question, why can't we just
-use HTML like we used to?  The Loadbare answer is: you can, go ahead.
-If you need something special, make a custom element, it is still
-just HTML.
-
-A simple builder also gives server-side HTML includes for free with
-no extra syntax.  The builder scans for one fixed file (the chrome),
-and all pages.  Anywhere a custom element is found, it looks for
-an HTML file to match, and inserts it into the built HTML.  This is recursive
-of course.
-
-The builder became "tree shaking" for free.  During HTML assembly
-and composition, any Typescript file whose name matches a custom
-element that was actually used gets added to the monolithic 
-`client.js`.  No import statement required.  The Loadbare code is 
-loading no extra Javascript outside of the single `client.js` named
-in the main HTML document.
-
-The validation during a build also fell out for free: if a custom
-element is used, it must have either a matching Typescript file
-or a matching HTML file, or both.  The only error is if neither
-are present.
+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`
+
+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
 
-For the hub to know what data to apply where and how, we need 
-custom attributes on the HTML.   It was possible to define a small
-and coherent vocabulary because the actual number of operations
-afforded by a database is small and coherent.
-
-### Browser Framework Code
-
-The entire browser framework code is in the hub `<lb-hub>`, and its
-only real job is to handle page navigation and the data channel.  
-
-It also contains addressable methods to update DOM elements with
-data objects, so that custom elements do not have to reproduce that
-code.
-
-### Application Server Code
-
-For server page code, this is where we truly got accidental complexity
-to zero.  A page is just its HTML, its queries, and its request handlers.
-
-For the Express server, I was rather surprised myself to find that the
-simplest thing was to show example code for an Express server.  Nowadays
-most frameworks provide their own Express server that is so completely
-invisible that a newcomer to the industry can be forgiven for not even
-knowing that Express exists.  I wondered if pushing this concern to the
-dev team violated the Principle of Essential Complexity, but I really
-don't think so.
-
-The reasoning for not providing a shrink-wrapped
-server is simple: the boilerplate code is one-time effort, and the dev
-team will need to add in their own database handler, security and 
-other concerns.  A one-time effort may be seen as accidental 
-complexity to a skeptic, but its one-time set up means it is not a 
-continual tax being paid every time you write a new page.  It is that
-sense of paying an ongoing tax that I'm really trying to avoid.
-
-### The Database
-
-Database concerns are mostly out of scope for the application layer,
-but we must make mention of them because Loadbare is supposed to
-be optimized for database apps.
-
-Loadbare satisfies the minimal principle of not being rude by not
-requiring a specific database, neither prohibiting nor requiring
-the ORM of your choice if you use one.  
-
-However, I should mention that I personally always use
-the `@loadbare/db` package to build
-my databases, which enriches them with calculated values that are
-declarative in the Loadbare db schema.  For this reason, I need no
-ORM because the access patterns are very simple: most database reads
-come from one table or a fairly simple view, and user actions that
-update a single table automatically cascade calculations 
-to related tables.  For this reason, I do not need an ORM and
-my `@loadbare/app` applications connect directly to the database
-with no "business logic" code at all.
-
-I must also state that a team not using `@loadbare/db` will probably
-use an ORM or craft a business logic layer, and `@loadbare/app` does
-nothing special for this.  It simply provides the empty slot where
-you plug it in.
-
-### The Builder
-
-The builder kind of fell out for free from the architecture and 
-mechanism choices.
-
-In addition to what was noted above, it is a very straightforward
-piece of code: it walks the `src/` tree, requiring only a 'chrome.html',
-and picking up all '*.page.html' files.  It builds one Javascript file,
-one CSS file, and one HTML file.  Having the files be sparse, containing
-only what was used, is trivial.
-
-It also builds the application's API from the page's processing
-code, and 4 lines in the Express server end up handling the entire 
-API.  
-
-In short, the builder satisfied the Principle of Essential Complexity, that
-if the code is organized around just application concerns, the builder
-algorithm is self-evident, straightforward, and easy to decorate with
-nice-to-haves.
-
-## Assessing the Result
-
-I am a biased examiner, but I can say that `@loadbare/app` solves mutliple
-problems for me and achieves compliance with the principles stated
-at the top of this essay.
-
-The Principle of Developer Experience says my goal is to make something
-that users actually use and appreciate.  Loadbare cannot do that for me,
-but it does free me from so many accidental concerns that my time is 
-free to pursue that quality application.  It reduces the cost of iteration
-and increases my ability to focus on the shape of the solution. That is
-as much as I can ask for from a productivity tool.
-
-In terms of the Principle of User Experience, that we must complete
-round trips from click to paint in a median time of 300ms, Loadbare gives
-me a better chance of doing this than any other tool I have seen.
-The Loadbare app is so light and does so little that if we allow a median
-time of 200ms for wire time, Loadbare likely needs 10ms or less between
-the browser and the server, leaving 90ms for the database and business
-logic.  Making the budget in production can be reduced to careful modeling,
-tuning, and hardware spend.  (Note: using `@loadbare/db` makes this almost
-a guaranteed win, provided we don't skimp on hardware and know how to tune
-Postgres for production).
-
-Finally, in terms of the Primacy of Essential Complexity, I may be a biased
-examiner.  Because I wrote it, I see zero accidental complexity, inasmuch
-as everything seems to be there to serve the major principles.  But I cannot
-trust my judgment there for obvious reasons.  Instead I will propose that
-there are some reasonably obvious wins for Essential Complexity that even
-a skeptic might agree with.
-
-One big win is the ability to just write plain HTML.  Mixing HTMl and
-Javascript seems cool if you need a fully mutatable DOM, but when you realize
-you don't need that, it's back to plain old reliable HTML.
-
-Another big win is the server code for pages.  The clean organization
-of requests, actions, CRUD and queries without boilerplate is pure
-Essential Complexity.  The automatic building of the API and 4 lines to
-handle it in Express is lower than I have seen in any other tool.
-
-Loadbare satisfies many other principles that do not merit a full explanation,
-such as using technology instead of fighting it, organizing the use of
-browser mechanisms instead of reimplementing them, and encouraging code
-that is likely to have a very long shelf life.  Loadbare does not
-interfere with normal CSS usage, so you can bring any solution you like.
-
-In closing I would add one more claim.  Loadbare is easy to learn because
-it has a small cognitive surface area.  The main activity, coding pages,
-is highly repetive and driven by a handful of patterns.  It can be learned
-by a person and taught to an LLM with just a few skills.  
+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 four foundations:
+
+| Attribute | Relational idea | HTML precedent                                     |
+| --------- | --------------- | -------------------------------------------------- |
+| `lb-list` | A set of rows   | `<select>` or `<ul>`, a container of its items     |
+| `lb-row`  | A single row    | `<form>`, one record of fields                     |
+| `lb-cell` | A column        | `name` on a form control, which field this is      |
+| `lb-key`  | The primary key | `value` on an `<option>`, identity apart from text |
+
+A highly simplified page showing
+an invoice and its lines looks like this:
+
+```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></tr>
+    </template>
+  </tbody>
+</table>
+```
+
+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-action`.
+Three values are reserved, and any other value is interpreted as the
+name of a routine on the server.
+
+A request is an action and a position.  The author writes the action,
+and the hub supplies the position from the document, using the same
+ancestor rule that decides where a value lands.  To add a delete
+button to the invoice lines from the previous section, the template
+gains one element:
+
+```html
+<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>
+```
+
+The button names neither the list nor the key.  When it is clicked,
+the hub reads `invoiceLines` from the nearest list scope and the key
+from the live row around the button, and sends:
+
+```
+{ action: "lb-row-delete", list: "invoiceLines", key: "42" }
+```
+
+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 writes three attributes about a request, `lb-pending`,
+`lb-error` and `lb-row-count`.  The framework browser code ignores
+a button or form performed again while stamped with `lb-pending`,
+meaning the disabled state can be represented entirely by CSS, no
+JavaScript needed.
+
+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-nav-link`.  If so, the hub interprets it as in-app
+navigation, swaps the anchor's `href` into `<main>`, and sends a request
+to the server for the page data.
+
+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
+navigation state, we had it publish a syntheic query result,
+`lb-navigation`, that contains the URI and, if it can find it,
+the anchor text for any link to that URI.
+
+These can be bound to any HTML, same as any other query sent by
+the application, but the resulting values are always supplied by
+the hub.
+
+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 as a row or a list, the same two shapes the
+HTML binds to.  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, where) => {
+          await ctx.db.deleteLine(where.key);
+          return { invoiceLines: patch({ drop: [where.key] }) };
+        },
+        refresh: ["invoice"],
+      },
+    },
+  },
+};
+```
+
+Deleting a line changes the invoice total, so the entry refreshes
+`invoice`.  The list 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 both: 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 scopes an `lb-row-delete` to `lb-list="invoice_lines"`, then the
+server carries a CRUD entry `rowDelete` under object invoiceLines.
+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 actions, 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 4 years before we had JQuery.  Andromeda was not nearly as
-optimized as Loadbare is now, but the principles were the same then as 
-they are now.  It has always worked for me, and I hope that it will work
-for you.
-
-## A Consistency Model
-
-> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
-> 2026-09-13, from a design session against `@loadbare/app` 0.6.0.  Treat
-> it as a proposal for this essay, not as the author's statement.
-
-### From a subjective claim to a checkable one
-
-Whether Loadbare carries less accidental complexity than another tool will
-always be disputable.  A developer fluent in React has muscle memory for its
-rules and will see Loadbare's rules as foreign, and foreign work feels
-accidental.  That objection is about familiarity, and familiarity is a cost
-paid once, in the same way this essay treats the Express boilerplate.
-
-A stronger claim can be checked, and a single counterexample in markup
-would refute it.  The model for applying data to HTML is:
-
-1. **Internally consistent.**  A few rules, each applied the same way
-   everywhere, with no exceptions.
-2. **Consistent with HTML.**  Each rule has a counterpart in how HTML
-   already behaves, and none contradicts it.
-3. **Consistent with relational data.**  What the server sends is the shape
-   a SQL query already returns, so nothing is translated on the way.
-
-### Where the vocabulary comes from
-
-This essay says the vocabulary is small because the operations a database
-affords are small and coherent.  A sharper statement is that the vocabulary
-sits where two systems that are already coherent meet: the relational model
-and HTML's containment model.  Each attribute is a relational idea placed on
-an element.
-
-| Loadbare                                 | Relational                                   | HTML precedent                                               |
-| ---------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
-| `lb-list`                                | a relation, a set of rows                    | `<select>`, `<ul>`: a container whose contents are its items |
-| `lb-row`                                 | a single row                                 | `<form>`: one record of fields                               |
-| `lb-cell`                                | a column                                     | `name` on a control: which field this is                     |
-| `lb-key`, `lb-key-value`                 | the primary key                              | `value` on `<option>`: identity apart from the label         |
-| `lb-action`                              | a closed set of writes, and named procedures | `action` on `<form>`: where a submission goes                |
-| scope from ancestors                     |                                              | form ownership, `lang`, `<fieldset disabled>`                |
-| a nested scope begins a new one          |                                              | a nested element owns its own contents                       |
-| `lb-row-count`, `lb-pending`, `lb-error` |                                              | state attributes such as `open` on `<details>`               |
-
-### The rules
-
-1. **An element's own attributes describe what it displays.  Its ancestors
-   describe where it belongs.**  A picker carrying `lb-list` displays that
-   list, and its choice is addressed to the row it sits in, the way a
-   `<select>` displays its options and submits to the form around it.
-2. **A name answers with one shape, a row or a set of rows, and a cell holds
-   one value.**  Master-detail is a row and a list under two names.  Many
-   masters with their details is one list of joined rows, grouped for
-   display.
-3. **A value lands where the element shows its state, and a form gathers
-   from the same places.**  A widget receives `lb-value`, a form control its
-   `value`, and any other element its text.
-4. **A request is an action and a position.**  The hub supplies the position
-   from the document.  Only an interaction supplies a value.
-5. **The hub owns position and reconciliation.  A widget owns interaction and
-   placement.**
-
-### Evidence
-
-The following decisions each removed an exception or a conflict, and none
-added an attribute.  Over the same span the model gained pickers inside rows,
-native selects that show their own state, and nested lists that do not
-destroy each other.
-
-| Decision                                                      | Removed                                                                              |
-| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| The hub scopes every request                                  | Native requests were scoped and widget requests were not                             |
-| Scope comes from ancestors, never the element's own `lb-list` | `lb-list` meant "display" in one place and "address" in another                      |
-| A form control receives its value as `value`                  | A `<select>` was treated as text, against HTML, and landing did not mirror gathering |
-| Row and template lookups stop at a nested scope               | Cells respected nesting while rows and templates did not                             |
-| Master-detail is a row and a list                             | An open question born of document-shaped data                                        |
-| `lb-value` on every cell                                      | Only a widget's landed value was visible to a stylesheet                             |
-| An insert or update gathers its form or row \*               | What sat beside a button decided what was sent                                       |
-| Gathering finds cells the way landing does \*                | Gathering read into nested scopes, and an element that was both a scope and a cell was gathered but never landed on |
-
-\* LLM-authored change, not yet reviewed by the author.  Added by Claude on
-2026-09-13: `lb-row-insert` and `lb-row-update` gather the nearest `<form>`,
-`<tr>` or live row inside their scope, rather than the nearest element
-holding a cell.  Gathering and landing then share one test for which cells
-belong to a scope, judged from the element's ancestors and never its own
-attributes, following the first rule.
-
-Two signs suggest these are rules rather than patches.  Fixing where a
-request's scope comes from also fixed an unrelated console error about insert
-forms, which was never worked on directly.  Making rows respect nested scopes
-needed no change to the reference, which already described that behavior.
-
-### Where the claim is not yet proven
-
-- **Parameters and view state.**  A query takes no argument from the
-  browser, so there is nowhere to put which record is selected, a filter, a
-  sort, or a collapsed section.  The model is incomplete here rather than
-  inconsistent.  If the answer is HTML's own, the URL, in the way
-  `<form method="get">` puts its fields in the query string, the claim grows
-  stronger.  If it needs a state mechanism with no HTML precedent, that will
-  be the model's first real exception.
-- **Checkboxes and radio buttons.**  HTML's boolean convention is presence or
-  absence, as with `checked`, `hidden` and `disabled`.  A rule following it
-  would avoid inventing truthiness, though it still touches data types.
-- **Data types.**  HTML attributes are strings, so comparing values as strings
-  in a stylesheet is consistent with HTML.  What is not yet reconciled is
-  that a database's typed values arrive untyped.
-- **A nested list shows the same rows in every outer row.**  That follows
-  from the second rule: one name is one relation.  Only a new outer row
-  starting with an empty nested list is a mechanical gap.
-
-### A test for every change
-
-Before a change is made, ask:
-
-- Does it remove an exception, or add one?
-- Does it have an HTML precedent?
-- Does it have a relational counterpart?
-
-Stamping every column of a row onto the row element as `data-*` fails the
-first two: attributes nobody wrote, with no precedent in HTML.  Writing
-`lb-value` on every cell passes all three.
+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`.
+