@loadbare/app 0.18.2 → 0.19.1

package/docs/testing.md

@@ -1,5 +1,9 @@
 # Testing
 
+> LLM-authored and LLM-maintained.  This is acceptable because the
+> document is fact-based, describing tests that exist in this package, and
+> is written to be consumed by an LLM working on the package.
+
 A contributor's document, and a companion to [theory.md](./theory.md). It
 describes how this package tests itself.
 
@@ -26,6 +30,23 @@ All four tiers run under `npm test` today and need no dependency that is not
 already installed. A fifth environment — a real browser — is discussed at the
 end and is not built.
 
+## What the tests are evidence for
+
+[Theory](./theory.md) makes three claims that can be checked, and this suite
+carries evidence for two of them.
+
+- **Correctness.**  Most of what Theory's correctness section names is
+  tested here: rows landed by key, an unchanged row left alone with what the
+  user typed, an answer in the wrong shape left out, a write sent once, a
+  refusal shown on the controls it names, and a server that refuses what a
+  page did not declare.
+- **The vocabulary rule.**  The markup checks in tier 1 enforce it at build
+  time: an `lb-` attribute outside the set the developer writes is a build
+  that fails.
+- **Performance.**  No tier measures the 300ms round trip.  Node and jsdom
+  have no network and no paint, so they are not evidence for it, and this
+  suite does not try.
+
 ## The runner
 
 `node:test`, run through `tsx`:
@@ -78,17 +99,14 @@ the most of what Loadbare promises, so it is first.
 - more than one `lb-exp-slot`
 
 **Markup checks.** The assembled chrome and every page are checked before
