@loadbare/app 0.6.0 → 0.7.1

package/dist/server/lb-server.js

@@ -4,7 +4,7 @@
 // vocabulary the browser writes, this one is the vocabulary the application
 // writes. The engine below is the whole of Hub on the server. It ships no
 // HTTP server, no router, and no data layer.
-import { LB_RESERVED_PREFIX } from "../core/lb-constants";
+import { LB_RESERVED_PREFIX } from "../core/lb-constants.js";
 /** A query that answers with one row. */
 export function row(run) {
     return { kind: "row", run };
@@ -114,3 +114,4 @@ export function createHub(pages) {
         },
     };
 }
+//# sourceMappingURL=lb-server.js.map

package/dist/server/lb-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lb-server.js","sourceRoot":"","sources":["../../server/lb-server.ts"],"names":[],"mappings":"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","sourcesContent":["// The server-side contract and the engine that runs it.\n//\n// This is the counterpart to core/lb-constants.ts: that file is the\n// vocabulary the browser writes, this one is the vocabulary the application\n// writes. The engine below is the whole of Hub on the server. It ships no\n// HTTP server, no router, and no data layer.\n\nimport type { Patch, Row, HubData, HubResult } from \"../core/lb-types.js\";\nimport { LB_RESERVED_PREFIX } from \"../core/lb-constants.js\";\n\n/**\n * Whatever the application hands the engine for the duration of one request.\n *\n * Hub declares it empty and never reads it. An application fills it in by\n * declaration merging, once, anywhere in its own source:\n *\n *     declare module \"@loadbare/app/server\" {\n *       interface HubContext {\n *         db: Db;\n *       }\n *     }\n *\n * That is why no type on this page takes a type parameter. The context is a\n * request-scoped handle — an authenticated database connection is the\n * expected case — so it is passed per call rather than held by the engine.\n */\nexport interface HubContext {}\n\n/**\n * A declared query: the request context in, one result out.\n *\n * Cardinality is a property of the name rather than of any one answer, so it\n * is declared here and never inferred from what comes back. One name answers\n * with one shape, always. A page that wants the roster once as a single row\n * and once as a set declares two queries.\n *\n * Write one with `row()` or `list()` below; nothing else builds one.\n */\nexport interface Query {\n  readonly kind: \"row\" | \"list\";\n  readonly run: (ctx: HubContext) => HubResult | Promise<HubResult>;\n}\n\n/** A query that answers with one row. */\nexport function row(run: (ctx: HubContext) => Row | Promise<Row>): Query {\n  return { kind: \"row\", run };\n}\n\n/**\n * A query that answers with the entire set, and therefore also the order. A\n * list reconciles to exactly this: a row whose key is not here is gone.\n *\n * There is no wrapper around the array, because the declaration already said\n * this name answers with rows.\n */\nexport function list(run: (ctx: HubContext) => Row[] | Promise<Row[]>): Query {\n  return { kind: \"list\", run };\n}\n\n/**\n * Only what changed, returned from a `crud` run rather than from a query.\n * Rows named here arrive or are updated, keys in `drop` are gone, and\n * everything unnamed is left alone — its contents, and its place in whatever\n * order the widget is keeping.\n *\n * `Array.isArray` is what tells a patch from a whole set, so a patch needs no\n * marker of its own and no column name is reserved to carry one.\n */\nexport function patch(change: { rows?: Row[]; drop?: string[] }): Patch {\n  return { ...change };\n}\n\n/** The shape of a `<name>.queries.ts` module. */\nexport type Queries = Record<string, Query>;\n\n/**\n * Where the interaction happened, in the binding vocabulary, plus the one\n * value a control may carry.\n *\n * The browser fills these from attributes it already has. It never names a\n * function — only a name the page declared — which is what keeps this from\n * being an RPC endpoint. A value may ride along because a `<select>` has one\n * and there is nowhere else to put it; it is a string from a control, not an\n * argument list.\n */\nexport interface Where {\n  list?: string;\n  row?: string;\n  key?: string;\n  cell?: string;\n  value?: string;\n}\n\n/**\n * What an action does, and which queries must re-run once it has.\n *\n * `run` may also return results of its own, which are laid over the refreshed\n * ones. That is how a patch reaches the browser: a query answers for its\n * whole set and cannot know why it was re-run, but the action knows exactly\n * what it changed and can say only that.\n */\nexport interface Action {\n  run: (\n    ctx: HubContext,\n    where: Where,\n  ) => void | HubData | Promise<void | HubData>;\n  refresh: string[];\n}\n\n/**\n * One CRUD operation on a declared query. Same shape as `Action` — run, then\n * refresh — but `where` carries only what that operation is typed to carry\n * on the wire, rather than the general `Where`.\n */\nexport interface CrudOp<W> {\n  run: (ctx: HubContext, where: W) => void | HubData | Promise<void | HubData>;\n  refresh: string[];\n}\n\nexport type CellChangeOp = CrudOp<{ key: string; cell: string; value: string }>;\nexport type RowDeleteOp = CrudOp<{ key: string }>;\nexport type RowInsertOp = CrudOp<{ values: Record<string, string> }>;\nexport type RowUpdateOp = CrudOp<{\n  key: string;\n  values: Record<string, string>;\n}>;\n\n/**\n * The CRUD operations declared for one list, keyed by its name in\n * `Requests.crud`. A name with no entry here permits none of them — the wire\n * cannot reach anything the page has not published, exactly as for a named\n * action.\n *\n * Every key here is the reserved `lb-action` value with the prefix stripped\n * and the rest camel-cased, so the attribute, the wire field and this key\n * are one vocabulary. All four are list operations: each needs a key, and a\n * key exists only on a live row inside a list.\n */\nexport interface Crud {\n  cellChange?: CellChangeOp;\n  rowDelete?: RowDeleteOp;\n  rowInsert?: RowInsertOp;\n  rowUpdate?: RowUpdateOp;\n}\n\n/**\n * The shape of a `<name>.requests.ts` module.\n *\n * `onPageEnter` runs once when the page is entered, before any query. It\n * declares no refresh set: entering the page runs the whole query set\n * afterward, so whatever the hook changed is already in the response.\n *\n * `actions` names what this page may be asked to do. A name the page did not\n * declare is refused, so the wire cannot reach anything the page has not\n * published.\n *\n * `crud` is the same rule for the typed CRUD operations, keyed by the list\n * they operate on rather than by a declared name — there is nothing to name,\n * since the row's own binding says what it is.\n */\nexport interface Requests {\n  onPageEnter?: (ctx: HubContext) => void | Promise<void>;\n  actions?: Record<string, Action>;\n  crud?: Record<string, Crud>;\n}\n\n/** A page is three files sharing a basename; two of them are these. */\nexport interface Page {\n  queries: Queries;\n  requests: Requests;\n}\n\n/**\n * The page registry. The builder populates this automatically from every\n * `.requests.ts`/`.queries.ts` pair it discovers — see docs/reference/builder.md,\n * \"Generating the server-side page registry\".\n */\nexport type Pages = Record<string, Page>;\n\nexport interface Hub {\n  /** Entering a page: run its onPageEnter hook, then all of its queries. */\n  dataForPage(page: string, ctx: HubContext): Promise<HubData>;\n\n  /**\n   * An action: run what the page declared under that name, then the refresh\n   * set declared with it.\n   */\n  runAction(\n    page: string,\n    name: string,\n    where: Where,\n    ctx: HubContext,\n  ): Promise<HubData>;\n\n  /** Edit one cell: run the list's declared `cellChange`, then its refresh set. */\n  runCellChange(\n    page: string,\n    where: { list: string; key: string; cell: string; value: string },\n    ctx: HubContext,\n  ): Promise<HubData>;\n\n  /** Drop one row: run the list's declared `rowDelete`, then its refresh set. */\n  runRowDelete(\n    page: string,\n    where: { list: string; key: string },\n    ctx: HubContext,\n  ): Promise<HubData>;\n\n  /** Add one row: run the list's declared `rowInsert`, then its refresh set. */\n  runRowInsert(\n    page: string,\n    where: { list: string; values: Record<string, string> },\n    ctx: HubContext,\n  ): Promise<HubData>;\n\n  /** Edit several cells at once: run the list's declared `rowUpdate`, then its refresh set. */\n  runRowUpdate(\n    page: string,\n    where: { list: string; key: string; values: Record<string, string> },\n    ctx: HubContext,\n  ): Promise<HubData>;\n}\n\n/**\n * Build the engine over a set of pages. The pages are fixed at startup; the\n * context is not, and arrives with each call.\n */\nexport function createHub(pages: Pages): Hub {\n  // Names beginning with the reserved prefix are Loadbare's — the hub's\n  // own query, the CRUD operations — so an application cannot declare one.\n  // Refused at startup, because a name is a fact about the page and not\n  // about any request.\n  for (const [page, entry] of Object.entries(pages)) {\n    const declared = [\n      ...Object.keys(entry.queries),\n      ...Object.keys(entry.requests.actions ?? {}),\n    ];\n    for (const name of declared) {\n      if (name.startsWith(LB_RESERVED_PREFIX)) {\n        throw new Error(\n          `loadbare: page '${page}' declares '${name}', but names ` +\n            `beginning with '${LB_RESERVED_PREFIX}' are reserved`,\n        );\n      }\n    }\n  }\n\n  async function run(\n    page: string,\n    names: string[],\n    ctx: HubContext,\n  ): Promise<HubData> {\n    const data: HubData = {};\n    for (const name of names) {\n      const query = pages[page]?.queries[name];\n      if (!query) {\n        console.warn(`loadbare: page '${page}' declares no query '${name}'`);\n        continue;\n      }\n      const result = await query.run(ctx);\n      // Cardinality is declared, so an answer that disagrees is a mistake in\n      // the query rather than a case to handle. Refused here, because a page\n      // is better off missing one name than showing the wrong shape for it.\n      if (Array.isArray(result) !== (query.kind === \"list\")) {\n        console.warn(\n          `loadbare: query '${name}' is declared ${query.kind} but answered ` +\n            `with ${Array.isArray(result) ? \"rows\" : \"one row\"}`,\n        );\n        continue;\n      }\n      data[name] = result;\n    }\n    return data;\n  }\n\n  /**\n   * Shared by every operation kind: run what was declared, then its refresh\n   * set against the same context, laying what the operation itself stated\n   * over the refreshed queries — the narrower answer wins because it is the\n   * one that knows what actually changed.\n   */\n  async function settle<W>(\n    page: string,\n    declared: CrudOp<W> | Action | undefined,\n    where: W,\n    ctx: HubContext,\n    notFound: string,\n  ): Promise<HubData> {\n    if (!declared) {\n      console.warn(notFound);\n      return {};\n    }\n    const stated = await declared.run(ctx, where as never);\n    return { ...(await run(page, declared.refresh, ctx)), ...(stated ?? {}) };\n  }\n\n  return {\n    async dataForPage(page, ctx) {\n      const entry = pages[page];\n      if (!entry) {\n        console.warn(`loadbare: no page '${page}'`);\n        return {};\n      }\n      await entry.requests.onPageEnter?.(ctx);\n      return run(page, Object.keys(entry.queries), ctx);\n    },\n\n    runAction(page, name, where, ctx) {\n      return settle(\n        page,\n        pages[page]?.requests.actions?.[name],\n        where,\n        ctx,\n        `loadbare: page '${page}' declares no action '${name}'`,\n      );\n    },\n\n    runCellChange(page, where, ctx) {\n      return settle(\n        page,\n        pages[page]?.requests.crud?.[where.list]?.cellChange,\n        { key: where.key, cell: where.cell, value: where.value },\n        ctx,\n        `loadbare: page '${page}' declares no cellChange for '${where.list}'`,\n      );\n    },\n\n    runRowDelete(page, where, ctx) {\n      return settle(\n        page,\n        pages[page]?.requests.crud?.[where.list]?.rowDelete,\n        { key: where.key },\n        ctx,\n        `loadbare: page '${page}' declares no rowDelete for '${where.list}'`,\n      );\n    },\n\n    runRowInsert(page, where, ctx) {\n      return settle(\n        page,\n        pages[page]?.requests.crud?.[where.list]?.rowInsert,\n        { values: where.values },\n        ctx,\n        `loadbare: page '${page}' declares no rowInsert for '${where.list}'`,\n      );\n    },\n\n    runRowUpdate(page, where, ctx) {\n      return settle(\n        page,\n        pages[page]?.requests.crud?.[where.list]?.rowUpdate,\n        { key: where.key, values: where.values },\n        ctx,\n        `loadbare: page '${page}' declares no rowUpdate for '${where.list}'`,\n      );\n    },\n  };\n}\n"]}

