@loadbare/app 0.8.1 → 0.9.0

package/docs/TECHREF-1.0.md

@@ -106,14 +106,6 @@ in the row.
   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.
-- **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
@@ -507,8 +499,11 @@ 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.
+Which master a page shows is a query parm, which a query reads off `ctx`
+since it takes no argument from the browser — see [Query parms](#query-parms).
+When a write creates or removes the master, the server response changes that
+parm — see
+[When a server response changes the query parms](#when-a-server-response-changes-the-query-parms).
 
 ### Requests
 
@@ -638,15 +633,16 @@ A failed insert resets nothing, so the entry can be corrected.
 
 A navigation that fails to load its data sets nothing.  No element
 dispatched it, so there is nothing to stamp, and the hub reports it to the
-console.
+console.  A load started by a control writing a query parm stamps that
+control, as a request stamps its origin.
 
 ### Links
 
 ---- UNEDITED ----
 
 An anchor carrying `lb-nav-link` navigates inside the application: the hub
-catches the click, pushes the anchor's path onto history, and swaps the page
-host in `<main>`.  An anchor without it is left alone and behaves like any
+catches the click, pushes the anchor's path and query string onto history,
+and swaps the page host in `<main>`.  An anchor without it is left alone and behaves like any
 other link, so leaving the application is the default and staying in it is
 the opt-in.
 
@@ -660,6 +656,11 @@ link to determine the path.
 Path space is flat.  A path such as `/members` links to the `members.*` files
 on the server.
 
+The query string is kept.  `/transactions?date_begin=2026-09-01` opens the
+transactions page narrowed to those dates, and a link to the page it is
+already on loads that page again at the new URL without replacing its DOM —
+see [Query parms](#query-parms).
+
 The bare path `/` resolves to `index`.
 
 A path that names no page is detected in the browser, after a successful
@@ -680,19 +681,122 @@ 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.
+The path 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.
+
+The query string describes what that page has on screen:
+`/accounts?acct=23&from=2026-09-09`.  It never commands, and the server
+remembers nothing, so a URL is a reproducible view.  Reload it, bookmark it,
+or mail it to someone, and what they see is what the sender saw.
 
 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.
+application designs no endpoints.
+
+That last is where query parms move Loadbare's position.  A query still takes
+no argument from the browser, and a parm arrives the way the session cookie
+does, as part of the request the context is built from.  But a user who
+types `?acct=99999` now influences what a query returns.  A query parm is
+user input, validated like any other where the application reads it, and a
+per-session database role means an id outside the caller's reach finds
+nothing.
+
+Loadbare is for applications, not sites.  Every route is answered with the
+same document, and a path that names no page is found out in the browser —
+see [Links](#links).
+
+#### Query parms
+
+A control that narrows what a page shows writes its value into the query
+string, rather than sending it:
+
+```html
+<lb-options lb-list="teams" lb-query-parm="team" exp-label="Team:">
+  <option value="">Every team</option>
+  <template lb-key="id"><option lb-cell="name"></option></template>
+</lb-options>
+```
+
+| Attribute            | Written by | Behavior                                                        |
+| -------------------- | ---------- | --------------------------------------------------------------- |
+| `lb-query-parm`      | Developer  | On a control: its `change` writes this parm and reloads the page |
+| `lb-query-parm-push` | Developer  | With `lb-query-parm`: the write pushes a history entry          |
+
+On `change`, the hub reads the control's value the way a form reads a cell,
+and sets that one parm in the URL.  Every other parm is left as it is, since
+it may have arrived by link with no control on screen to say it again.  An
+empty value takes the parm out, so a URL is as long as the user has narrowed
+the page.  A value the URL already carries does nothing.
+
+The write replaces the current history entry: changing what a page shows is
+not going anywhere, so Back leaves the page rather than walking back through
+every choice.  `lb-query-parm-push` makes the write push an entry instead.
+
+The page then loads at the new URL exactly as a cold load of that URL would:
+`onPageEnter`, then every query.  The page's DOM is kept, and the answer
+lands by key, so a list that gets its rows back keeps them and its scroll
+position.
+
+After every load — cold, by link, by Back, by a write — the hub lands each
+parm on the control that writes it, and an absent parm lands empty.  A
+control therefore shows what the address bar says.
+
+A control that writes a query parm sends no request.  One that also carries
+`lb-action` has that request refused, since the choice would otherwise be
+sent twice.
+
+Every round trip carries the query string the browser is showing, a page
+load and an action alike.  The server hands its parms to `contextFor` — see
+[The Express server](#the-express-server).  Nothing in Loadbare assigns a
+parm a meaning.
 
-Whether a page URL may carry parameters, so that a link can open the page on
-one record, is undecided — see the blockers.
+#### When a server response changes the query parms
+
+Some query parms can only be known once a write has run.  After an insert,
+the key of the new row exists only on the server.  After a delete, only the
+server knows that the row the page was showing is gone.
+
+The usual web answer is Post/Redirect/Get: the server answers the write with
+a redirect to a URL naming the result, and the browser makes a second request
+to load it.  Loadbare/app does the same work in one round trip, and never
+changes the path.
+
+A request's `run` returns `queryParms()`, naming the parms the write decided.
+The server loads the page with those parms set, as a cold load of the
+resulting URL would: `onPageEnter`, then every query.  The server response
+carries the parms and that load together.  The hub sets the parms in the URL,
+replacing the history entry, and then lands the load.
+
+```ts
+rowInsert: {
+  run: async (ctx, { values }) => {
+    const id = await ctx.db.addAccount(values);
+    return queryParms({ acct: String(id) });
+  },
+  refresh: [],
+},
+```
+
+- Only query parms change.  A server response cannot send the browser to
+  another page.
+- Parms the response does not name are left as they are.  An empty value
+  removes its parm.
+- At least one parm is named, and every value is a string.  Otherwise the
+  server warns, ignores the parms, and runs the refresh set as usual.
+- The refresh set does not run, and anything else `run` returned is dropped.
+  Both were answers for the query string the page is leaving.
+- If loading the page fails, the write has still happened.  The response
+  carries the parms alone, and the hub loads the page itself.  A failure
+  there is a page load's, and is not stamped on the element that sent the
+  request.
+- A user who has left the page by the time the response arrives keeps the
+  URL they are on.
+
+The page is loaded with a second context, built by `contextFor` from the new
+parms — see [The Express server](#the-express-server).
 
 ### lb-navigation
 
@@ -706,10 +810,11 @@ like a server-produced result.
 | Cell         | Holds                                                               |
 | ------------ | ------------------------------------------------------------------- |
 | `page-label` | The text of the link to the current page, empty if no link names it |
-| `page-uri`   | The path as the browser has it, such as `/members`                  |
+| `page-uri`   | The path and query string as the browser has them, such as `/members?team=Engines` |
 
 The `page-uri` is taken from the current URL.  The `page-label` is taken from the first
-`lb-nav-link` link in the document (presumably in a nav bar) that matches the URI.
+`lb-nav-link` link in the document (presumably in a nav bar) whose path matches the
+current path, so the query string does not change it.
 
 The row lands before the page is looked up, so a path that names no page has
 it too, and an `lb-unknown-page` dialog, where the chrome has one, displays
@@ -871,6 +976,24 @@ Explaining Express is beyond the scope of this technical reference.  The
 only real requirement is that the catch-all for app.html is at the end,
 so it does not catch any other files.
 
+`hubRoutes` answers `POST /lb/<page>`, with the query string the browser is
+showing after it, verbatim.  It hands `contextFor` that query string's parms
+as a second argument, and `contextFor` puts on the context whatever a query
+reads from them.  They are user input:
+
+```ts
+function contextFor(req: Request, parms: URLSearchParams): HubContext {
+  return { db: openDb(), acct: parms.get("acct") ?? "" };
+}
+```
+
+Read the parms from that argument, not from `req.query`.  After a request
+whose `run` returned `queryParms()`, `contextFor` is called a second time for
+the same request, with the new parms, to load the page at them.  So it must
+be safe to call twice, and a write must be visible to the second context by
+the time its `run` returns.  A handle opened per request without a
+transaction around it is both.
+
 Give the server the origin root.  The hub reaches its own endpoints by
 absolute path, so an application cannot be hosted under a subpath such as
 `example.com/myapp/`, and anything proxying in front of the server passes
@@ -941,6 +1064,13 @@ interaction happened, as `list`, `row`, `key`, `cell` and `value`.  Under
 ones.  That is how a delta reaches the browser: wrap it in `patch()`, naming
 the rows that arrived or changed and the keys that went.
 
+`run` may instead return `queryParms()`, naming query parms only the write
+can know, such as the key of a row it inserted.  The page then loads at them
+in the same round trip, in place of the refresh set — see
+[When a server response changes the query parms](#when-a-server-response-changes-the-query-parms).
+A `rowDelete` that removes the row on screen returns `queryParms({ acct: "" })`
+and leaves any other delete to its refresh set.
+
 ```ts
 // members.requests.ts
 import { patch, type Requests } from "@loadbare/app/server";
@@ -1148,6 +1278,8 @@ Each attribute is defined in one section, and this table says which.
 | `lb-value`        | Hub           | [How a value lands](#how-a-value-lands)             |
 | `lb-action`       | Developer     | [Requests](#requests)                               |
 | `lb-nav-link`     | Developer     | [Links](#links)                                     |
+| `lb-query-parm`   | Developer     | [Query parms](#query-parms)                         |
+| `lb-query-parm-push` | Developer  | [Query parms](#query-parms)                         |
 | `lb-pending`      | Hub           | [Request state](#request-state)                     |
 | `lb-error`        | Hub           | [Request state](#request-state)                     |
 | `lb-row-count`    | Hub           | [Request state](#request-state)                     |

package/docs/comparison.md

@@ -361,7 +361,8 @@ Vuetify for Vue) are not usable in another without a wrapper.
 
 ### Loadbare/app
 
-Every request from the hub is `POST /lb?page=<name>` with a JSON body.
+Every request from the hub is `POST /lb/<page>` with a JSON body, and carries
+the query string the browser is showing.
 
 - An empty body asks for the page's whole query set.  The server runs the
   page's `onPageEnter`, then every query the page declares.
@@ -679,12 +680,12 @@ blocker.  Serving the static files from a separate origin is a roadmap item.
 
 First load of any path:
 
-| Request                  | Returns                                    |
-|--------------------------|--------------------------------------------|
-| `GET /<path>`            | `app.html`: the chrome and every page as a `<template>` |
-| `GET /client.js`         | The hub and every used widget, one bundle  |
-| `GET /app.css`           | Every stylesheet, one file                 |
-| `POST /lb?page=<name>`   | The page's query results as JSON           |
+| Request                   | Returns                                    |
+|---------------------------|--------------------------------------------|
+| `GET /<path>`             | `app.html`: the chrome and every page as a `<template>` |
+| `GET /client.js`          | The hub and every used widget, one bundle  |
+| `GET /app.css`            | Every stylesheet, one file                 |
+| `POST /lb/<page>?<query>` | The page's query results as JSON           |
 
 The three static files are fixed at release and can be compressed, cached,
 and served from a CDN.  There are no per-route bundles, lazy chunks or module

package/docs/reference/chrome.md

@@ -73,7 +73,9 @@ sits directly inside `<body>`, with banner, nav, footer and `<main>` inside
 it, so Loadbare can act on all of them.
 
 A navigation anchor's `href` is a path, and the path names a page:
-`/members` shows `members.page.html`. A bare `/` resolves to `index`, so the
+`/members` shows `members.page.html`. A query string on it is kept, so
+`/members?team=Engines` opens the page narrowed; see
+[Query parms](./data-binding.md#query-parms). A bare `/` resolves to `index`, so the
 landing page is the one named `index.page.html`. An anchor without
 `lb-nav-link` is left alone and behaves like any other link.
 
@@ -100,10 +102,10 @@ shows a value — so a chrome displays the current page with no code at all:
 | Cell         | Holds                                                     |
 |--------------|-----------------------------------------------------------|
 | `page-label` | The text of the `lb-nav-link` anchor for the path, or empty if none |
-| `page-uri`   | The path as the browser has it, such as `/members`        |
+| `page-uri`   | The path and query string as the browser has them, such as `/members?team=Engines` |
 
 The label is the nav's. The hub takes it from the first `lb-nav-link`
-anchor whose `href` names the current page, so a click, a reload and the
+anchor whose path names the current page, whatever its query string, so a click, a reload and the
 back button all land the same text, and a path no anchor names lands an
 empty label. A chrome that shows the label somewhere fixed should expect
 that case for a page reachable only by URL.

package/docs/reference/data-binding.md

@@ -304,6 +304,39 @@ Leave `lb-action` off a widget inside an `lb-row-insert` or `lb-row-update`
 form. The form reads every `lb-cell` in it on submit, so a widget that also
 sent its own would write the same edit twice.
 
+## Query parms
+
+A control that narrows what the page shows writes its value into the query
+string instead of sending a request. `lb-query-parm` names the parm:
+
+```html
+<select lb-query-parm="team">
+  <option value="">Every team</option>
+  <option value="Engines">Engines</option>
+</select>
+```
+
+On `change` the hub sets that one parm in the URL, leaving every other parm
+alone, and takes it out when the value is empty. The write replaces the
+current history entry; add `lb-query-parm-push` to push one instead. The page
+then loads at the new URL, exactly as a cold load of it would, without
+replacing its DOM.
+
+After every load the hub lands each parm on the control that writes it, and
+an absent parm lands empty, so the control shows what the address bar says.
+
+A control that writes a query parm sends no request, and one that also
+carries `lb-action` has that request refused.
+
+A request can write parms too, when only the write knows their value, such as
+the key of a row it inserted; see
+[refresh and patch](./page-files.md#refresh-and-patch). The page loads at
+them in the same round trip, and they land on their controls as above.
+
+The server hands the parms to `contextFor`; see
+[the Express server](./server.md#database-layer). See
+[Query parms](../TECHREF-1.0.md#query-parms) for the whole rule.
+
 ## Conditional rendering
 
 Loadbare ships static HTML and hydrates elements that are already in the

package/docs/reference/page-files.md

@@ -192,3 +192,42 @@ resetRoster: {
   refresh: ["roster"],
 },
 ```
+
+Return `queryParms()` instead when the server response changes the query
+parms: after an insert, only the server knows the new key, and after a delete,
+only the server knows the parm should go. The page loads at the query string
+with those parms set, in the same round trip, and the hub writes them into the
+URL, replacing the history entry. This is Post/Redirect/Get without the
+redirect. The refresh set does not run, and nothing else `run` returned is
+sent, since both answered for the query string the page left. Name at least
+one parm, give each a string, and use an empty string to take one out:
+
+```ts
+// src/pages/accounts.requests.ts
+import { queryParms, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  crud: {
+    accounts: {
+      rowInsert: {
+        run: async (ctx, { values }) => {
+          const id = await ctx.db.addAccount(values);
+          return queryParms({ acct: String(id) });
+        },
+        refresh: [],
+      },
+      rowDelete: {
+        run: async (ctx, { key }) => {
+          await ctx.db.deleteAccount(key);
+          if (key === ctx.acct) return queryParms({ acct: "" });
+        },
+        refresh: ["accounts"],
+      },
+    },
+  },
+};
+```
+
+Only parms: `run` cannot send the browser to another page. The loaded page
+reads the new parms through `contextFor` like any others; see
+[the Express server](./server.md#database-layer).

package/docs/reference/server.md

@@ -137,6 +137,23 @@ declare module "@loadbare/app/server" {
 }
 ```
 
+The query string the browser is showing arrives on every data request, and
+`contextFor` gets its parms as a second argument. Put on the context whatever
+a query reads from them, and treat them as user input:
+
+```ts
+function contextFor(req: Request, parms: URLSearchParams): HubContext {
+  return { db: openDb(), team: parms.get("team") ?? "" };
+}
+```
+
+Read the parms from that argument, not from `req.query`. When a server
+response changes the query parms, `contextFor` is called a second time for
+that request, with the new parms, to load the page at them; see [refresh and patch](./page-files.md#refresh-and-patch). Write it to
+be safe to call twice, and make a write visible to the second context by the
+time `run` returns: a handle opened per request, with no transaction held
+open across the two, is both.
+
 Add a field for anything else a request needs — the authenticated user, a
 request id, a feature flag set. Queries and requests read them from `ctx`; see
 [page files](./page-files.md).

package/docs/reference/widgets.md

@@ -56,7 +56,8 @@ action carries a value.
 | ---------- | ----- |
 | `exp-label` | the visible `<label>` text |
 
-Requires `lb-action` — a change with none logs and sends nothing.
+Requires `lb-action` or `lb-query-parm` — a change with neither logs and
+sends nothing. With `lb-query-parm` the hub writes the choice into the URL.
 
 ## `lb-options`
 
@@ -81,8 +82,11 @@ hand. The author supplies the row template inside the widget (via
   once, with `lb-key`.
 - `data-group` on the row template sections the options into `<optgroup>`s,
   one per distinct value, created and removed as rows arrive and leave.
+- `lb-value` selects the option with that key, including one that arrives
+  after the value did.
 - A `change` sends the action named by `lb-action`, value from the
-  select's `.value`.
+  select's `.value`. With `lb-query-parm` instead, the hub writes the
+  choice into the URL.
 
 `lb-picker` is this same class with its row template supplied by the
 definition instead of the page — see below.

package/docs/roadmap.md

@@ -34,6 +34,18 @@ A value that hasn't arrived yet is probably derivable from an absent
 `lb-value` rather than needing a signal of its own. Not yet needed because
 nothing currently produces that gap in practice — revisit if one does.
 
+### Events while a request is in flight
+
+A native action, a button or a form, ignores being performed again while its
+own round trip is in flight.  Nothing holds back any other element, so two
+round trips can be out at once and the one that answers last is what lands,
+whichever the user started last.
+
+Whether the hub should refuse every event while anything is in flight is
+open.  A widget is deliberately not held back today, because one that sends on
+change must have its latest value sent rather than dropped, and a refusal of
+everything would have to say what happens to that value.
+
 ### Validation placement
 
 Per-keystroke feedback cannot afford a round trip, so some validation will
@@ -103,6 +115,22 @@ If a dev team wishes to make their own widgets that identify `lb-list` or `lb-ro
 Perhaps a utility that can be called, like `getDataScope(el)`, to help
 clean up the code in these cases.
 
+### Refresh narrowed by query parm
+
+A query parm write loads the whole page again, every query at once.  Keyed
+landing keeps the rows that came back, so nothing on screen is disturbed, but
+the server does work for queries the parm never touched.
+
+A query could declare the parms it reads, and the hub, which holds the old
+URL and the new, could send the names that changed.  The server would run
+only the queries that read one of them, and still remember nothing.
+
+### Query parm history as a user preference
+
+A query parm write replaces the history entry, and `lb-query-parm-push`
+pushes one.  Which of the two a user wants may be the user's to say, rather
+than the page's.
+
 ### Build-time checking of `lb-action` against the declared requests
 
 Release 1.0 resolves every `lb-action` value at request time. A value naming

package/docs/theory.md

@@ -210,6 +210,12 @@ empty slot and has no opinion about what goes in it.  It does not:
 - require or prevent any authentication solution
 - expect or hinder the use of an ORM, or of `@loadbare/db`
 
+Loadbare is for applications, not sites.  Every route is answered with
+the same document, and a path that names no page is found out in the
+browser rather than answered with a 404.  The path names a page, and the
+query string describes what that page has on screen, so the address bar
+is always true and a URL can be reloaded or mailed to someone.
+
 The rule for one-time chores, such as standing up an Express Server,
 is that they stay as close as possible to "set and forget", so that
 their cost is paid once and they are not a tax on 
@@ -520,7 +526,8 @@ in the browser, providing an SPA is fairly simple.
 The hub catches anchor clicks, and checks if the anchor contains the
 attribute `lb-nav-link`.  If so, the hub interprets it as in-app
 navigation, swaps the anchor's `href` into `<main>`, and sends a request
-to the server for the page data.
+to the server for the page data.  The query string rides along, so the
+server always knows what URL the browser is showing.
 
 Anchors without the attribute behave as normal links.
 

package/docs/tutorials/010-pages-and-navigation.md

@@ -77,7 +77,8 @@ If a `<dialog lb-unknown-page>` element is present in the HTML, it will be
 displayed to the user when a URL is entered that has no matching page in the app.
 The `lb-row` and `lb-cell` attributes will be explained when we get to data
 binding; for now, know that `lb-navigation` is a query the hub itself answers
-on every navigation, and `page-uri` is the path that was asked for.  The
+on every navigation, and `page-uri` is the path and query string that were
+asked for.  The
 widget library ships this dialog ready-made as `<lb-unknown-page>`, which
 [Using Widget Libraries](./090-using-widget-libraries.md) covers.
 

package/package.json

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

package/skills/loadbare-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loadbare-app
-description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that binds HTML to server data and sends requests (`lb-list`, `lb-row`, `lb-cell`, `lb-key`, `lb-show`, `lb-action`); build-time widget expansion with `exp-*` parameters, `lb-slot` and `lb-template`; custom element code; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or widget file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that binds HTML to server data and sends requests (`lb-list`, `lb-row`, `lb-cell`, `lb-key`, `lb-show`, `lb-action`); query parms in the URL with `lb-query-parm`; build-time widget expansion with `exp-*` parameters, `lb-slot` and `lb-template`; custom element code; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or widget file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
 license: Apache-2.0
 metadata:
   package: "@loadbare/app"
@@ -159,10 +159,36 @@ for display by a widget's `lbPlaceRow`.  A list nested inside another list's
 rows receives the same rows in every outer row; use it for a picker, never
 for per-row detail.
 
-**A URL names a page, never a resource.**  Do not design `/accounts/42`.  A
-row is addressed by `list` and `key`, taken from where the element sits.
-Queries take no arguments from the browser; which record a page shows is
-server state reached through `ctx`.
+**A URL's path names a page, never a resource.**  Do not design
+`/accounts/42`.  A row is addressed by `list` and `key`, taken from where the
+element sits.
+
+**The query string is what the page has on screen.**  Which record a page
+shows, a filter, a date range: each is a query parm,
+`/accounts?acct=23&from=2026-09-09`, so a reload, a bookmark or a mailed link
+shows the same thing.  A control writes one with `lb-query-parm="acct"`, which
+replaces the history entry, reloads the page at the new URL, and sends no
+request.  A link writes several with an ordinary `lb-nav-link` href.  Queries
+still take no arguments: `contextFor(req, parms)` puts parms onto `ctx`, and
+a query reads them there.  Read them from `parms`, never `req.query`, because
+`contextFor` may be called twice for one request.  A parm is user input, so
+validate it where you read it.  Do not keep a selection in server state set
+by an action; that forces `refresh: []` and a hand-written re-answer of
+everything the selection touches.
+
+**When a server response changes the query parms.**  After an insert, only
+the server knows the new key.  After a delete, only the server knows the parm
+should go.  Have `run` return `queryParms({ acct: String(id) })`, or
+`queryParms({ acct: "" })` to remove the parm.  The page loads at the new
+query string in the same round trip, and the history entry is replaced to
+match.  This is Post/Redirect/Get without the redirect: the path never
+changes, and there is no second request.  Do not reach for a redirect, a
+hand-written refresh of every query, or server state holding the selection.
+See [refresh and patch](references/page-files.md#refresh-and-patch).
+
+**Loadbare is for applications, not sites.**  Every route is answered with
+`app.html`, and a path that names no page is found in the browser, not
+answered with a 404.  That is the design, not a defect to report.
 
 **There are no endpoints to write.**  `hubRoutes(hub, contextFor)` is the
 whole data channel.  Declare every action under `actions` and every
@@ -238,8 +264,8 @@ with the package, so no network is needed.
 - [`references/overview.md`](references/overview.md) — the map of the
   reference, by part of the application.
 - [`references/data-binding.md`](references/data-binding.md) — every `lb-`
-  attribute, requests, forms, conditions and request state.  Start here for
-  anything in a page.
+  attribute, requests, forms, query parms, conditions and request state.
+  Start here for anything in a page.
 - [`references/page-files.md`](references/page-files.md) — queries,
   `onPageEnter`, actions, CRUD, refresh and patch.
 - [`references/custom-elements.md`](references/custom-elements.md) —
@@ -254,5 +280,7 @@ with the package, so no network is needed.
 - [`references/widgets.md`](references/widgets.md) — the basic widget
   library.
 - [`references/TECHREF-1.0.md`](references/TECHREF-1.0.md) — the reserved
-  names, and the open items that block 1.0.  Read it before designing around
+  names, what a URL names and
+  [query parms](references/TECHREF-1.0.md#query-parms), and the open items
+  that block 1.0.  Read it before designing around
   something the other references do not mention.