@loadbare/app 0.4.0

package/docs/hosting.md

@@ -0,0 +1,218 @@
+# Hosting a Loadbare App Application
+
+Everything here is written once for an application and then left alone. None
+of it is per-page knowledge — for that, see the [Programmer's
+Guide](./guide.md), which builds a page and stops at the point where the page
+has to be served.
+
+Loadbare App ships no HTTP server, no router and no data layer. The engine in
+`@loadbare/app/server` imports one thing — its own wire types — and never
+sees a request object. So hosting is an adapter you write once, and this
+document is that adapter.
+
+Status: runs, except where marked.
+
+---
+
+## Register the page
+
+Status: partial. Nothing loads `pages/<name>.queries.ts` or
+`pages/<name>.hooks.ts` by name yet, so an application names its pages in a
+registry. `demo/pages.ts` is the demo's:
+
+```ts
+import { createHub } from "@loadbare/app/server";
+
+export const hub = createHub({
+  hello: { queries: helloQueries, hooks: helloHooks },
+});
+```
+
+`createHub` returns two functions, `dataForPage` and `runAction`. The pages
+are fixed at startup; the context is not, and arrives with each call.
+
+When the loader ships, this file disappears and the directory is the registry.
+
+## The shell
+
+The shell is the one document the server sends for every route and every user.
+It carries the chrome — whatever surrounds the page, such as a header and a
+nav — an empty `<main>`, and every page host in the application, each wrapped
+in a `<template>`:
+
+```html
+<lb-hub>
+  <header><h1>Loadbare App Demo</h1></header>
+  <nav>
+    <a href="/hello" lb-nav-link>Hello</a>
+    <a href="/counter" lb-nav-link>Counter</a>
+  </nav>
+  <main></main>
+</lb-hub>
+<template id="page-hello">…</template>
+<template id="page-counter">…</template>
+```
+
+`<lb-hub>` is the hub: a single custom element that sits above every page,
+outside `<main>`. It survives navigation, so it needs no id. It receives every
+request a widget sends, POSTs it, and applies the response.
+
+Because the shell carries no data, it is identical for every user and every
+route, which is what makes it cacheable indefinitely. Values arrive later, on
+the data channel, and land on the tree as attributes.
+
+Assembling it is a build step: read each page host, expand its widgets, wrap
+each in `<template id="page-<name>">`, and concatenate. `demo/shell.ts` does
+this at startup rather than at build time, which is a convenience of the demo
+and not the design.
+
+## Navigation
+
+Every page host already ships in the document, so navigation moves markup that
+is already there. Mark an anchor to have the hub intercept it:
+
+```html
+<a href="/entity" lb-nav-link>Entity</a>
+```
+
+The hub calls `history.pushState`, selects the host with
+`getElementById("page-" + name)`, fetches that page's data, then inserts and
+hydrates in one synchronous block. The browser does not paint mid-task, so
+there is no empty flash.
+
+Anchors without the attribute are left alone. There is no fetch on the host
+channel, no route table, and no in-flight state.
+
+The path-to-page rule is one segment. An empty path currently resolves to
+`counter`, which is demo leakage in `hub/lb-hub.ts` and should be
+configuration.
+
+---
+
+## Serving it with Express
+
+The demo runs on Express, because Loadbare App has no opinion about which server you
+bring and the community has a settled answer. The demo splits the work along
+the line that matters:
+
+| file                   | whose it is                                     |
+| ---------------------- | ----------------------------------------------- |
+| `demo/lb-routes.ts` | Loadbare App's. Every application writes this same file. |
+| `demo/server.ts`       | the demo's. Its store, its bundle, its shell.   |
+
+### Two endpoints, and no third
+
+```
+GET  /lb/data?page=<name>   the page's whole query set
+POST /lb?page=<name>        one operation, then its refresh set
+```
+
+Both names are constants — `LB_DATA_ENDPOINT` and
+`LB_REQUEST_ENDPOINT`. The page rides on the query string rather than in
+the body, which is what lets the operation set stay closed.
+
+They mount as an ordinary router:
+
+```ts
+export function hubRoutes(hub: Hub, contextFor: ContextFor): Router {
+  const router = express.Router();
+
+  // Scoped here, not on the app: the routes that need a parsed body are the
+  // routes that say so.
+  router.use(express.json());
+
+  router.get(LB_DATA_ENDPOINT, async (req, res) => {
+    const page = String(req.query.page ?? "");
+    res.json(await hub.dataForPage(page, contextFor(req)));
+  });
+
+  router.post(LB_REQUEST_ENDPOINT, async (req, res) => {
+    const { name, query, key, cell, value } = req.body as HubRequest;
+    const page = String(req.query.page ?? "");
+    res.json(
+      await hub.runAction(
+        page,
+        name,
+        { query, key, cell, value },
+        contextFor(req),
+      ),
+    );
+  });
+
+  return router;
+}
+```
+
+Note what the POST handler does not do. It does not look up a function by a
+name from the wire, and it does not read a payload. It passes a declared name
+and the addressing coordinates to `runAction`, which refuses any name the page
+did not declare.
+
+### The context is injected, because it is yours
+
+`contextFor` is a parameter rather than something the router builds, because
+building it is the one part of this that is genuinely the application's:
+
+```ts
+export type ContextFor = (req: Request) => HubContext;
+```
+
+The demo's opens the same store every time. A real one opens it for the
+authenticated caller — which is the whole reason the engine takes a context
+per request rather than holding one for the life of the process:
+
+```ts
+function contextFor(req: Request): HubContext {
+  return { db: openDb(req.user) };
+}
+```
+
+### Ordering is yours, and Loadbare App asks for one thing
+
+Express keeps one ordered list of middleware and walks it top to bottom.
+Nothing about `app.use` makes authentication run first; it runs first because
+you registered it first. Loadbare App's only requirement is the obvious one: the
+context must be built per request, after whatever establishes identity, and
+before a Loadbare App route runs.
+
+```ts
+const app = express();
+
+app.use(session(...));
+app.use(authenticate);                     // sets req.user, or 401s
+app.use(hubRoutes(hub, contextFor));   // now req.user exists
+
+app.get("/client.js", serveBundle);
+app.get(/.*/, serveShell);                 // last, or it swallows everything
+app.use(errors);                           // four arguments, last of all
+```
+
+You can scope instead of sequence — `app.use("/lb", authenticate)` covers
+both endpoints, since `use` matches on prefix and they share one. Either way
+the decision is yours; Loadbare App never sees the request.
+
+### The demo's own routes
+
+Everything below the Loadbare App mount is this application's, and would differ in
+yours:
+
+```ts
+app.get(/.*/, async (_req, res) => {
+  res.type("html").send(await buildShell());
+});
+```
+
+Every remaining route gets the same shell. The demo rebuilds it per request
+only so that editing a page host shows up on reload; it is a build step
+wearing a route's clothes.
+
+### Three things that will bite you, none of them Loadbare App's
+
+- **The catch-all must be last.** It is a route like any other, and Express
+  takes the first match. Put it above the Loadbare App mount and it answers
+  `/lb/data` with HTML.
+- **Express 5 changed the wildcard.** A bare `"*"` is no longer a valid path;
+  use a regex or `"/*splat"`.
+- **Express 4 does not catch async rejections.** An `await` that throws inside
+  a handler hangs the request rather than reaching your error middleware.
+  Express 5 forwards it. The demo is on 5 and has no `try`/`catch` anywhere.