package/docs/TECHREF-1.0.md

@@ -24,6 +24,13 @@ element, or by whatever the widget does when it lands on a widget.
 We will then see if a useful solution emerges that Loadbare/app should
 handle.
 
+### Form controls
+
+- **Checkboxes and radio buttons are not implemented.** A value does not
+  land on one and a form does not gather one.  Landing needs a decision on
+  what counts as checked, which waits on [Data types](#data-types), and a
+  radio group is several elements answering to one cell.
+
 ### Run-time state attributes
 
 The hub stamps `lb-row-count`, `lb-pending` and `lb-error` for a
@@ -49,24 +56,21 @@ That decision is firm; what the set contains is not.
   element at a time and offers no escape hatch.  An optional `lbAcceptRow`
   would sit beside `lbPlaceRow` and `lbRowsLanded`, and this is the most
   likely first request from a widget author.
-- **Give a widget a way to fire its own request.** A custom widget must
-  reproduce the logic in the hub to fire its own event.  This is a bit of a
-  smell, but was done this way to start because we do not know yet the shape
-  of how the widget could re-use code from the hub.
 
 ### Lists
 
-- **Decide what a nested list means.** A list whose rows each hold a list is
-  legal by the nesting rule, and produces strange results when the outer list
-  is updated.  Loadbare/app has no vocabulary for it.
+- **Decide how a new row fills a nested list.** A row added to the outer
+  list starts with an empty nested list, which fills only when the nested
+  list's name lands again.  See [Master-detail](#master-detail) for what a
+  nested list is for.
 
 ```html
-<div lb-list="departments">
-  <template lb-key="id"><section>
-    <h2 lb-cell="name"></h2>
-    <ul lb-list="members"><template lb-key="id"><li lb-cell="who"></li></template></ul>
-  </section></template>
-</div>
+<tbody lb-list="accounts">
+  <template lb-key="id"><tr>
+    <td lb-cell="name"></td>
+    <td><select lb-list="statuses"><template lb-key="id"><option lb-cell="label"></option></template></select></td>
+  </tr></template>
+</tbody>
 ```
 
 ### The server API
@@ -93,10 +97,14 @@ That decision is firm; what the set contains is not.
   stays a flag, since it is what locates the file.  State the precedence
   between a flag and a key once.  Its key names join the permanent surface,
   so this lands before 1.0 or not at all.
-- **Take a position on the URL space.** A page name is a filename basename,
-  so `/user/42` resolves to nothing and no page is addressable by row.
-  Deciding against path parameters is a legitimate answer.  Write whichever
-  one down.
+- **Decide whether a URL carries view parameters.** A URL names a page and
+  nothing finer — see [What a URL names](#what-a-url-names) — and a query
+  takes no argument from the browser.  So a page has nowhere to keep which
+  record it shows, a filter, a sort, or a collapsed section: a reload or a
+  shared link loses them, and a filter is lost whenever an action re-runs its
+  query.  Parameters on a page URL, as `<form method="get">` puts its fields
+  in the query string, are one answer.  Deciding against them, and leaving
+  view state to the application, is another.  Write whichever one down.
 - **Decide CSS pairing.** Naming a stylesheet `<tag>.css` beside its
   definition would let the builder ship only what survives expansion.
   Recommend deferring the mechanism and reserving the configuration key, so
@@ -376,35 +384,104 @@ custom widgets to update themselves.
 | lb-cell      | Developer   | This DOM node displays this column of the row in scope                                    |
 | lb-key       | Developer   | Names the column that identifies a row, on the row template inside an lb-list             |
 | lb-key-value | Hub         | Stamped on a live row: that row's value of `lb-key`                                       |
-| lb-value     | Hub         | Custom widgets update themselves when this attribute changes                              |
+| lb-value     | Hub         | The value that landed on a cell; a widget updates itself from it and a stylesheet selects on it |
 
 #### How a value lands
 
-A cell lands one of two ways, and the tag name decides which.
+A cell lands one of three ways, and the element decides which.  Every cell
+that receives a value also carries it as `lb-value`.
+
+| Element                                             | Receives the value as                |
+|-----------------------------------------------------|--------------------------------------|
+| A custom element, tag hyphenated                    | Its `lb-value` attribute             |
+| `<select>`, `<textarea>`, or `<input>`              | Its `value`, and `lb-value`          |
+| Any other native element                            | Its `textContent`, and `lb-value`    |
+
+A widget owns whatever control it wraps, so it is handed the value and
+renders it itself.  A form control shows its state as its `value`, so a
+`<select>` keeps its options.  Any other native element has no behavior of its
+own, so its value is its text.
+
+A form gathers from the same controls it lands on, so a value read back on
+submit is the one that landed.
 
-| Element                          | Receives the value as    |
-|----------------------------------|--------------------------|
-| A native element                 | Its `textContent`        |
-| A custom element, tag hyphenated | Its `lb-value` attribute |
+An `<input>` of type `checkbox`, `radio`, or `file` receives nothing, not even
+`lb-value`, and the hub reports it to the console.  A form gathering one skips it the same way.
 
-A native element has no behavior of its own, so its value is its text.  A
-widget owns whatever control it wraps, so it is handed the value and renders
-it itself.
+A `<select>` with no option for the value shows no selection.
 
-The test is the hyphen in the tag name.  The hub holds no knowledge of any
-particular element, and the same test decides that the hub leaves a widget's
-own clicks alone — see [Requests](#requests).
+Only the hyphen and these three form controls are recognized.  The hub holds
+no other knowledge of any particular element, and the hyphen also decides
+that the hub leaves a widget's own clicks alone — see [Requests](#requests).
 
-Nothing an application writes ever sets `lb-value`.  Loadbare writes it and
-the widget it is written on reads it.
+Nothing an application writes ever sets `lb-value`.  Loadbare writes it, and
+a widget or a stylesheet reads it.
 
 The value arrives as the query produced it, with no conversion, so the
 browser decides what a non-string looks like.
 
+A cell holds one value.  A set of values is a list of its own, never an array
+in a cell.
+
 A widget sees `attributeChangedCallback` for an `lb-value` already present
 when it upgrades, so a widget cannot tell a first landing from a refresh,
 and does not need to.
 
+#### Displaying by value
+
+A stylesheet selects on `lb-value` to show or hide part of a page according
+to a value that landed.  A column the page does not display is bound to a
+hidden element.
+
+```html
+<template lb-key="id">
+  <tr>
+    <td lb-cell="name"></td>
+    <td lb-cell="locked" hidden></td>
+    <td><button lb-action="lb-row-delete">Remove</button></td>
+  </tr>
+</template>
+```
+
+```css
+tr:has([lb-cell="locked"][lb-value="true"]) button { display: none; }
+```
+
+`lb-value` holds the string the query sent, so the query decides the spelling
+a selector matches.  A hidden control is out of reach, keyboard included; a
+stylesheet cannot disable one, which is a widget's job.  Hiding is
+presentation, and the server still refuses what a request may not do.
+
+#### Master-detail
+
+A master is a row and its detail is a list, as two names answered side by
+side.  A cell never holds rows.
+
+```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>
+```
+
+Many masters, each with its own detail, is one list of joined rows: each
+detail row carries its master's columns.  A widget's `lbPlaceRow` groups them
+for display, as `lb-table` builds sections and `lb-options` builds
+`<optgroup>`s.
+
+A list nested in another list's rows receives the same rows in every outer
+row.  That serves a picker offering the same choices on every row, and is
+not a way to show a different detail per row.
+
+Which master a page shows is server state reached through `ctx`, since a
+query takes no argument from the browser — see the blocker on view parameters.
+
 ### Requests
 
 ---- UNEDITED ----
@@ -422,9 +499,9 @@ name, the same test that decides how a value lands — see
 
 | lb-action      | Written on                                        |
 |----------------|---------------------------------------------------|
-| lb-row-insert  | a `<form>` in a list scope                        |
+| lb-row-insert  | a `<form>`, or a button by its cells, in a list   |
 | lb-row-delete  | anything inside a live row                        |
-| lb-row-update  | a `<form>` inside a live row                      |
+| lb-row-update  | a `<form>`, or a button by its cells, in a row    |
 | lb-cell-change | a widget wrapping one control                     |
 | anything else  | must be a named routine in the page's server code |
 
@@ -432,21 +509,43 @@ The wire format is not visible to the user, but uses the same lb-*
 attributes minus their prefix, so that it is intelligible when working on
 Loadbare/app itself.
 
-From a native element the hub sends the action plus whatever binding is in
-scope, and never a scalar value.
+The hub scopes every request, whether a native element or a widget
+dispatched it.  It reads the scope from the dispatching element before any
+ancestor sees the event, and never overwrites a field the request already
+carries.
+
+| `action`         | Filled from scope              | Required                   |
+|------------------|--------------------------------|----------------------------|
+| a declared name  | `list` or `row`, `key`, `cell` | nothing                    |
+| `lb-cell-change` | `list`, `key`, `cell`          | all three, and `value`     |
+| `lb-row-insert`  | `list`                         | `list`, and `values`       |
+| `lb-row-delete`  | `list`, `key`                  | both                       |
+| `lb-row-update`  | `list`, `key`                  | both, and `values`         |
+
+An element's own `lb-list` or `lb-row` names what it displays, never where
+its request goes.  A request belongs to the scope around the element, the
+way a control belongs to the form around it.  `list` or `row` comes from the
+nearest ancestor scope, `key` from the nearest live row inside that scope,
+and `cell` from the dispatching element's own `lb-cell`.
+A request missing a required field is not sent.  The hub never fills
+`value`; for `lb-row-insert` and `lb-row-update`, `values` is gathered from
+the nearest element holding an `lb-cell` with a control to read, starting at
+the dispatching element and walking up.  A `<form>` holds its own cells; a
+button in a `<tr>` for a new row, which cannot be a form, reads the row
+around it.  The walk stops at the live row the element sits in and never
+reaches the scope, whose other cells belong to other rows.  A request that
+already carries `values` keeps them, and one with no cell to read is not
+sent.  A click inside a native element that carries either operation and
+holds cells itself is not sent, since clicking into one of its controls
+would send the row: put the action on a form or on a button.
+
+A widget dispatches the action and, where it wraps a control, that control's
+value.
 
 ```
 { action: "lb-row-insert",  list: "rosterList", values: {...} }
 { action: "lb-row-delete",  list: "rosterList", key: "42" }
 { action: "lb-row-update",  list: "rosterList", key: "42", values: {...} }
-```
-
-A widget builds its own request and adds the value of the control it wraps.
-`lb-select` and `lb-options` send an action and a value and no binding.
-`lb-input` sends the binding as well, and is the only sender of a cell
-change.
-
-```
 { action: "lb-cell-change", list: "rosterList", key: "42", cell: "name", value: "Ann" }
 { action: "selectTab",      row: "prefs", cell: "active_tab", value: "two" }
 ```
@@ -519,6 +618,22 @@ One that declares none gets a console error and nothing on screen.  See
 
 See also [Navigation Row lb-navigation](#lb-navigation).
 
+#### What a URL names
+
+A URL names a page, a place in the application.  It never names a resource,
+and Loadbare/app does not reproduce REST: `/accounts/42` is not a way to
+reach account 42.
+
+A page declares what it shows, its queries, and what it allows, its actions.
+Loading a page runs its queries.  A request performs an action at a position.
+A row is addressed by `list` and `key`, taken from where the element sits,
+which is how the database already names it.  Nothing is fetched by URL, so an
+application designs no endpoints, and the browser reaches only what a page
+publishes.
+
+Whether a page URL may carry parameters, so that a link can open the page on
+one record, is undecided — see the blockers.
+
 ### lb-navigation
 
 ---- UNEDITED ----

package/docs/analysis-accidental-complexity.md

@@ -0,0 +1,149 @@
+# Assessing the accidental complexity claim
+
+[Theory](./theory.md) claims that Loadbare/app carries less accidental
+complexity than React, Angular, or the hypermedia libraries.  This document
+tests that claim against [TECHREF-1.0](./TECHREF-1.0.md), which is the
+authoritative statement of what 1.0 means.
+
+Written 2026-09-07, against `@loadbare/app` 0.6.0.
+
+Brooks separates the difficulty of the user's problem from the work the tool
+demands.  The second kind is accidental, and the test applied here is whether
+Loadbare removes such work or relocates it somewhere the author still pays
+for it.
+
+## Where the claim holds
+
+The whole owned surface fits in the technical reference's cross-reference
+section.
+
+| Owned            | Count |
+|------------------|-------|
+| `lb-*` attributes | 15   |
+| `lb*` methods     | 3    |
+| Builder flags     | 4    |
+| Reserved filenames| 8    |
+| Reserved tags     | 1    |
+| Reserved events   | 1    |
+
+React reaches that size before an application adds a router, a data layer, or
+a bundler configuration, and each of those carries a surface of its own.
+Loadbare/app asks for no configuration file today.
+
+The server half is the strongest part of the argument.  A page is markup, a
+queries file, and a requests file.  The application designs no endpoints,
+writes no route table, and picks no serialization contract.  Four lines of
+Express carry the data channel.  Neither the fat frameworks nor the
+hypermedia libraries remove that category of work; htmx in particular leaves
+the developer designing every endpoint and every fragment it answers with.
+
+Building the HTML once removes reconciliation, keys, memoization, and effect
+dependencies together.  That is the largest single deletion in the design,
+and it is the one the hypermedia libraries do not make either, since they
+ship markup at run time and carry swap semantics to place it.
+
+## What the technical reference already knows
+
+Most of what an assessment finds is already on the blocker list.  Each
+concern below adds weight to an open item rather than naming a new one.
+
+| Concern                                    | Blocker                                    |
+|--------------------------------------------|--------------------------------------------|
+| Values carry no type, so every application formats its own dates and money | Data types |
+| No page is reachable by row                | Take a position on the URL space           |
+| A widget receives one cell at a time       | Whether a widget may receive a whole row   |
+| A widget repeats hub code to fire a request| Give a widget a way to fire its own request|
+| Master-detail is unspecified               | Decide what a nested list means            |
+| Every page redeclares the chrome's queries | Give the chrome a way to state its own queries |
+
+The technical reference's own sample query calls `String()` on a count by
+hand, which is the data-type blocker showing up in the documentation.
+
+Two [roadmap](./roadmap.md) items carry the same weight as these and appear
+in the first real application.  Concurrent writers on one list have no
+version or conflict story.  Per-keystroke validation has no home, and the
+roadmap expects it to sit in the widget while the server stays authoritative
+for the same field.
+
+Five sections of the technical reference are still marked `UNEDITED`:
+Binding, Requests, Links, Widgets, and Widget authoring.  Those are the
+mechanisms an author touches on every page.
+
+## Positions that carry a cost
+
+Two constraints appear in the body of the technical reference as current
+behavior rather than on the blocker list, so the project has taken a position
+on each.  Naming the cost is still fair.
+
+The hub reaches its endpoint by absolute path, so an application cannot be
+hosted under a subpath such as `example.com/myapp/`.  A deployment that wants
+several applications behind one host gives each one an origin.
+
+Every route answers 200 with the same document, so the browser detects an
+unknown page after the fact and the chrome's `lb-unknown-page` dialog reports
+it.  A crawler or a monitor that reads status codes sees a healthy response
+for a path the application does not have.
+
+## The gap recorded nowhere
+
+Loadbare/app offers no way to display or style an element according to the
+value that landed in it.
+
+A cell lands on a custom element as the `lb-value` attribute, which a
+stylesheet can select.  A cell lands on a native element as its
+`textContent`, which no selector reaches.  The hub stamps `lb-pending`,
+`lb-error`, and `lb-row-count`, which cover a request in flight, a request
+that failed, and an empty list.  Nothing covers a row whose `status` column
+reads `overdue`.
+
+An application that wants this writes a widget, and a widget that fires a
+request pays the cost the widget-protocol blocker already names.  So the
+missing piece pushes the author toward the mechanism that is itself
+unfinished.
+
+This appears in neither the blockers, the roadmap's open questions, nor the
+decided-against section.  It is the one finding here that the technical
+reference does not already record.
+
+## The general form of the query gap
+
+The URL-space blocker names one consequence of a broader constraint, and
+stating the constraint directly is more useful than stating the consequence.
+
+A query takes no argument from the browser.  Its signature is `(ctx) => Row`
+or `(ctx) => Row[]`, and `ctx` is what the application built from the Express
+request.  The hub's own request carries `page=<name>`.  The hub reads
+`location.pathname`, which drops the query string, so a path segment and a
+search parameter are both invisible to the server.
+
+An application that shows one selected record therefore holds the selection
+in server state.  A click fires an action, the handler records the selection
+where `ctx` reaches it, and the refreshed query reads it back.  That works
+today and needs no new mechanism.  It puts selection in the same territory as
+the roadmap's concurrent-writers question, and it means a reload or a shared
+link does not carry the record.
+
+## Comparison with the hypermedia libraries
+
+Theory rejects the existing tools for combining interpolation with
+conditional and list rendering.  The distinction is narrower than that.
+Loadbare/app interpolates at build time, with defaults and a substitution
+grammar, and renders lists at run time through `<template lb-key>`.  What the
+design rules out is conditionals and interpolation after the build.
+
+Loadbare/app also adds a builder, a filename grammar, and a slot and template
+system, where htmx asks for no build step.  Against React and Angular the
+surface comparison is decisive.  Against htmx it is close, and the server
+half is where Loadbare/app wins instead.
+
+## Verdict
+
+The claim holds on the server, and it holds on the client for everything the
+reconciliation layer used to cost.
+
+On the rest of the client it currently holds partly by not doing several
+things database applications need, and the technical reference lists most of
+them itself.  Whether the claim survives 1.0 depends on how the URL space,
+the row hook, the chrome queries, and value-driven display are answered, and
+an answer of "decided against" counts as an answer only where an application
+can still reach the behavior some other way.

package/docs/reference/custom-elements.md

@@ -264,28 +264,39 @@ no separate hydration path to write.
 ### Sending a request
 
 A widget that owns its own interaction — a `<select>`'s choice rather than a
-click — builds its own request and dispatches it as a bubbling
-`CustomEvent` named `LB_EVENT_NAME`, carrying one of the `HubRequest` shapes
-as its `detail`:
+click — dispatches its own request as a bubbling `CustomEvent` named
+`LB_EVENT_NAME`, carrying the action and, where it wraps a control, that
+control's value as its `detail`:
 
 ```ts
-import { ATTR_CELL, ATTR_KEY_VALUE, ATTR_LIST, LB_EVENT_NAME } from "@loadbare/app/constants";
+import { LB_EVENT_NAME } from "@loadbare/app/constants";
 import type { HubRequest } from "@loadbare/app/types";
 
-const detail: HubRequest = {
-  action: "lb-cell-change",
-  list: this.closest(`[${ATTR_LIST}]`)!.getAttribute(ATTR_LIST)!,
-  key: this.closest(`[${ATTR_KEY_VALUE}]`)!.getAttribute(ATTR_KEY_VALUE)!,
-  cell: this.getAttribute(ATTR_CELL)!,
-  value: input.value,
-};
+const detail: HubRequest = { action: "lb-cell-change", value: input.value };
 this.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
 ```
 
-Find the scope name and `key` by walking up with `closest()`, the same way the hub
-finds the binding for a native element. See
-[Data Binding](./data-binding.md#requests) for the request vocabulary and
-what each operation carries.
+The hub fills in the scope the widget sits in before any ancestor sees the
+event, and does not send a request missing a field its operation requires.
+See [TECHREF-1.0](../TECHREF-1.0.md#requests) for what each operation is
+filled with.
+
+A widget sending `lb-row-insert` or `lb-row-update` doesn't read its own
+controls. It dispatches the bare action from the element holding the cells,
+a `<tr>` as readily as a `<form>`, or from anything inside it, and the hub
+gathers `values` from the nearest element holding a readable `lb-cell`:
+
+```ts
+row.dispatchEvent(
+  new CustomEvent(LB_EVENT_NAME, {
+    bubbles: true,
+    detail: { action: "lb-row-insert" } as HubRequest,
+  }),
+);
+```
+
+Values the widget supplies itself are kept, and nothing is gathered over
+them.
 
 Let the event bubble, so an ancestor widget can intercept and stop it before
 the hub sees it. A hand-written widget and a native element carrying
@@ -339,8 +350,7 @@ order. `lb-options.browser.ts` and `lb-table.browser.ts` in
 [`@loadbare/widgets`](./widgets.md) are two different placements over the
 same machinery.
 
-A list scope with no row template displays nothing, which is not an error: an
-insert form names the list it adds a row to and has no rows of its own.
+A list scope with no row template displays nothing, which is not an error.
 
 Style an empty list against `lb-row-count` rather than carrying an empty-state
 conditional in the widget — see