@loadbare/app 0.18.1 → 0.19.0

package/docs/theory.md

@@ -1,113 +1,353 @@
 # 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:
+By Ken Downs
+October 9, 2026
+
+The primary goals of Loadbare/app are performance, correctness, and
+developer ergonomics for server-bound applications.  These goals motivate
+all design and implementation decisions.  The motivations cannot be
+cleanly separated in implementation, they must all be true at once, and
+often overlap and support each other.
+
+Correctness: there is precise and perfect integrity between the database
+and the screen as of the last round
+trip.  User writes hit the database once.  Constraint violations are
+intelligible and rendered in context.  
+
+Developer ergonomics means the simplest coding path results in an
+application that is correct and performant.  Getting the right
+answer painted on the screen must be the lowest friction way to
+write the code.  This means many things, but it definitely rules
+out elegant abstractions, excessive boilerplate and housekeeping code.
+It must be difficult to express a solution that is slow or does not
+maintain integrity between database and UI.
+
+I admire elegance, but it is very dangerous when it becomes a goal
+for its own sake.  An elegant abstraction appeals from its own
+design rather than from what it does for the user: it
+hides the platform instead of mapping onto it, and it must be learned and
+serviced forever.
+
+From the user's perspective, performance is an aspect of correctness.  A 
+slow round trip leaves the user wondering if what they see is correct.  The
+ideal user experience is certainty and trust in the application, which 
+requires a cumulative experience of an expectation:reward ratio of
+exactly 1:1.  All application behaviors that create doubt and 
+confusion erode the expectation:reward ratio, and must be removed
+and made difficult to create by construction.  A slow application cannot
+provide an expectation:reward ratio of 1:1 because it is constantly
+creating doubt.
+
+## Currency is not a motivator
+
+Currency is not a motivator for 1.0.  
+By currency, we mean the screen may be updated, absent any action by
+the current user, due to the actions of other users or automated processes.
+The class of apps that require currency are different in kind from those
+that require only correctness.  Unprompted updates may even violate 
+the Loadbare/app definition of correctness.
+
+Currency can be considered when use cases present, and once it is
+reconciled to correctness.
+
+## From motivation to means
+
+With the motivations firmly established, everything after is
+technical decisions to establish the means.  
+
+This can be confusing, because sometimes a means and motivation
+look the same.  For example, I personally prefer to code static
+HTML, and would like a data-driven framework that allows that.
+It so happens Loadbare/app works that way.  But it would be a
+tedious and unproductive waste of words trying to determine if
+that was a preference, motivation or means.
+
+The three primary motivations force all design and implementation
+decisions.  All of my other preferences and motivations, such as
+low boilerplate, declarative systems, static HTML and many others
+were all worked in along the way, but always in a way that 
+supported the major three motivations.
+
+I am happy to say I think it worked.  In the sections below,
+you will see how it was done.  My own preferences and secondary
+motivations will be plain to see in the decisions, but they
+are always presented as what they are: a means to create a correct
+and performant application with high developer ergonomics.
+
+## The organizing principle
+
+Every framework needs an organizing principle that determines implementation
+decisions and the developer experience.  For Loadbare/app, a very early
+decision established that principle: Loadbare uses SQL vocabulary and
+understands two SQL data shapes: a `row` or a set of `rows`.  We speak
+of rows, columns, keys, insert, update, and delete.  We use the word
+"query" when talking about named SQL SELECT statements.  
+
+Loadbare/app does not understand non-atomic column values.  If a 
+document is retrieved from a store that embeds child rows into a 
+parent row, it must be converted into two separate query results.
+
+A relational 
+expert will quickly point out that `rows` subsumes `row` and only
+one shape is necessary, but in a UI they are not subsumed.  A form
+with its singleton form controls per column is expressed with 
+fundamentally different mechanics than a `<ul>`, `<select>` or
+`<table>`.  This is a UI framework, not a relational store, so the
+data shapes are optimized for making user interfaces.
+
+This one decision serves all three motivations.  Two shapes and three
+writes make a small and closed vocabulary, so coding the framework
+is a finite and terminating task.  For correctness, a finite task has
+no open-ended edge cases to get wrong, and because every row arrives
+with its key, the screen always knows exactly which row in the
+database it is showing.  For performance, every task the framework
+must perform is itself finite, so each one can be measured and
+optimized.  For ergonomics, a developer of a database application must
+already know rows, keys, SELECT and DML.  Loadbare/app asks them to
+map that knowledge onto HTML, not to learn new concepts.
+
+This organizing principle also guards us from creating elegant
+abstractions.  Anything new must be a SQL concept, an HTML one, or a
+member of a small, named family of things every browser application
+needs, and an elegant abstraction is none of these.  An elegant abstraction works against
+all three motivations at once: it is a place where what the developer
+wrote and what actually happens can drift apart, it adds work to every
+round trip, and it is one more thing to learn and service instead of
+the application.  That last cost is where yak-shaving begins.
+
+With this decision, Loadbare/app becomes a natural fit for SQL applications,
+and can also be used if back-end data can be formatted to the two
+shapes of `row` and `rows`.
+
+## The performance goal
+
+Because performance must be protected at all times, we need to
+get specific about that first.  All downstream decisions must know
+the target they are protecting.
+
+Research on response time gives two limits.  Near 100ms, a response
+feels instantaneous, as if caused directly by the user's action.  Near
+one second, the user's flow of thought begins to break (Miller 1968;
+Card, Moran and Newell 1983; Nielsen 1993).  Between the two, every
+reduction pays, and the payoff grows sharply below a second (Doherty
+and Thadhani 1982).
+
+A server-bound application cannot reach 100ms, because the round trip
+alone takes longer.  So Loadbare/app sets its own target: a median of
+300ms from click to paint, as close to instantaneous as a round trip
+allows, and well inside the limit where doubt begins.
+
+With a 300ms budget, we must allocate 200ms as typical wire time
+when an application and user are in the same region, leaving 100ms
+for everything that happens in the browser, the application server,
+and the database.
+
+The database's response time is not under the control of
+Loadbare/app, and neither is the application's own server work,
+such as authentication or picking up a connection from the pool.
+So Loadbare/app must be thin, and get its job done in low
+double-digit milliseconds, leaving as much of the 100ms as possible
+to the work that belongs to the application.
+
+This is where the organizing principle pays off a second time.
+Having already ruled out elegant abstractions, we extend the rule to
+reimplementations of browser behavior.  The browser already parses
+HTML, finds elements by selector, clones templates and manages focus,
+and it does those things in native code faster than any framework
+can do them again in JavaScript.  Every millisecond Loadbare/app
+spends redoing the browser's work is a millisecond taken from the
+database.
+
+## The correctness goal
+
+Performance has a number, and we can hold a stopwatch to it.
+Correctness has a definition instead, given at the top of this
+document: integrity between database and screen as of the last round
+trip, writes that hit the database once, and constraint violations
+that are intelligible and rendered in context.  We protect it by
+making wrong states hard to reach, and by refusing or reporting the
+ones we cannot rule out.
+
+The foundation is an observation about data applications.  Most
+frameworks support a DOM that is fully mutable at any time for any
+reason.  But in a data application, the screen changes for one main
+reason: the server answered with rows.  The other changes, such as a
+button waiting on its request, are a small and closed set.  So
+Loadbare/app changes the screen only from what the server sent, and
+never ahead of it.  There are no optimistic updates, and no guesses
+about what the database probably did.
+
+Because every row arrives with its key, the hub matches what arrived
+to what is shown by key, never by position.  A row that is gone
+leaves, a row that changed is filled, and a row that did not change
+is left alone, along with anything the user typed into it and has not
+sent.  An answer the server could not have meant for the current
+screen is discarded: if the user moved to another page while a
+request was in flight, the write still happened, but its answer does
+not land on a page it says nothing about.  When a query answers in a
+shape it did not declare, the page goes without it.  A page missing
+one query is better than a page showing the wrong thing.
+
+Writes hit the database once because a request comes from the
+document, not from the developer's code.  The developer names the
+request, and the hub supplies the query and key from where the
+element sits, so the developer cannot send the wrong key.  An element
+whose request is in flight ignores the next click, so a double click
+cannot become a double write.
+
+Constraints belong to the database, or to the application's own
+server code.  The framework's job is to carry the violation back to
+the user in terms they can act on.  A handler refuses a request with
+words written for the user, either for the request as a whole or for
+each column, and the browser shows them on the controls they belong
+to.  Anything else that goes wrong on the server reaches the browser
+as a plain failure, so a stack trace or a database message never
+lands in front of a user.
+
+Finally, correctness by construction.  Whatever can be checked before
+the application runs is checked, and a mistake stops the build or the
+server rather than shipping.  The builder refuses a custom element it
+cannot find and any `lb-` attribute the developer is not allowed to
+write.  The server refuses, at startup, patterns that are known to be
+wrong, and refuses any request a page did not declare, so the wire
+cannot reach anything the page has not published.  What cannot be
+checked ahead of time is reported on the console the moment it
+happens, rather than silently papered over.
+
+Each of these removes a source of doubt.  Taken together, they are
+how Loadbare/app keeps the expectation:reward ratio at 1:1 from the
+correctness side, as the 300ms budget does from the performance side.
+
+## Guarding the vocabulary
+
+A small, clean vocabulary is a means, and it serves ergonomics first.
+Every term a developer must learn that is not about their own
+application is accidental complexity, time spent servicing the tool
+instead of building the app.  A messy vocabulary also hurts
+correctness, because overlapping terms create edge cases, and edge
+cases are where the framework and the developer disagree about what
+the code means.
+
+With apologies to Brooks and Pike:
+
+> 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.
+
+A fair critic might say Loadbare/app does not have low accidental
+complexity, only different accidental complexity.  I take the
+critique seriously, and it cannot be answered by counting terms.  The
+browser is inherently complex, so any complete solution will be
+non-trivial, and vocabulary size alone is not a good proxy.  What
+matters more is where the terms come from.
+
+Most of the vocabulary comes from SQL, which a developer of a
+database application already knows:
+
 - 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.
