@loadbare/app 0.5.5 → 0.6.0

package/dist/hub/lb-apply.js

@@ -2,15 +2,21 @@
 /**
  * Landing data on a live host — see docs/reference/data-binding.md.
  *
- * This is one file rather than part of the hub because a list widget needs
- * the same operation. It clones a row and fills it with a tuple, and filling
- * a row is filling a scope: the only difference is how much of the page the
- * root covers. A widget imports `applyTuple` the way it imports `ATTR_VALUE`,
- * so there is one implementation of what a cell means and nobody reaches into
- * anybody's children.
+ * One containment ladder, and one function per rung. `applyData` lands a
+ * whole response, `applyList` lands one list result, `applyRow` fills one
+ * scope from one row. Filling a live row and filling a single-row scope are
+ * the same operation, and the only difference is how much of the page the
+ * root covers.
+ *
+ * The row machinery used to live in its own file because every list widget
+ * imported and called it. The hub reconciles a list scope itself now, so a
+ * widget supplies placement and scaffolding through two optional hooks and
+ * never sees a whole result. Cloning the template, matching a row to the
+ * element already showing it, and filling that element are the same in every
+ * list, so no widget can get them wrong.
  */
-import { ATTR_CELL, ATTR_QUERY, ATTR_VALUE } from "../core/lb-constants";
-import { isProjection, } from "../core/lb-types";
+import { ATTR_CELL, ATTR_KEY, ATTR_KEY_VALUE, ATTR_LIST, ATTR_ROW, ATTR_ROW_COUNT, ATTR_VALUE, } from "../core/lb-constants";
+import { isPatch, } from "../core/lb-types";
 /**
  * A cell lands one of two ways. A custom element owns whatever control it
  * wraps, so it receives the value as an attribute and renders it itself.
@@ -23,55 +29,199 @@ import { isProjection, } from "../core/lb-types";
  * knowledge of any particular element.
  */
 function land(el, value) {
+    // Untouched, whatever the server sent: the browser decides what a
+    // non-string looks like. See Row in core/lb-types.ts.
     if (el.localName.includes("-"))
         el.setAttribute(ATTR_VALUE, value);
     else
         el.textContent = value;
 }
 /**
- * Fill one scope from one tuple.
+ * Whether an element under `root` belongs to root's scope, rather than to a
+ * scope nested inside it.
+ *
+ * Both scope attributes scope their DOM children, and a nested one of either
+ * kind begins a new scope (docs/reference/data-binding.md). So a descendant
+ * is in root's scope unless something between it and root — the element
+ * itself included — carries one. Root's own attribute does not count: root is
+ * the scope being filled, whatever it carries.
+ */
+function inScope(root, el) {
+    for (let node = el; node && node !== root;) {
+        if (node.hasAttribute(ATTR_LIST) || node.hasAttribute(ATTR_ROW)) {
+            return false;
+        }
+        node = node.parentElement;
+    }
+    return true;
+}
+/** Root if it matches, then every descendant in root's scope that does. */
+function within(root, selector) {
+    const found = root.matches(selector) ? [root] : [];
+    for (const el of root.querySelectorAll(selector)) {
+        if (inScope(root, el))
+            found.push(el);
+    }
+    return found;
+}
+/**
+ * Fill one scope from one row.
  *
  * The root counts as a cell if it carries one. A `<tr>` holds its cells in
  * `<td>` children, but `<option>`'s content model is text, so an option row
  * has to be the cell it displays. Requiring a wrapper there would require an
  * element HTML does not allow.
  */
