@loadbare/app 0.18.1 → 0.19.0

package/docs/what-does-loadbare-extend.md

@@ -1,124 +0,0 @@
-# What Does Loadbare Extend?
-
-> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
-> 2026-09-27 against `@loadbare/app` 0.10.0.
-
-The question: what is `@loadbare/app`'s foundation, the thing it adds to
-rather than replaces, and does the package stand on that foundation the way
-`@loadbare/db` stands on Postgres?
-
-The short answer: the browser half of `@loadbare/app` is honestly "HTML+", in
-the same way `@loadbare/db` is "Postgres+".  The package as a whole is not.
-The framing that covers all of it, and ties it to db, is relational rather
-than HTML.
-
-## The precise reading
-
-### Where "extension to HTML" is literally true
-
-- **It uses the platform's own extension point.**  Custom elements are how
-  HTML is meant to be extended.  The whole browser runtime is one custom
-  element, `<lb-hub>`.  Custom elements are also the only way Loadbare lets an
-  application split up markup or ship behaviour.  There are no components, no
-  JSX, and no expressions evaluated at run time.
-- **The attributes copy HTML's own ideas.**  [Theory](./theory.md#data-binding)
-  already sets this out in a table:
-  - `lb-column` works like `name`.
-  - `lb-query` works like `<form>` or `<select>`, a container of records.
-  - `lb-show` works like `hidden`.
-  - `lb-key-value` works like an `<option>`'s `value` sitting apart from its
-    text.
-- **HTML decides behaviour wherever it already has an opinion.**  Commits
-  follow HTML's events: a form on submit, a control on change, anything else
-  on click.  Gathering follows the form owner, including `form="…"`.  Resets
-  go through `formResetCallback`.  Busy state uses `aria-busy`.  The unknown
-  page is a real `<dialog>`, and links are real `<a href>`.
-- **What ships is plain HTML.**  It can be read in view-source, it uses light
-  DOM, and CSS is left untouched.  A page that shows no data is just an HTML
-  file.
-- **There is historical precedent.**  IE4's `datasrc`/`datafld` really was
-  data binding added to HTML, and [Prior art](./prior-art.md) finds its
-  vocabulary maps almost one to one onto Loadbare's.
-
-### Where it is inaccurate or strained
-
-- **The attributes don't conform to the spec.**  HTML sets aside `data-*` for
-  author attributes, and a validator will flag `lb-*`.  htmx and Alpine have
-  the same problem, so it's defensible.  But a literal claim of "extension to
-  HTML" is only half true: Loadbare uses one of the sanctioned extension
-  points (custom elements) fully and skips the other (`data-*`).
-- **Build-time expansion is a preprocessor.**  `exp-` parameters and `{{…}}`
-  are a small template language that runs before HTML exists.  The output is
-  HTML; the source a developer writes is not quite HTML.
-- **Navigation overrides HTML's model on purpose.**  HTML's model is one
-  document per URL.  Loadbare ships every page as a `<template>` in one
-  document and answers every route with `app.html`, with no 404.  Keeping the
-  address bar truthful softens this, but it is still a replacement.
-- **The wire is JSON, not hypermedia.**  In the ecosystem, "extends HTML"
-  usually means htmx's argument that HTML is unfinished hypertext.  Loadbare
-  rejects that model after the first load.  Calling it an HTML extension
-  invites exactly the comparison [Theory](./theory.md) spends paragraphs
-  getting out of.
-- **Half of what a developer writes isn't HTML.**  `queries.ts` and
-  `requests.ts`, with `row`/`rows`/`patch`, crud entries and refresh lists,
-  have no HTML counterpart at all.
-
-## The db comparison
-
-db earns "Postgres+" because it passes four tests:
-
-1. What it builds is plain Postgres, inspectable with psql.
-2. Its vocabulary extends Postgres's own concepts: the foreign key becomes the
-   channel for values flowing down and aggregates flowing up.
-3. A developer can drop to plain SQL anywhere.
-4. Postgres does the heavy lifting.
-
-The browser half of app passes all four:
-
-1. The output is plain HTML.
-2. The vocabulary extends `name`, `form` and `hidden`.
-3. Any HTML works, and a custom element is still just a custom element.
-4. The platform does the work: `cloneNode` of templates, the selector engine,
-   form owners, `showModal`, the History API.
-
-The rule behind it is the same as db's: **defer where the foundation has an
-answer, and add only where it is silent.**  HTML is silent about data, and
-that's where the seven attributes live.
-
-The difference is that db never overrides Postgres.  It adds to Postgres and
-replaces the application's logic layer.  app overrides HTML twice, in
-navigation and on the wire, both for the 300ms budget.  Those are deliberate
-departures, not add-ons.
-
-## How it feels
-
-- **Writing a page** feels like writing HTML: forms and tables with a few
-  attributes, much like data-bound HTML in 1999 without the ActiveX.
-- **Writing a widget** feels like writing web components.
-- **Writing `requests.ts`** feels like neither.  A nested declaration such as
-  `crud.invoiceLines.rowDelete.{run, refresh}` feels like a framework's
-  configuration map.  db has no equivalent seam, because its DSL reads as DDL
-  all the way down.  That file is where the "HTML+" feel breaks.
-
-## A better framing
-
-The idea that runs through every layer of app is not HTML.  It is the
-**row**: query, row, rows, column and key.  That's where the scope decision in
-[Theory](./theory.md#data-binding) lands, and it's what the protocol carries.
-HTML is the surface, and relations are the substance.
-
-Framed that way, the two packages form one story rather than two:
-
-- **db** is the relational model with derived values, built on Postgres.
-- **app** is the relational model shown and edited on screen, with HTML as its
-  surface.
-- **The row** is the only thing that crosses between them.
-
-So "Relational+ from end to end, with Postgres at one end and HTML at the
-other" is accurate everywhere.  "HTML+" is accurate only for page and widget
-authoring.  It also explains the server half: `queries.ts` and `requests.ts`
-aren't HTML because they're the relational half of the contract.
-
-"HTML+" still works as a description of how page authoring feels.  It fails
-as a statement of what the package is, and it pulls readers toward the
-hypermedia comparison Loadbare would rather avoid.