+The rest of it comes from HTML, which they also already know.
+
+Not everything is SQL or HTML.  Any browser application also needs
+navigation, request status, and a way to show what changed between
+one result and the next.  These are small, closed families of their
+own.  So the rule is that a new term must be a SQL concept, an HTML
+one, or belong to a named family.  Any mechanism that is not
+directly serving SQL, HTML or a named family is a mistake and will, sooner
+or later, obstruct progress on the main motivations.
+
+The real complexity comes when we map SQL onto HTML.  HTML has a
+larger surface area than SQL, but it is still finite.  The accidents
+most likely to pile up are in the mapping rules SQL does not dictate:
+which element a row becomes, what happens when a row lands again, and
+how a key identifies an element.  That is where to look first when
+the framework starts to feel like something you have to learn.
+
+The same test applies to "best practices."  If we end up with a list
+of them, and they look like a bunch of stuff you have to learn, we
+ask whether the practice already exists in SQL or HTML, and whether
+it makes sense in the combination.  If it does not, it is accidental
+complexity, and the framework should absorb it or drop it.
+
+The payoff is that the whole vocabulary fits in one technical
+reference.  That means it fits in a developer's head, and in an
+LLM's context window.
+
+## Conclusion
+
+Loadbare/app is not for every application.  It fits when the data is
+rows, or can easily be shaped into rows, and when user actions
+map to reading and writing those rows.  It does not fit an
+application whose data will not take the two shapes, and it does not
+yet fit an application that needs currency.  For a database
+application, which describes a great many of the applications
+people actually use at work, I believe it fits very well.
+
+These are claims that can be checked.  Performance has a
+number: a median round trip of 300ms from click to paint.
+Correctness has a definition: integrity between database and screen
+as of the last round trip, writes that hit the database once, and
+constraint violations rendered in context.  The vocabulary has a
+rule: every term is SQL, HTML, or a member of a named family.  If
+Loadbare/app misses the number, breaks the definition, or grows past
+the rule, the theory has failed in a way anyone can see.
+
+Code written for Loadbare/app should also last.  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 in its own right, so code
+written today is exposed to very little framework churn tomorrow.
+As long as we have browsers, a Loadbare/app application should run.
+
+The same properties matter more now that much code is written by
+LLMs.  SQL and HTML are about as well represented in an LLM's
+training as anything can be, and the named families, navigation,
+request status and showing what changed, are concepts every web
+framework has.  The model already knows nearly everything, so the
+context we provide only has to spell out the mappings between them.
+That is why the vocabulary fits in one reference, and one reference
+fits in a context window.  A framework that refuses mistakes at build time and at
+startup catches the LLM's mistakes along with the developer's.  The
+correct application being the easiest one to write is just as true
+when the writer is a model.
+
+None of this is new to me.  I first wrote this framework in 2003, as
+Andromeda, before Node existed and before we had jQuery.  The
+foundation of Andromeda lives on in `@loadbare/db`, which makes the
+data correct by declaring business logic in the schema.  The
+conviction behind Andromeda's web layer was that database
+applications deserve a framework built for them.  I am just as
+convinced today, and `@loadbare/app` carries that correctness the
+rest of the way, from the database to the paint.
+
+So the whole theory comes down to this.  Loadbare/app exists to make
+a server-bound application correct, and to deliver that correctness
+fast.  The correct, fast application must also be the easiest one to
+write.  One early decision, that the framework speaks SQL and
+understands only a `row` and a set of `rows`, serves all three at
+once, and every other decision in this document is a means to the
+same end.
+
+## Appendix: Opinions, Departures and Miswarts
+
+In an imperfect world, well defined rules do not always converge to
+perfection.  Loadbare/app makes two significant
+[departures](./departures.md) from what this document implies, in
+navigation and on the wire, and a few [miswarts](./miswarts.md)
+appeared during development.
+
+The decisions in this document force some positions on the developer.
+They are listed in one place as [opinions](./opinions.md).
+
+## References
+
+- Card, S. K., Moran, T. P. and Newell, A.  *The Psychology of
+  Human-Computer Interaction.*  Lawrence Erlbaum, 1983.
+- Doherty, W. J. and Thadhani, A. J.  "The Economic Value of Rapid
+  Response Time."  IBM, November 1982.
+- Miller, R. B.  "Response time in man-computer conversational
+  transactions."  *Proceedings of the AFIPS Fall Joint Computer
+  Conference*, 1968.
+- Nielsen, J.  *Usability Engineering*, chapter 5.  Academic Press, 1993.