-export function applyTuple(root, cells) {
-    for (const [cell, value] of Object.entries(cells)) {
-        const selector = `[${ATTR_CELL}="${cell}"]`;
-        if (root.matches(selector))
-            land(root, value);
-        for (const el of root.querySelectorAll(selector))
+export function applyRow(root, row) {
+    for (const [column, value] of Object.entries(row)) {
+        for (const el of within(root, `[${ATTR_CELL}="${column}"]`)) {
             land(el, value);
+        }
     }
 }
 /**
- * A projection has to reach a widget. A native element has one destination
- * for a value and no way to acquire children, so a list is not something it
- * can be asked to show.
+ * The row template: the one the developer wrote inside this list scope, or
+ * null when this scope shows nothing.
+ *
+ * A scope with no template is bound to the list without displaying it — an
+ * insert form names the list it adds a row to, and has no rows of its own.
+ * That is not a mistake, so it is silent. A template that does not name its
+ * key column is a mistake, and says so.
  */
-function landRows(scope, query, result) {
-    const host = scope;
-    if (typeof host.acceptRows !== "function") {
-        console.error(`lb-hub: query '${query}' returned rows, but <${scope.localName}> ` +
-            `is not a list widget`);
+function templateIn(scope) {
+    const template = scope.querySelector("template");
+    if (!template)
+        return null;
+    if (!template.getAttribute(ATTR_KEY)) {
+        console.error(`lb-hub: the <template> in <${scope.localName}> has no ${ATTR_KEY} ` +
+            `naming the column that identifies a row`);
+        return null;
+    }
+    return template;
+}
+/**
+ * The rows already showing, by the key value each carries. Only a live row
+ * carries one: the template names the key column under a different name.
+ */
+function showing(scope) {
+    const rows = new Map();
+    for (const el of scope.querySelectorAll(`[${ATTR_KEY_VALUE}]`)) {
+        rows.set(el.getAttribute(ATTR_KEY_VALUE), el);
+    }
+    return rows;
+}
+/**
+ * Land a list result in a list scope.
+ *
+ * An array is the whole set, so it decides membership and order: every row is
+ * placed in the order given, and a row whose key did not arrive is gone. A
+ * patch disturbs only what it names — a row it did not mention keeps its
+ * contents and its position.
+ *
+ * A widget that carries `lbPlaceRow` decides where a row goes, because only
+ * it knows whether it sorts or groups. Without it a row lands immediately
+ * before the template, so rows accumulate in the order they arrive and the
+ * template stays put as the insertion marker.
+ */
+export function applyList(scope, result) {
+    const template = templateIn(scope);
+    if (!template)
         return;
+    const keyColumn = template.getAttribute(ATTR_KEY);
+    const shown = showing(scope);
+    const host = scope;
+    const whole = !isPatch(result);
+    const place = (el, row) => {
+        if (host.lbPlaceRow)
+            host.lbPlaceRow(el, row, template);
+        else
+            template.parentElement.insertBefore(el, template);
+    };
+    const upsert = (row) => {
+        if (row[keyColumn] === undefined) {
+            console.error(`lb-hub: a row for <${scope.localName}> has no '${keyColumn}' column`);
+            return null;
+        }
+        // The key is stored on the row as an attribute and read back from
+        // there, so it is compared as the string the attribute holds.
+        const key = String(row[keyColumn]);
+        let el = shown.get(key);
+        const fresh = el === undefined;
+        if (!el) {
+            el = template.content.firstElementChild.cloneNode(true);
+            el.setAttribute(ATTR_KEY_VALUE, key);
+            shown.set(key, el);
+        }
+        // Fill before insertion. The attributes are already there when the row
+        // upgrades, which is the same thing that makes hydration and refresh one
+        // operation everywhere else.
+        applyRow(el, row);
+        if (fresh || whole)
+            place(el, row);
+        return key;
+    };
+    if (Array.isArray(result)) {
+        const arrived = new Set();
+        for (const row of result) {
+            const key = upsert(row);
+            if (key !== null)
+                arrived.add(key);
+        }
+        for (const [key, el] of shown)
+            if (!arrived.has(key))
+                el.remove();
     }
-    host.acceptRows(result);
+    else {
+        for (const row of result.rows ?? [])
+            upsert(row);
+        for (const key of result.drop ?? [])
+            shown.get(String(key))?.remove();
+    }
+    // How many rows are showing, counted from the DOM rather than from either
+    // branch above, so a whole set and a patch report the same fact the same
+    // way.
+    //
+    // It is stamped here because only this function knows the count: it is the
+    // one conditional a page cannot be sent, since the server answers with rows
+    // and says nothing about how many survived reconciliation. A page says what
+    // an empty list looks like in a stylesheet, and no list widget carries code
+    // for it. See docs/reference/data-binding.md.
+    scope.setAttribute(ATTR_ROW_COUNT, String(showing(scope).size));
+    // Derived scaffolding — a section heading, an <optgroup> — goes when its
+    // last row does, and only the widget knows it exists.
+    host.lbRowsLanded?.();
 }
-/** Land a whole response. Every query result arrives through here. */
+/** Land a whole response. Every result arrives through here. */
 export function applyData(root, data) {
-    for (const [query, result] of Object.entries(data)) {
-        const scopes = root.querySelectorAll(`[${ATTR_QUERY}="${query}"]`);
-        if (scopes.length === 0) {
-            console.warn(`lb-hub: no scope for query '${query}', skipping`);
+    for (const [name, result] of Object.entries(data)) {
+        const lists = root.querySelectorAll(`[${ATTR_LIST}="${name}"]`);
+        const rows = root.querySelectorAll(`[${ATTR_ROW}="${name}"]`);
+        if (lists.length === 0 && rows.length === 0) {
+            console.warn(`lb-hub: no scope for '${name}', skipping`);
+            continue;
+        }
+        // Cardinality is a property of the name, so one name is a list or a row
+        // and never both. Two spellings of it on one page is a mistake in the
+        // markup rather than a case to reconcile.
+        if (lists.length > 0 && rows.length > 0) {
+            console.error(`lb-hub: '${name}' is bound as a list in one place and a row in ` +
+                `another; a name answers with one shape`);
+            continue;
+        }
+        if (lists.length > 0) {
+            for (const scope of lists)
+                applyList(scope, result);
             continue;
         }
-        for (const scope of scopes) {
-            if (isProjection(result))
-                landRows(scope, query, result);
-            else
-                applyTuple(scope, result);
+        // The only disagreement visible from here: a patch and a row are both
+        // objects, so an array arriving at a row scope is the one case the
+        // browser can name. createHub holds the stronger check, because it knows
+        // what the query declared.
+        if (Array.isArray(result)) {
+            console.error(`lb-hub: '${name}' is bound with ${ATTR_ROW} but answered with rows`);
+            continue;
         }
+        for (const scope of rows)
+            applyRow(scope, result);
     }
 }

package/dist/hub/lb-hub.browser.d.ts

@@ -1,2 +1,2 @@
-export { applyData, applyTuple } from "./lb-apply";
+export { applyData, applyRow } from "./lb-apply";
 //# sourceMappingURL=lb-hub.browser.d.ts.map

package/dist/hub/lb-hub.browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lb-hub.browser.d.ts","sourceRoot":"","sources":["../../hub/lb-hub.browser.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"lb-hub.browser.d.ts","sourceRoot":"","sources":["../../hub/lb-hub.browser.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/hub/lb-hub.browser.js

@@ -1,18 +1,25 @@
 /// <reference lib="dom" />
-import { ATTR_ACTION, ATTR_CELL, ATTR_DELETE, ATTR_ERROR, ATTR_INSERT, ATTR_KEY, ATTR_NAV_LINK, ATTR_PENDING, ATTR_QUERY, ATTR_UNKNOWN_PAGE, ATTR_UPDATE, HUB_TAG_NAME, PAGE_TEMPLATE_PREFIX, LB_DATA_ENDPOINT, LB_EVENT_NAME, LB_REQUEST_ENDPOINT, LB_REQUEST_TIMEOUT_MS, } from "../core/lb-constants";
-import { applyData, applyTuple } from "./lb-apply";
-export { applyData, applyTuple } from "./lb-apply";
+import { ACTION_ROW_DELETE, ACTION_ROW_INSERT, ACTION_ROW_UPDATE, ATTR_ACTION, ATTR_CELL, ATTR_ERROR, ATTR_KEY_VALUE, ATTR_LIST, ATTR_NAV_LINK, ATTR_PAGE, ATTR_PENDING, ATTR_ROW, ATTR_UNKNOWN_PAGE, LB_ACTIONS, LB_RESERVED_PREFIX, HUB_TAG_NAME, NAV_CELL_LABEL, NAV_CELL_URI, NAV_ROW, LB_EVENT_NAME, LB_ENDPOINT, LB_REQUEST_TIMEOUT_MS, } from "../core/lb-constants";
+import { applyData } from "./lb-apply";
+export { applyData, applyRow } from "./lb-apply";
 /**
  * Where a click happened, in the binding vocabulary. An action carries
  * these and nothing else, so there is no channel for a browser-supplied
  * argument.
+ *
+ * The scope field is `list` or `row`, whichever attribute scoped the nearest
+ * ancestor, so an action fired inside a single-row scope says so and the
+ * wire never needs a noun for the addressable thing.
  */
 function binding(el) {
-    const query = el.closest(`[${ATTR_QUERY}]`)?.getAttribute(ATTR_QUERY);
-    const key = el.closest(`[${ATTR_KEY}]`)?.getAttribute(ATTR_KEY);
+    const scope = el.closest(`[${ATTR_LIST}], [${ATTR_ROW}]`);
+    const list = scope?.getAttribute(ATTR_LIST) ?? null;
+    const row = list === null ? (scope?.getAttribute(ATTR_ROW) ?? null) : null;
+    const key = el.closest(`[${ATTR_KEY_VALUE}]`)?.getAttribute(ATTR_KEY_VALUE);
     const cell = el.getAttribute(ATTR_CELL);
     return {
-        ...(query === null || query === undefined ? {} : { query }),
+        ...(list === null ? {} : { list }),
+        ...(row === null ? {} : { row }),
         ...(key === null || key === undefined ? {} : { key }),
         ...(cell === null ? {} : { cell }),
     };
@@ -61,6 +68,29 @@ function pageNameFor(path) {
     const name = path.replace(/^\/+|\/+$/g, "");
     return name === "" ? "index" : name;
 }
+/**
+ * The `<template>` a page's markup ships in. The builder guarantees one per
+ * page name (build/locations.ts refuses two page files sharing a stub), so
+ * a second match here means the document was assembled by something else,
+ * and is worth saying out loud rather than resolving by document order.
+ */
+function pageHostFor(page) {
+    const hosts = [];
+    for (const el of document.querySelectorAll(`template[${ATTR_PAGE}]`)) {
+        if (el.getAttribute(ATTR_PAGE) === page) {
+            hosts.push(el);
+        }
+    }
+    if (hosts.length === 0) {
+        console.error(`lb-hub: no page host for '${page}'`);
+        return null;
+    }
+    if (hosts.length > 1) {
+        console.error(`lb-hub: ${hosts.length} page hosts carry ${ATTR_PAGE}="${page}", ` +
+            `using the first`);
+    }
+    return hosts[0];
+}
 /**
  * Fetch one round trip against the client-side deadline. Throws — rather
  * than swallowing — on a non-ok response, a network failure, or a timeout,
@@ -68,11 +98,18 @@ function pageNameFor(path) {
  * only ever wants the freshest data, like navigate()) can tell the two
  * apart from a genuinely empty result.
  */
-async function fetchData(url, init) {
+async function fetchData(page, request) {
+    const url = `${LB_ENDPOINT}?page=${encodeURIComponent(page)}`;
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), LB_REQUEST_TIMEOUT_MS);
     try {
-        const res = await fetch(url, { ...init, signal: controller.signal });
+        // An empty body is how the hub asks for the page's whole query set.
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(request ?? {}),
+            signal: controller.signal,
+        });
         if (!res.ok) {
             throw new Error(`lb-hub: server responded ${res.status} for ${url}`);
         }
@@ -89,7 +126,7 @@ async function fetchData(url, init) {
 class LbHub extends HTMLElement {
     main;
     /**
-     * The page currently in <main>. Hooks are declared per page, so a request
+     * The page currently in <main>. A page declares its own requests, so a request
      * has to say which page it came from. The page rides on the URL rather
      * than in the request, leaving the operation set closed.
      */
@@ -98,8 +135,18 @@ class LbHub extends HTMLElement {
         this.main = this.querySelector("main");
         this.addEventListener(LB_EVENT_NAME, (e) => {
             const request = e.detail;
-            if (!request?.op) {
-                console.warn(`lb-hub: event without an op, ignoring`, request);
+            if (!request?.action) {
+                console.warn(`lb-hub: event without an action, ignoring`, request);
+                return;
+            }
+            // The reserved prefix is the whole of the discriminant, so a reserved
+            // name that is not one of the four operations is a typo rather than
+            // something to forward. Refused here, where the widget can see why: a
+            // server would only report that it declares no such action.
+            if (request.action.startsWith(LB_RESERVED_PREFIX) &&
+                !LB_ACTIONS.includes(request.action)) {
+                console.error(`lb-hub: '${request.action}' begins with '${LB_RESERVED_PREFIX}' ` +
+                    `but names no operation, ignoring`);
                 return;
             }
             // The element that dispatched the request, not e.currentTarget (the
@@ -108,12 +155,7 @@ class LbHub extends HTMLElement {
             const origin = e.target;
             origin?.removeAttribute(ATTR_ERROR);
             origin?.setAttribute(ATTR_PENDING, "");
-            const url = `${LB_REQUEST_ENDPOINT}?page=${encodeURIComponent(this.page)}`;
-            void fetchData(url, {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify(request),
-            })
+            void fetchData(this.page, request)
                 .then((data) => applyData(this, data))
                 .catch((err) => {
                 console.error(`lb-hub: request failed`, err);
@@ -137,73 +179,29 @@ class LbHub extends HTMLElement {
             const el = e.target?.closest(`[${ATTR_ACTION}]`);
             if (!el || el.localName.includes("-"))
                 return;
-            e.preventDefault();
-            const detail = {
-                op: "action",
-                name: el.getAttribute(ATTR_ACTION),
-                ...binding(el),
-            };
-            el.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
-        });
-        // The CRUD counterpart to the lb-action delegation above: a native
-        // element needs no declared name to delete the row it is in, only its
-        // own query/key binding.
-        this.addEventListener("click", (e) => {
-            const el = e.target?.closest(`[${ATTR_DELETE}]`);
-            if (!el || el.localName.includes("-"))
+            // A form performs its action on submit, whatever was clicked in it.
+            if (el instanceof HTMLFormElement)
                 return;
             e.preventDefault();
-            const { query, key } = binding(el);
-            if (!query || !key) {
-                console.warn(`lb-hub: lb-delete with no query/key binding, ignoring`, el);
-                return;
+            const name = el.getAttribute(ATTR_ACTION);
+            const detail = this.requestFor(name, el);
+            if (detail) {
+                el.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
             }
-            const detail = { op: "tuple-delete", query, key };
-            el.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
         });
-        // The CRUD op that gathers rather than binds a single cell: every
-        // lb-cell inside the form becomes one entry of the values map. There is
-        // no key, because there is no row yet — only the query, found the same
-        // way binding() finds one for a click, says what it is inserting
-        // into.
+        // The same delegation for the event a form owns. A reserved name here
+        // gathers the form's cells; a declared one carries the binding, as a
+        // click does.
         this.addEventListener("submit", (e) => {
-            const form = e.target?.closest(`[${ATTR_INSERT}]`);
-            if (!form)
+            const form = e.target;
+            if (!form || !form.hasAttribute(ATTR_ACTION))
                 return;
             e.preventDefault();
-            const { query } = binding(form);
-            if (!query) {
-                console.warn(`lb-hub: lb-insert with no lb-query, ignoring`, form);
-                return;
+            const name = form.getAttribute(ATTR_ACTION);
+            const detail = this.requestFor(name, form);
+            if (detail) {
+                form.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
             }
-            const detail = {
-                op: "tuple-insert",
-                query,
-                values: gatherValues(form),
-            };
-            form.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
-        });
-        // The batch counterpart to cell-change: same gathering as lb-insert, but
-        // with the key of the row it is a form for — a list's row template root,
-        // or a form inside one, has it from the same ancestor a delete button
-        // reads.
-        this.addEventListener("submit", (e) => {
-            const form = e.target?.closest(`[${ATTR_UPDATE}]`);
-            if (!form)
-                return;
-            e.preventDefault();
-            const { query, key } = binding(form);
-            if (!query || !key) {
-                console.warn(`lb-hub: lb-update with no query/key binding, ignoring`, form);
-                return;
-            }
-            const detail = {
-                op: "tuple-update",
-                query,
-                key,
-                values: gatherValues(form),
-            };
-            form.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
         });
         // Only anchors that opted in. Everything else is a real link.
         this.addEventListener("click", (e) => {
@@ -223,12 +221,62 @@ class LbHub extends HTMLElement {
      * already in the document, so selecting a page is getElementById() and
      * there is no fetching mechanism on the host channel.
      */
+    /**
+     * What a native element carrying `lb-action` asks for. A reserved name is
+     * one of the CRUD operations and takes the binding that operation needs;
+     * any other name is an action the page declared, carrying whatever
+     * binding is in scope. A reserved name the hub does not turn into an
+     * operation here — a cell change, which needs a widget to say what a
+     * change is, or a name nobody reserved — is refused rather than sent.
+     */
+    requestFor(name, el) {
+        const { list, row, key, cell } = binding(el);
+        const form = el instanceof HTMLFormElement;
+        switch (name) {
+            case ACTION_ROW_DELETE:
+                if (list && key)
+                    return { action: ACTION_ROW_DELETE, list, key };
+                break;
+            case ACTION_ROW_INSERT:
+                if (form && list) {
+                    return {
+                        action: ACTION_ROW_INSERT,
+                        list,
+                        values: gatherValues(el),
+                    };
+                }
+                break;
+            case ACTION_ROW_UPDATE:
+                if (form && list && key) {
+                    return {
+                        action: ACTION_ROW_UPDATE,
+                        list,
+                        key,
+                        values: gatherValues(el),
+                    };
+                }
+                break;
+            default:
+                if (!name.startsWith(LB_RESERVED_PREFIX)) {
+                    return {
+                        action: name,
+                        ...(list === undefined ? {} : { list }),
+                        ...(row === undefined ? {} : { row }),
+                        ...(key === undefined ? {} : { key }),
+                        ...(cell === undefined ? {} : { cell }),
+                    };
+                }
+        }
+        console.warn(`lb-hub: ${ATTR_ACTION}="${name}" on <${el.localName}> cannot be ` +
+            `sent from here, ignoring`, el);
+        return null;
+    }
     async navigate(path) {
         const page = pageNameFor(path);
-        const template = document.getElementById(PAGE_TEMPLATE_PREFIX + page);
-        if (!(template instanceof HTMLTemplateElement)) {
-            console.error(`lb-hub: no page host for '${page}'`);
-            this.reportUnknownPage(page);
+        this.landNavigation(path, page);
+        const template = pageHostFor(page);
+        if (!template) {
+            this.reportUnknownPage();
             this.reveal();
             return;
         }
@@ -240,7 +288,7 @@ class LbHub extends HTMLElement {
         this.reveal();
         let data = {};
         try {
-            data = await fetchData(`${LB_DATA_ENDPOINT}?page=${encodeURIComponent(page)}`);
+            data = await fetchData(page);
         }
         catch (err) {
             console.error(`lb-hub: failed to load data for '${page}'`, err);
@@ -256,6 +304,38 @@ class LbHub extends HTMLElement {
     reveal() {
         document.body.hidden = false;
     }
+    /**
+     * The hub's own row: where the page is, in the vocabulary a server
+     * answer arrives in, so a chrome displays it the way it displays anything
+     * — `lb-row="lb-navigation"` on a subtree, `lb-cell` on what shows a
+     * value. Landed before the page host is looked up, so a miss has it too;
+     * the unknown-page dialog is one consumer among whatever others the
+     * chrome writes.
+     *
+     * The label is the nav's: the text of the first lb-nav-link anchor whose
+     * href names this page. Taken from the nav rather than from a click, so a
+     * click, a reload and the back button all land the same label — and a
+     * path no anchor names lands an empty one, explicitly, so a consumer is
+     * never left showing the previous page's.
+     *
+     * Landed only where a subtree names it. applyData() warns about a query
+     * with no scope, and a chrome that displays no navigation has nothing to
+     * be warned about.
+     */
+    landNavigation(path, page) {
+        if (!this.querySelector(`[${ATTR_ROW}="${NAV_ROW}"]`))
+            return;
+        let label = "";
+        for (const a of this.querySelectorAll(`a[${ATTR_NAV_LINK}]`)) {
+            if (pageNameFor(new URL(a.href).pathname) !== page)
+                continue;
+            label = a.textContent?.trim() ?? "";
+            break;
+        }
+        applyData(this, {
+            [NAV_ROW]: { [NAV_CELL_LABEL]: label, [NAV_CELL_URI]: path },
+        });
+    }
     /**
      * A path that resolves to no page host is discovered client-side, after a
      * successful 200 — every route gets the same document, so there is no
@@ -265,14 +345,16 @@ class LbHub extends HTMLElement {
      * element it's on is a <dialog> (build/assemble.ts), so this can call
      * showModal() without checking the tag here.
      *
+     * Only opens it. What the dialog says it gets from landNavigation(),
+     * already run, by naming the hub's row in lb-row like any subtree.
+     *
      * Scoped to the hub, like every other lookup here, so that one rule holds
      * without exception: what the hub acts on is inside the hub.
      */
-    reportUnknownPage(page) {
+    reportUnknownPage() {
         const dialog = this.querySelector(`[${ATTR_UNKNOWN_PAGE}]`);
         if (!dialog)
             return;
-        applyTuple(dialog, { page });
         const modal = dialog;
         if (!modal.open)
             modal.showModal();

package/dist/server/lb-express.d.ts

@@ -6,13 +6,16 @@
  * Express itself is a peer dependency: nothing outside this file imports it,
  * so an application that hosts Hub some other way never pays for it.
  *
- * Two endpoints, and no third:
+ * One endpoint, and no second:
  *
- *   GET  /hub/data?page=<name>   the page's whole query set
- *   POST /hub?page=<name>        one operation, then its refresh set
+ *   POST /lb?page=<name>   an empty body asks for the page's whole query
+ *                          set; a body carrying an action runs that action
+ *                          and answers with its refresh set
  *
  * The page rides on the query string rather than in the body, which is what
- * lets the operation set stay closed.
+ * lets the operation set stay closed. Every hub call is a POST, so an
+ * application's own GET routes never collide with this one and no page name
+ * is reserved.
  */
 import { type Request, type Router } from "express";
 import type { Hub, HubContext } from "./lb-server";

package/dist/server/lb-express.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lb-express.d.ts","sourceRoot":"","sources":["../../server/lb-express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAgB,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,UAAU,CAAC;AAEtD,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAkElE"}
+{"version":3,"file":"lb-express.d.ts","sourceRoot":"","sources":["../../server/lb-express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAgB,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAS7D,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,UAAU,CAAC;AAEtD,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAkFlE"}