package/docs/latent-risks.md

@@ -0,0 +1,20 @@
+# Latent Risks
+
+Issues that a single developer iterating on one app is unlikely to hit by
+accident, but that are expensive to retrofit once real usage exposes them.
+Not being built speculatively — read this when the symptom below actually
+shows up, as a prompt to come back and decide the shape deliberately.
+
+## Staleness and concurrent writers
+
+Two tabs, or two users, updating the same projection at once. A solo
+developer testing in one browser will not produce this by accident, and
+retrofitting a version or conflict check onto every tuple after the fact
+touches every widget that writes.
+
+## Nesting
+
+Whether a tuple may contain a projection (master-detail, an expanding row).
+`theory.md` already flags this as possibly load-bearing if disallowed. Worth
+a decision-in-principle the first time a master-detail page is built, even
+before the mechanism is needed elsewhere.

package/docs/theory.md

@@ -0,0 +1,226 @@
+# Theory of Loadbare App
+
+Loadbare App is a web framework that answers the author's pain points with modern
+web development: a paradoxical situation in which developer ergonomics appear
+to dominate framework architecture but we end up with developer tools that
+inflict increasing pain and expense at scale.  User
+experience, especially speed, is left as "an exercise for the reader" or waved
+away as irrelevant due to "powerful modern hardware."  
+
+The result is that it is incredibly expensive to make a web app, and the result
+is usually very slow. 
+
+The iterative effort began with Axiom Zero: The best
+developer experience is creating an application that users appreciate. 
+A framework for application development must put user needs first, and
+craft the resulting solution patterns to developer needs after the best
+user result is identified and achieved.
+
+So we begin with user experience, a fancy way of saying, "why we built this
+darn app in the first place, and what makes people likely to come back."
+Modern expectations for a web app are numerous and span multiple domains.  The
+one domain that seems to have been forgotten as inconvenient to --toy-making-- 
+developer tool forging is throughput, or performance.  Loadbare App therefore puts
+performance first, every decision must result in a performant application.
+
+This leads to Axiom 1: Performance drives all architecture.  Primary
+decisions drive performance, secondary decisions do not subvert it.
+
+## The Performance Budget
+
+Research over the past 50 years concludes that users appreciate a tight average
+of ~300ms response time from a request to a completed paint.  
+
+As the round trip is the critical path, we look at a round trip and break down
+the budget into wire 
+time, browser time, and server time.  Wire time is limited by the speed of light,
+so we pick 200ms as a strong median for a browser and server located in roughly
+the same region.
+
+With 200ms consumed on the wire, that leaves 100ms for the server and the browser.
+Within that 100ms, there is browser paint, which we control, and request handling,
+which the framework can structure, and then database response time.  Since the
+database is the one thing outside of our control, we come to a simple conclusion:
+
+> Global Requirement 1: The framework must consume as little of the
+> 100ms as possible, leaving
+> as much of the 100ms budget as possible to the database.
+
+
+## The Split
+
+Since the author knew the fat browser frameworks could never be twisted into
+shape to satisfy the ground requirements, he experimented mostly with htmx, and
+investigated dataStar, Turbo, and others.
+
+What became clear is that all modern offerings have two things in common:
+
+COMMEN ELEMENT 1: They all assume that any DOM node can be mutated, added, or
+removed at any time.  Most of the run-time expense and framework complexity
+is a direct result of this assumption.  
+
+COMMON ELEMENT 2: Their templating systems mix the shape of a response (the
+HTML/CSS and some JS for behavior), with the content of the response (the stuff
+we got from a data store, search engine, relational database or what have you).
+
+> *Note: Phoenix LiveView is the only exception I found, it was rejected
+> for reasons explained in [prior-art.md](../docs-llm-slop/prior-art.md).
+
+The final iteration, which led to Release 1.0, only got off the ground
+once the fundamental split was identified:
+
+> The UI is shipped as a static and permanent "host" for data that is supplied
+> on a separate channel.  Page navigation swaps in the page "host" code, and
+> user interaction refreshes data that the framework must push into the DOM.
+
+This split does not preclude conditional rendering or list processing, but it
+significantly changes their shape.  There are plentiful examples in the
+[guide.md](./guide.md).
+
+## Some Practical Wisdom
+
+Given a collection of ideals, a tight budget, and one lonely architectural
+decision, a few more ideas were needed to maintain alignment with Axiom zero,
+that user experience and developer ergonomics must be aligned.
+
+0. Use the fewest mechanisms that are most expressive
+1. Leverage the browser, don't fight it or supersede it.
+2. Stick with HTML, don't invent a templating system
+3. Ship example CSS, but don't force our solution path
+4. Find a sane default for shipping Javascript
+5. Use community solutions where they exist (eg, Express), 
+   don't reinvent a building block one exists that is not going
+   to chew too much of our 100ms budget
+6. The build is the developer-equivalent "speed trumps everything", the
+   fastest build has the fewest steps, and the easiest build has the
+   least configurations
+7. Prefer explicit over magic, except in the build, we do not want
+   the build to force boilerplate into the code.
+8. Authentication and Authorization should be demonstrable but are
+   squarely outside of scope.
+9. Keep architectural elements loosely coupled, but don't over-force
+   that to the detriment of a coherent solution that can be used
+   as-is. 
+10. For 1.0, create a minimal working solution whose elements can
+    be extended without fundamental refactoring.
+
+## Implementation Decisions
+
+Custom Elements with Light DOM.  Loadbare App connects javascript to HTML in
+the simplest way possible.  Custom elements and light DOM
+leverage the browser instead of fighting it, and they naturally fit
+the role of code in a tree, which is to manage itself and its descendants.
+
+A browser "hub" with two jobs.  Job 1 is to respond to navigation requests
+by swapping in the HTML "host" for the page.  Job 2 is to catch events,
+send requests to the server, and update host elements that display results.
+
+Provide a fixed set of data shapes, from cell (scalar), to a tuple (a
+single collection of cells), or a projection, a collection of tuples.
+
+Have the hub locate nodes to update with attributes like `lb-query`,
+`lb-key` and `lb-cell`.  Supplement the vocabulary with special ops
+for row deletions or adds, and both CRUD and non-CRUD requests to the
+server.
+
+A page system that organizes the HTML host template and the server-side
+code with minimal or zero boilerplate. 
+
+
+
+## Settled Implementation Approaches
+
+### Widgets
+
+A widget is an HTML custom element without Shadow DOM. Widgets compose,
+up to the level of a page.
+
+### Defining a Page
+
+A "page" is the static host of the HTML main landmark. It can be written into
+a plain old HTML document. How it is packaged, delivered and cached is settled
+in [bundling.md](../docs-llm-slop/bundling.md).
+
+We assume a page-level server-side state system.
+
+A page also has a set of declared queries in a data structure, mapped to
+the server-side state variables they require. A page GET must execute
+all queries and deliver all results.
+
+A page is a set of files sharing a basename: the host, the queries it
+declares, and the hooks it declares. The name of the file says which page
+it belongs to, so nothing inside it has to.
+
+User interactions break down into three groups:
+
+- Fire-and-forget. The user changed sort order on an HTML TABLE that
+  is smart enough to sort its own rows. It still fires a fire-and-forget
+  update to server state, so that user choice can be fetched on the next
+  page load
+- CRUD operations with hooks, declared per page: the table, the operation,
+  whatever custom code it runs, and the queries it refreshes.
+- Declared actions, for work that is not CRUD. The page names what it can be
+  asked to do and what each one refreshes. The browser sends a declared name
+  and nothing else, so the server decides every value.
+
+A hook always states which queries it refreshes. There is no automatic
+mapping from an operation to the projections it affects. The exception is a
+hook that runs before a page GET, which needs no such declaration because
+the whole query set runs after it.
+
+### Data Updates
+
+A data update can be a full hydration or rehydration of page, or a refresh of
+some elements based on a user action. In all cases, the following statements hold.
+
+We assume the host HTML is fully loaded and upgraded with JS.
+
+We define an "addressable" widget as one with custom attributes that allow the
+hub to identify which widgets are responsible for the data fragments it has
+received. A widget is addressed by three coordinates: the declared query, the
+tuple key, and the cell.
+
+A cell lands as text when it addresses a native element and as an attribute
+when it addresses a widget. A native element has no behavior of its own, so
+the value is simply its text; a widget owns whatever control it wraps, so it
+receives the value and renders it. The test is the browser's own rule for what
+a custom element is, so the hub holds no knowledge of any particular element.
+
+Projections land by method call, and tuples get no mechanism of their own.
+
+Because the browser runs `attributeChangedCallback` for attributes already
+present when a widget upgrades, hydration and refresh are the same operation,
+and hydration timing is invisible to widget code.
+
+The attribute vocabulary and the binding mechanism are specified in
+[data-binding.md](../docs-llm-slop/data-binding.md).
+
+## Open Implementation Topics
+
+Binding, addressing and the update mechanism are settled in
+[data-binding.md](../docs-llm-slop/data-binding.md). The request vocabulary is settled in
+[requests.md](../docs-llm-slop/requests.md). Packaging of the static half is settled in
+[bundling.md](../docs-llm-slop/bundling.md). Expansion of authored markup is settled in
+[expansion.md](../docs-llm-slop/expansion.md). What remains:
+
+topics to expand:
+
+- values bound to executable attributes. Markup injection is closed:
+  values are applied through the DOM and never parsed. An attribute that
+  is executable in its own right — href, src, style, on\* — is not, and
+  the first widget that binds a URL has to answer for it.
+- navigation replaces a static host rather than data, the one operation
+  that does replace host DOM. What makes something a new host versus new
+  data for an existing host is the daily modeling decision.
+- nesting. Whether a tuple may contain a projection (master-detail, an
+  expanding row). If it may not, that limit is load bearing.
+- staleness and concurrent writers. Two tabs or two users against one
+  projection. Do tuples carry a version, or is last-write-wins the
+  stated position?
+- validation placement. Per-keystroke feedback cannot afford a round
+  trip, so the budget forces some validation into the widget while the
+  server remains the source of truth.
+- the declarative path for setting a page-state variable to a literal. A
+  native element can send a declared action, because an action carries
+  nothing; a control that writes a literal directly has no markup for it
+  yet.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@loadbare/app",
+  "description": "High performance web app framework for server-bound applications",
+  "version": "0.4.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "widgets",
+    "docs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "loadbare-app-build": "dist/build/cli.js"
+  },
+  "exports": {
+    ".": "./dist/hub/lb-hub.js",
+    "./constants": "./dist/core/lb-constants.js",
+    "./types": "./dist/core/lb-types.js",
+    "./rows": "./dist/hub/lb-rows.js",
+    "./server": "./dist/server/lb-server.js",
+    "./express": "./dist/server/lb-express.js",
+    "./build": "./dist/build/elements.js",
+    "./widgets/*": "./dist/widgets/*.js"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
+    "preflight": "node scripts/preflight-release.mjs",
+    "release": "npm run preflight && npm publish",
+    "release:patch": "node scripts/bump-release.mjs patch",
+    "release:minor": "node scripts/bump-release.mjs minor",
+    "release:major": "node scripts/bump-release.mjs major",
+    "prebuild": "node --eval \"fs.rmSync('dist',{recursive:true,force:true})\" --input-type=module",
+    "build:client": "esbuild client/main.ts --bundle --format=iife --outfile=dist/client.js",
+    "build:server": "tsc --project tsconfig.build.json",
+    "build": "npm run build:server && npm run build:client",
+    "build:demo": "npm run build:server && tsx build/cli.ts --src demo --out dist/demo",
+    "dev": "npm run build:demo && (tsx build/cli.ts --src demo --out dist/demo --watch & tsx demo/server.ts)",
+    "build:demo-static": "npm run build:server && tsx build/cli.ts --src demo-static/src --out dist/demo-static",
+    "dev:demo-static": "npm run build:demo-static -- --watch & node demo-static/serve.mjs",
+    "test": "tsx --test \"tests/**/*.test.ts\"",
+    "test:golden": "UPDATE_GOLDEN=1 tsx --test tests/golden.test.ts",
+    "pretypecheck": "npm run build:demo",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "author": "Ken Downs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/kendowns/loadbare.git",
+    "directory": "packages/app"
+  },
+  "homepage": "https://gitlab.com/kendowns/loadbare",
+  "bugs": {
+    "url": "https://gitlab.com/kendowns/loadbare/-/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.1",
+    "jsdom": "^25.0.0"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^22.0.0",
+    "express": "^5.2.1",
+    "prettier": "^3.8.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/widgets/index.ts

@@ -0,0 +1,6 @@
+import "./lb-input";
+import "./lb-select";
+import "./lb-list";
+import "./lb-options";
+import "./lb-table";
+import "./lb-picker";

package/widgets/lb-input.html

@@ -0,0 +1 @@
+<label>{{label}} <input readonly="{{readonly}}" /></label>

package/widgets/lb-input.ts

@@ -0,0 +1,64 @@
+/// <reference lib="dom" />
+
+import {
+  ATTR_CELL,
+  ATTR_KEY,
+  ATTR_QUERY,
+  ATTR_VALUE,
+  LB_EVENT_NAME,
+} from "../core/lb-constants";
+import type { HubRequest } from "../core/lb-types";
+
+/**
+ * A leaf cell wrapping an <input>. The hub writes one attribute name for
+ * every widget type, so the value lands in `lb-value` and the widget
+ * forwards it to the control it owns.
+ *
+ * The other direction of the same cell: on change it sends `cell-change`,
+ * addressed by the same lb-query/lb-key/lb-cell coordinates the value
+ * arrived on. A `readonly` input never fires `change` from user input, so a
+ * readonly cell sends nothing on its own.
+ */
+class LbInput extends HTMLElement {
+  static observedAttributes = [ATTR_VALUE];
+
+  attributeChangedCallback(_name: string, _old: string, value: string) {
+    const input = this.querySelector("input");
+    if (!input) {
+      console.error(`lb-input: no <input> to receive the value`);
+      return;
+    }
+    input.value = value;
+  }
+
+  connectedCallback() {
+    this.addEventListener("change", () => {
+      const input = this.querySelector("input");
+      if (!input) {
+        console.error(`lb-input: change with no <input>, ignoring`);
+        return;
+      }
+      const query = this.closest(`[${ATTR_QUERY}]`)?.getAttribute(ATTR_QUERY);
+      const key = this.closest(`[${ATTR_KEY}]`)?.getAttribute(ATTR_KEY);
+      const cell = this.getAttribute(ATTR_CELL);
+      if (!query || !key || !cell) {
+        console.error(
+          `lb-input: change with no query/key/cell coordinates, ignoring`,
+        );
+        return;
+      }
+      const detail: HubRequest = {
+        op: "cell-change",
+        query,
+        key,
+        cell,
+        value: input.value,
+      };
+      this.dispatchEvent(
+        new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }),
+      );
+    });
+  }
+}
+
+customElements.define("lb-input", LbInput);

package/widgets/lb-list.html

@@ -0,0 +1 @@
+<div lb-slot></div>

package/widgets/lb-list.ts

@@ -0,0 +1,21 @@
+/// <reference lib="dom" />
+
+import type { Projection, HubRowHost } from "../core/lb-types";
+import { applyRows } from "../hub/lb-rows";
+
+/**
+ * The plain repeater: whatever the page author wrote inside is repeated once
+ * per tuple, in the order the server sent.
+ *
+ * It exists because a projection has to land on a widget, and because a
+ * `<table>` cannot be one — a custom element written inside `<tbody>` is
+ * discarded by the parser, so the widget goes around the table and the
+ * template goes inside it, where the content model already allows it.
+ */
+class LbList extends HTMLElement implements HubRowHost {
+  acceptRows(result: Projection) {
+    applyRows(this, result);
+  }
+}
+
+customElements.define("lb-list", LbList);

package/widgets/lb-options.html

@@ -0,0 +1,4 @@
+<label
+  >{{label}}
+  <select lb-slot></select
+></label>