package/package.json

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

package/skills/loadbare-app/SKILL.md

@@ -42,8 +42,10 @@ tsc --noEmit
 `dist/pages.ts` imports page files with their `.ts` extensions, so the
 application's `tsconfig.json` needs `allowImportingTsExtensions`.
 
-Write, build, fix, and repeat until the build is clean.  Then start the
-server: `createHub` refuses a page that declares a reserved name at startup,
+Write, build, fix, and repeat until the build is clean.  The build loads
+each page's `.queries.ts` and `.requests.ts` to check the names the markup
+carries, so their import-time code runs then; open a database in
+`contextFor`, not at import.  Then start the server: `createHub` refuses a page that declares a reserved name at startup,
 and the server console reports a query that answers with the wrong kind.
 Restart the server after adding or changing a `.queries.ts` or
 `.requests.ts` file.
@@ -70,7 +72,8 @@ server.ts
 
 The chrome carries `<lb-hub>` inside `<body>`, an empty `<main>` inside the
 hub, and `<script src="/client.js" defer>`.  Everything a user touches sits
-inside `<lb-hub>`.
+inside `<lb-hub>`.  The chrome belongs to no page, so it names only the
+hub's queries, `lb-url` and `lb-choices`, and sends no declared request.
 
 A page is an HTML fragment that lands in `<main>`:
 