-anything ships:
-
-- an `lb-` attribute that is not one the developer writes
-- `lb-request="lb-…"` naming none of the requests Loadbare provides
-- `lb-url-link` off an `<a>`, `lb-url-push` without `lb-request`, and
-  `lb-url-unknown` off a `<dialog>` or outside `<lb-hub>`
-- `lb-show` on a `<template>`, on a row template's root, or with no row
-  around it
-- a chrome without exactly one `<lb-hub>` and one empty `<main>` inside it,
-  and a page carrying either
-- a widget script declaring an `lb` method Loadbare does not define
+anything ships, against the list in
+[The markup checks](./reference/data-binding.md#the-markup-checks).  Each one
+is a build that must not produce output.  The checks of `lb-query` and
+`lb-request` names take each page's declarations as `loadDeclared` reads
+them, and `loadDeclared` is tested against real page modules: names read
+off objects built with spreads and computed keys, nothing declared for a
+page with no modules, nothing left in the output directory, and a module
+that throws named in the error.
 
 A page file's `<title>` is lifted out and stamped as `lb-page-title`.
 
@@ -118,7 +136,7 @@ Review the golden files rather than blessing them. `npm run test:golden -w
 @loadbare/demo` rewrites them; the diff is the point, and a diff nobody read
 is a test nobody ran.
 
-The rest of the build — `assemble`, `elements`, `pages`, `styles`,
+The rest of the build — `assemble`, `declared`, `elements`, `pages`, `styles`,
 `package-css` — is tested the same way and in the same tier, since none of it
 needs a browser either.
 
@@ -126,7 +144,7 @@ needs a browser either.
 a temporary project, which carries a stand-in `@loadbare/app` pointing at
 the hub's source so the test needs no prior build.  It is tested for its
 default `src` and `dist`, every file it writes, `--minify`, a failed build's
-exit code, and `--watch` rebuilding on a change, skipping a file it does not
+exit code, a name the page does not declare, and `--watch` rebuilding on a change, skipping a file it does not
 watch, and surviving a failed build.
 
 ## Tier 2 — The engine
@@ -149,11 +167,22 @@ watch, and surviving a failed build.
   operator away from silently reversing
 - a handler returning `url()` answers with the `lb-url` item alone, and runs
   no refresh set
+- a `row` query that finds no row answers `null`
+- at startup, a malformed order, an unknown column type, and a crud request
+  that refreshes its own `rows` query are refused
+- an update or delete for several rows runs once per key, lays the patches
+  together, and refreshes once
+- `onPageEnter` may return `url()` or `choices()`, and `onChoices` hears
+  every choice the user makes
+- a refusal carries a message, columns or both, and passes through the
+  engine untouched
 
 `tests/lb-express.test.ts` runs against a listening app: the page comes from
 the path, the query parms reach `contextFor`, a `url()` answer is followed by
-the page loaded at the new URL, an undeclared request is refused, and a
-malformed body does not throw.
+the page loaded at the new URL, an undeclared request is refused, a
+malformed body does not throw, an oversized body is refused, a refusal
+answers 422 with its words, and any other throw answers 500 with nothing in
+it.
 
 ## Tier 3 — Landing
 
@@ -187,6 +216,10 @@ evidence here.
   groups and leaving them out of counts and aggregates (`lb-choices.test.ts`)
 - `lb-show` moves an element into a template and back, and landing reaches
   inside it
+- a row whose values arrive as it already shows them is not filled again,
+  so what the user typed into it stays
+- a `row` query answered with no row empties the columns it names and drops
+  its key
 
 Two properties, written as loops rather than with a library. Applying the
 same rows twice is applying them once. And rows reached through any sequence
@@ -252,6 +285,17 @@ What the hub is tested for here:
   loaded there
 - `hidden` comes off the body once a page has landed, including the page
   that failed to load, and a link whose page fails to load marks no element
+- an answer that returns after the user has moved to another URL does not
+  land
+- focus goes to the first element the user can operate once a page's
+  queries land
+- a form pointed at a row by `commandfor` fills from the row the hub holds,
+  and a row not yet entered sends no update or delete
+- ticked `lb-select` rows travel as `keys`, and the selection clears once
+  the request succeeds
+- a refusal lands its message on the element that committed and on each
+  control it names
+- `lb-request-done` reaches the element that committed and its ancestors
 
 Widgets are small and their logic is local, so jsdom carries them: a value
 reaches the control the widget owns, the widget is a form-associated control
@@ -282,18 +326,8 @@ No browser test runner is installed and none of the following exists. They
 are recorded here as the shape of the work, not as coverage:
 
 1. a cold load fills `<main>` with no empty flash
-2. the wizard never displays a step the server has not confirmed
-3. the view-source invariant
-
-The last is the one worth a browser. Loadbare's central claim is that no
-markup exists in the DOM that is not in view-source, and that the difference
-between the two is exactly the dynamic half. That is a property, it is stated
-precisely in [theory.md](./theory.md), and it should be enforced mechanically
-rather than believed: fetch the shell as text, compare the element set
-against the live document after interaction, and assert that the only
-additions are clones of row templates.
-
-See [TODO.md](../TODO.md) for this and the rest of the open work.
+2. the wizard page in `@loadbare/demo` never displays a step the server has
+   not confirmed
 
 ## Continuous integration
 
@@ -307,7 +341,7 @@ tiers here stay fast enough to run on every save.
 ## One change the tests want
 
 The client reports through `console.error` and `console.warn` directly, from
-roughly twenty places across `hub/` and `@loadbare/widgets`. Routing those through a
+more than twenty places across `hub/` and `@loadbare/widgets`. Routing those through a
 single `report()` in `core/` would give the tests one seam to observe instead
 of a global to mock per file, and would put the framework's error channel in
 the same file as the rest of its vocabulary. It is a small change and it is

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/docs/tutorials/040-displaying-data.md

@@ -130,7 +130,7 @@ requests to the correct page code.
 import express from "express";
 import { readFileSync } from "node:fs";
 import { hubRoutes } from "@loadbare/app/express";
-import { hub } from "./dist/pages";
+import { hub } from "./dist/pages.ts";
 import { openDb } from "./src/database";
 
 const app = express();