@@ -155,7 +158,8 @@ answers with a constant one.
 **There is no template language.**  No `{#if}`, no `v-for`, no `map()`.  A
 set of rows is an element carrying `lb-query` with a `<template>` inside it,
 the row template, which the hub clones once per row.  A `row` query with no
-row template lands on the element itself.  A `rows` query with no row
+row template lands on the element itself, and one answering `null` empties
+every column there and removes its `lb-key-value`.  A `rows` query with no row
 template lands nothing, which is what an insert form naming its query is.  A
 condition is `lb-show="<column>"`: write every possibility into the page and
 let a column decide which is present.  The column is a boolean or null; the
@@ -273,7 +277,9 @@ fetched to be edited is another page, with that row as its master.
 `crud`, keyed by query name, as `rowInsert`, `rowUpdate` and `rowDelete`.
 Each works on a `row` query as well as a `rows` query, since the element a
 `row` lands on carries its key.  Every other request name is a declared
-request, under `handlers`.  Anything undeclared is refused.
+request, under `handlers`.  The build refuses markup naming a query or
+request the page does not declare, and the server refuses one that arrives
+anyway.
 
 **An empty key is a row not yet entered.**  A `row` query answering with an
 empty key, or a form `--lb-new` pointed, carries `lb-key-value=""`.  The hub
@@ -334,7 +340,8 @@ reason.  A list shared by several handlers is a warning sign.
 one page's elements in the form they show: formatted dates and amounts, and
 the words a reader sees, such as "12 postings".  The hub does no type
 conversion, so what a number, date or null looks like is decided on the
-server.  A value the page reads back stays data: a column on a control, the
+server, or by `lb-number` and `lb-date`, which format a raw value with
+`Intl`.  Send a column the user sorts or filters raw.  A value the page reads back stays data: a column on a control, the
 key, an `lb-show` condition, a value a stylesheet selects on.  What pages
 share goes beneath them, in a database view or a helper module, never in a
 layer between the page and its queries.
@@ -457,7 +464,8 @@ own, or to act on rows once they land through the hook the hub calls,
 
 Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
 `lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`, `lb-confirm`,
-`lb-form`, `lb-insert-dialog`, `lb-master`, `lb-checkbox`.  The first four are
+`lb-form`, `lb-insert-dialog`, `lb-master`, `lb-checkbox`, `lb-number`,
+`lb-date`.  The first four are
 form-associated controls that carry `lb-column` and `lb-request`
 themselves.  Install the package and list it in `src/imports.ts`:
 
@@ -494,6 +502,5 @@ with the package, so no network is needed.
   library.
 - [`references/TECHREF-1.0.md`](references/TECHREF-1.0.md) — the reserved
   names, what a URL names and
-  [query parms](references/TECHREF-1.0.md#query-parms), and the open items
-  that block 1.0.  Read it before designing around something the other
+  [query parms](references/TECHREF-1.0.md#query-parms).  Read it before designing around something the other
   references do not mention.