@loadbare/app 0.5.5 → 0.6.0

package/dist/server/lb-express.js

@@ -6,70 +6,82 @@
  * 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 express from "express";
-import { LB_DATA_ENDPOINT, LB_REQUEST_ENDPOINT } from "../core/lb-constants.js";
+import { ACTION_CELL_CHANGE, ACTION_ROW_DELETE, ACTION_ROW_INSERT, ACTION_ROW_UPDATE, LB_ENDPOINT, } from "../core/lb-constants.js";
+import { isOperation } from "../core/lb-types.js";
 export function hubRoutes(hub, contextFor) {
     const router = express.Router();
     // Mounted here rather than on the app so that Hub's need for a parsed
     // body is stated where the routes that need it are.
     router.use(express.json());
-    router.get(LB_DATA_ENDPOINT, async (req, res) => {
+    router.post(LB_ENDPOINT, async (req, res) => {
         const page = String(req.query.page ?? "");
-        res.json(await hub.dataForPage(page, contextFor(req)));
-    });
-    router.post(LB_REQUEST_ENDPOINT, async (req, res) => {
-        const page = String(req.query.page ?? "");
-        // The body is unknown until op says which shape it is, so it is read
-        // once through this loose view for the case that does not match one.
-        const body = req.body;
         const request = req.body;
         const ctx = contextFor(req);
+        // No body at all is the page load: the browser is asking for this
+        // page's whole query set, which is every request it makes that names no
+        // action. A body that carries something but not an action is malformed.
+        if (request === undefined || Object.keys(request).length === 0) {
+            res.json(await hub.dataForPage(page, ctx));
+            return;
+        }
+        if (!request.action) {
+            console.warn(`loadbare: request without an action`);
+            res.status(400).json({});
+            return;
+        }
         // A thrown error is how application code (a query, an action, a CRUD
         // op) says "this request is invalid" or hits an unexpected failure —
         // it resolves to a real response rather than an unhandled rejection, so
         // the browser side has something to catch.
         try {
-            switch (request?.op) {
-                case "action": {
-                    const { name, query, key, cell, value } = request;
-                    res.json(await hub.runAction(page, name, { query, key, cell, value }, ctx));
-                    return;
-                }
-                case "cell-change": {
-                    const { query, key, cell, value } = request;
-                    res.json(await hub.runCellChange(page, { query, key, cell, value }, ctx));
+            // The reserved prefix is the whole of the discriminant: a name so
+            // prefixed is one of the four operations, and anything else is a name
+            // the page declared. Nothing else tells them apart, here or anywhere.
+            if (!isOperation(request)) {
+                const { action, list, row, key, cell, value } = request;
+                res.json(await hub.runAction(page, action, { list, row, key, cell, value }, ctx));
+                return;
+            }
+            switch (request.action) {
+                case ACTION_CELL_CHANGE: {
+                    const { list, key, cell, value } = request;
+                    res.json(await hub.runCellChange(page, { list, key, cell, value }, ctx));
                     return;
                 }
-                case "tuple-delete": {
-                    const { query, key } = request;
-                    res.json(await hub.runTupleDelete(page, { query, key }, ctx));
+                case ACTION_ROW_DELETE: {
+                    const { list, key } = request;
+                    res.json(await hub.runRowDelete(page, { list, key }, ctx));
                     return;
                 }
-                case "tuple-insert": {
-                    const { query, values } = request;
-                    res.json(await hub.runTupleInsert(page, { query, values }, ctx));
+                case ACTION_ROW_INSERT: {
+                    const { list, values } = request;
+                    res.json(await hub.runRowInsert(page, { list, values }, ctx));
                     return;
                 }
-                case "tuple-update": {
-                    const { query, key, values } = request;
-                    res.json(await hub.runTupleUpdate(page, { query, key, values }, ctx));
+                case ACTION_ROW_UPDATE: {
+                    const { list, key, values } = request;
+                    res.json(await hub.runRowUpdate(page, { list, key, values }, ctx));
                     return;
                 }
                 default:
-                    console.warn(`loadbare: operation '${body?.op}' not implemented`);
+                    console.warn(`loadbare: operation '${request.action}' not implemented`);
                     res.status(400).json({});
             }
         }
         catch (err) {
-            console.error(`loadbare: operation '${request?.op}' threw`, err);
+            console.error(`loadbare: '${request.action}' threw`, err);
             res.status(500).json({});
         }
     });

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

@@ -1,4 +1,4 @@
-import type { Projection, QueryResult, HubData, HubResult } from "../core/lb-types";
+import type { Patch, Row, HubData, HubResult } from "../core/lb-types";
 /**
  * Whatever the application hands the engine for the duration of one request.
  *
@@ -20,24 +20,40 @@ export interface HubContext {
 /**
  * A declared query: the request context in, one result out.
  *
- * A plain object is one tuple and is the common case. A query that returns
- * many tuples says so with `rows`, below.
+ * Cardinality is a property of the name rather than of any one answer, so it
+ * is declared here and never inferred from what comes back. One name answers
+ * with one shape, always. A page that wants the roster once as a single row
+ * and once as a set declares two queries.
+ *
+ * Write one with `row()` or `list()` below; nothing else builds one.
  */
-export type Query = (ctx: HubContext) => HubResult | Promise<HubResult>;
+export interface Query {
+    readonly kind: "row" | "list";
+    readonly run: (ctx: HubContext) => HubResult | Promise<HubResult>;
+}
+/** A query that answers with one row. */
+export declare function row(run: (ctx: HubContext) => Row | Promise<Row>): Query;
 /**
- * The entire set, and therefore also the order. A list widget reconciles to
- * exactly this: a row whose key is not here is gone.
+ * A query that answers with the entire set, and therefore also the order. A
+ * list reconciles to exactly this: a row whose key is not here is gone.
+ *
+ * There is no wrapper around the array, because the declaration already said
+ * this name answers with rows.
  */
-export declare function rows(list: QueryResult[]): Projection;
+export declare function list(run: (ctx: HubContext) => Row[] | Promise<Row[]>): Query;
 /**
- * Only what changed. Rows named here arrive or are updated, keys in `drop`
- * are gone, and everything unnamed is left alone — its contents, and its
- * place in whatever order the widget is keeping.
+ * Only what changed, returned from a `crud` run rather than from a query.
+ * Rows named here arrive or are updated, keys in `drop` are gone, and
+ * everything unnamed is left alone — its contents, and its place in whatever
+ * order the widget is keeping.
+ *
+ * `Array.isArray` is what tells a patch from a whole set, so a patch needs no
+ * marker of its own and no column name is reserved to carry one.
  */
 export declare function patch(change: {
-    rows?: QueryResult[];
+    rows?: Row[];
     drop?: string[];
-}): Projection;
+}): Patch;
 /** The shape of a `<name>.queries.ts` module. */
 export type Queries = Record<string, Query>;
 /**
@@ -51,7 +67,8 @@ export type Queries = Record<string, Query>;
  * argument list.
  */
 export interface Where {
-    query?: string;
+    list?: string;
+    row?: string;
     key?: string;
     cell?: string;
     value?: string;
@@ -82,87 +99,92 @@ export type CellChangeOp = CrudOp<{
     cell: string;
     value: string;
 }>;
-export type TupleDeleteOp = CrudOp<{
+export type RowDeleteOp = CrudOp<{
     key: string;
 }>;
-export type TupleInsertOp = CrudOp<{
+export type RowInsertOp = CrudOp<{
     values: Record<string, string>;
 }>;
-export type TupleUpdateOp = CrudOp<{
+export type RowUpdateOp = CrudOp<{
     key: string;
     values: Record<string, string>;
 }>;
 /**
- * The CRUD operations declared for one query, keyed by query name in
- * `Hooks.crud`. A query with no entry here permits none of them — the
- * wire cannot reach anything the page has not published, exactly as for a
- * named action.
+ * The CRUD operations declared for one list, keyed by its name in
+ * `Requests.crud`. A name with no entry here permits none of them — the wire
+ * cannot reach anything the page has not published, exactly as for a named
+ * action.
+ *
+ * Every key here is the reserved `lb-action` value with the prefix stripped
+ * and the rest camel-cased, so the attribute, the wire field and this key
+ * are one vocabulary. All four are list operations: each needs a key, and a
+ * key exists only on a live row inside a list.
  */
 export interface Crud {
     cellChange?: CellChangeOp;
-    tupleDelete?: TupleDeleteOp;
-    tupleInsert?: TupleInsertOp;
-    tupleUpdate?: TupleUpdateOp;
+    rowDelete?: RowDeleteOp;
+    rowInsert?: RowInsertOp;
+    rowUpdate?: RowUpdateOp;
 }
 /**
- * The shape of a `<name>.hooks.ts` module.
+ * The shape of a `<name>.requests.ts` module.
  *
- * `beforeGet` runs on the page's data GET, before any query. It declares no
- * refresh set: the page GET runs the whole query set afterward, so whatever
- * the hook changed is already in the response.
+ * `onPageEnter` runs once when the page is entered, before any query. It
+ * declares no refresh set: entering the page runs the whole query set
+ * afterward, so whatever the hook changed is already in the response.
  *
  * `actions` names what this page may be asked to do. A name the page did not
  * declare is refused, so the wire cannot reach anything the page has not
  * published.
  *
- * `crud` is the same rule for the typed CRUD operations, keyed by the query
+ * `crud` is the same rule for the typed CRUD operations, keyed by the list
  * they operate on rather than by a declared name — there is nothing to name,
  * since the row's own binding says what it is.
  */
-export interface Hooks {
-    beforeGet?: (ctx: HubContext) => void | Promise<void>;
+export interface Requests {
+    onPageEnter?: (ctx: HubContext) => void | Promise<void>;
     actions?: Record<string, Action>;
     crud?: Record<string, Crud>;
 }
-/** A page is four files sharing a basename; two of them are these. */
+/** A page is three files sharing a basename; two of them are these. */
 export interface Page {
     queries: Queries;
-    hooks: Hooks;
+    requests: Requests;
 }
 /**
  * The page registry. The builder populates this automatically from every
- * `.hooks.ts`/`.queries.ts` pair it discovers — see docs/reference/builder.md,
+ * `.requests.ts`/`.queries.ts` pair it discovers — see docs/reference/builder.md,
  * "Generating the server-side page registry".
  */
 export type Pages = Record<string, Page>;
 export interface Hub {
-    /** A page GET: run the page's beforeGet hook, then all of its queries. */
+    /** Entering a page: run its onPageEnter hook, then all of its queries. */
     dataForPage(page: string, ctx: HubContext): Promise<HubData>;
     /**
      * An action: run what the page declared under that name, then the refresh
      * set declared with it.
      */
     runAction(page: string, name: string, where: Where, ctx: HubContext): Promise<HubData>;
-    /** Edit one cell: run the query's declared `cellChange`, then its refresh set. */
+    /** Edit one cell: run the list's declared `cellChange`, then its refresh set. */
     runCellChange(page: string, where: {
-        query: string;
+        list: string;
         key: string;
         cell: string;
         value: string;
     }, ctx: HubContext): Promise<HubData>;
-    /** Drop one tuple: run the query's declared `tupleDelete`, then its refresh set. */
-    runTupleDelete(page: string, where: {
-        query: string;
+    /** Drop one row: run the list's declared `rowDelete`, then its refresh set. */
+    runRowDelete(page: string, where: {
+        list: string;
         key: string;
     }, ctx: HubContext): Promise<HubData>;
-    /** Add one tuple: run the query's declared `tupleInsert`, then its refresh set. */
-    runTupleInsert(page: string, where: {
-        query: string;
+    /** Add one row: run the list's declared `rowInsert`, then its refresh set. */
+    runRowInsert(page: string, where: {
+        list: string;
         values: Record<string, string>;
     }, ctx: HubContext): Promise<HubData>;
-    /** Edit several cells at once: run the query's declared `tupleUpdate`, then its refresh set. */
-    runTupleUpdate(page: string, where: {
-        query: string;
+    /** Edit several cells at once: run the list's declared `rowUpdate`, then its refresh set. */
+    runRowUpdate(page: string, where: {
+        list: string;
         key: string;
         values: Record<string, string>;
     }, ctx: HubContext): Promise<HubData>;

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

@@ -1 +1 @@
-{"version":3,"file":"lb-server.d.ts","sourceRoot":"","sources":["../../server/lb-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lb-server.d.ts","sourceRoot":"","sources":["../../server/lb-server.ts"],"names":[],"mappings":"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"}

package/dist/server/lb-server.js

@@ -4,26 +4,54 @@
 // 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";
+/** A query that answers with one row. */
+export function row(run) {
+    return { kind: "row", run };
+}
 /**
- * The entire set, and therefore also the order. A list widget reconciles to
- * exactly this: a row whose key is not here is gone.
+ * A query that answers with the entire set, and therefore also the order. A
+ * list reconciles to exactly this: a row whose key is not here is gone.
+ *
+ * There is no wrapper around the array, because the declaration already said
+ * this name answers with rows.
  */
-export function rows(list) {
-    return { op: "rows", rows: list };
+export function list(run) {
+    return { kind: "list", run };
 }
 /**
- * Only what changed. Rows named here arrive or are updated, keys in `drop`
- * are gone, and everything unnamed is left alone — its contents, and its
- * place in whatever order the widget is keeping.
+ * Only what changed, returned from a `crud` run rather than from a query.
+ * Rows named here arrive or are updated, keys in `drop` are gone, and
+ * everything unnamed is left alone — its contents, and its place in whatever
+ * order the widget is keeping.
+ *
+ * `Array.isArray` is what tells a patch from a whole set, so a patch needs no
+ * marker of its own and no column name is reserved to carry one.
  */
 export function patch(change) {
-    return { op: "patch", ...change };
+    return { ...change };
 }
 /**
  * Build the engine over a set of pages. The pages are fixed at startup; the
  * context is not, and arrives with each call.
  */
 export function createHub(pages) {
+    // Names beginning with the reserved prefix are Loadbare's — the hub's
+    // own query, the CRUD operations — so an application cannot declare one.
+    // Refused at startup, because a name is a fact about the page and not
+    // about any request.
+    for (const [page, entry] of Object.entries(pages)) {
+        const declared = [
+            ...Object.keys(entry.queries),
+            ...Object.keys(entry.requests.actions ?? {}),
+        ];
+        for (const name of declared) {
+            if (name.startsWith(LB_RESERVED_PREFIX)) {
+                throw new Error(`loadbare: page '${page}' declares '${name}', but names ` +
+                    `beginning with '${LB_RESERVED_PREFIX}' are reserved`);
+            }
+        }
+    }
     async function run(page, names, ctx) {
         const data = {};
         for (const name of names) {
@@ -32,7 +60,16 @@ export function createHub(pages) {
                 console.warn(`loadbare: page '${page}' declares no query '${name}'`);
                 continue;
             }
-            data[name] = await query(ctx);
+            const result = await query.run(ctx);
+            // Cardinality is declared, so an answer that disagrees is a mistake in
+            // the query rather than a case to handle. Refused here, because a page
+            // is better off missing one name than showing the wrong shape for it.
+            if (Array.isArray(result) !== (query.kind === "list")) {
+                console.warn(`loadbare: query '${name}' is declared ${query.kind} but answered ` +
+                    `with ${Array.isArray(result) ? "rows" : "one row"}`);
+                continue;
+            }
+            data[name] = result;
         }
         return data;
     }
@@ -57,23 +94,23 @@ export function createHub(pages) {
                 console.warn(`loadbare: no page '${page}'`);
                 return {};
             }
-            await entry.hooks.beforeGet?.(ctx);
+            await entry.requests.onPageEnter?.(ctx);
             return run(page, Object.keys(entry.queries), ctx);
         },
         runAction(page, name, where, ctx) {
-            return settle(page, pages[page]?.hooks.actions?.[name], where, ctx, `loadbare: page '${page}' declares no action '${name}'`);
+            return settle(page, pages[page]?.requests.actions?.[name], where, ctx, `loadbare: page '${page}' declares no action '${name}'`);
         },
         runCellChange(page, where, ctx) {
-            return settle(page, pages[page]?.hooks.crud?.[where.query]?.cellChange, { key: where.key, cell: where.cell, value: where.value }, ctx, `loadbare: page '${page}' declares no cell-change for query '${where.query}'`);
+            return settle(page, pages[page]?.requests.crud?.[where.list]?.cellChange, { key: where.key, cell: where.cell, value: where.value }, ctx, `loadbare: page '${page}' declares no cellChange for '${where.list}'`);
         },
-        runTupleDelete(page, where, ctx) {
-            return settle(page, pages[page]?.hooks.crud?.[where.query]?.tupleDelete, { key: where.key }, ctx, `loadbare: page '${page}' declares no tuple-delete for query '${where.query}'`);
+        runRowDelete(page, where, ctx) {
+            return settle(page, pages[page]?.requests.crud?.[where.list]?.rowDelete, { key: where.key }, ctx, `loadbare: page '${page}' declares no rowDelete for '${where.list}'`);
         },
-        runTupleInsert(page, where, ctx) {
-            return settle(page, pages[page]?.hooks.crud?.[where.query]?.tupleInsert, { values: where.values }, ctx, `loadbare: page '${page}' declares no tuple-insert for query '${where.query}'`);
+        runRowInsert(page, where, ctx) {
+            return settle(page, pages[page]?.requests.crud?.[where.list]?.rowInsert, { values: where.values }, ctx, `loadbare: page '${page}' declares no rowInsert for '${where.list}'`);
         },
-        runTupleUpdate(page, where, ctx) {
-            return settle(page, pages[page]?.hooks.crud?.[where.query]?.tupleUpdate, { key: where.key, values: where.values }, ctx, `loadbare: page '${page}' declares no tuple-update for query '${where.query}'`);
+        runRowUpdate(page, where, ctx) {
+            return settle(page, pages[page]?.requests.crud?.[where.list]?.rowUpdate, { key: where.key, values: where.values }, ctx, `loadbare: page '${page}' declares no rowUpdate for '${where.list}'`);
         },
     };
 }

package/dist/tests/assemble.test.js

@@ -43,16 +43,168 @@ describe("assemble", () => {
             await rm(src, { recursive: true, force: true });
         }
     });
-    it("still throws when the chrome uses an undefined widget", async () => {
+    it("reports a chrome widget with no definition as a used tag, for elements.ts to refuse", async () => {
+        // Expansion leaves an undefined tag alone; whether it can do anything is
+        // one rule in one place — see build/elements.ts.
         const src = await tree({
             "chrome.html": `<!doctype html><body><lb-nope></lb-nope></body>`,
         });
         try {
             const locations = await resolveLocations({ src, out: `${src}/dist` });
-            await assert.rejects(async () => assemble({ ...locations, scans: await scansFor(locations) }), /<lb-nope> has no definition/);
+            const { html, usedTags } = await assemble({
+                ...locations,
+                scans: await scansFor(locations),
+            });
+            assert.match(html, /<lb-nope><\/lb-nope>/);
+            assert.ok(usedTags.has("lb-nope"));
+        }
+        finally {
+            await rm(src, { recursive: true, force: true });
+        }
+    });
+});
+describe("the unknown-page dialog", () => {
+    it("accepts a chrome that declares none", async () => {
+        const src = await tree({
+            "chrome.html": `<!doctype html><body><lb-hub><main></main></lb-hub></body>`,
+        });
+        try {
+            const locations = await resolveLocations({ src, out: `${src}/dist` });
+            const { html } = await assemble({
+                ...locations,
+                scans: await scansFor(locations),
+            });
+            assert.doesNotMatch(html, /lb-unknown-page/);
+        }
+        finally {
+            await rm(src, { recursive: true, force: true });
+        }
+    });
+    it("refuses the attribute on anything but a <dialog>", async () => {
+        const src = await tree({
+            "chrome.html": `<!doctype html><body><lb-hub><main></main><div lb-unknown-page></div></lb-hub></body>`,
+        });
+        try {
+            const locations = await resolveLocations({ src, out: `${src}/dist` });
+            const scans = await scansFor(locations);
+            await assert.rejects(() => assemble({ ...locations, scans }), /lb-unknown-page on <div>, must be a <dialog>/);
+        }
+        finally {
+            await rm(src, { recursive: true, force: true });
+        }
+    });
+    it("refuses a dialog outside the hub, where the hub cannot reach it", async () => {
+        const src = await tree({
+            "chrome.html": `<!doctype html><body><dialog lb-unknown-page></dialog><lb-hub><main></main></lb-hub></body>`,
+        });
+        try {
+            const locations = await resolveLocations({ src, out: `${src}/dist` });
+            const scans = await scansFor(locations);
+            await assert.rejects(() => assemble({ ...locations, scans }), /lb-unknown-page outside <lb-hub>/);
         }
         finally {
             await rm(src, { recursive: true, force: true });
         }
     });
 });
+/**
+ * The binding vocabulary, checked against the finished document rather than
+ * discovered one console error at a time in a browser — see walkBinding in
+ * build/assemble.ts. Every case here is a build that must not produce output.
+ */
+describe("the binding check", () => {
+    const CHROME = `<!doctype html><body><lb-hub><main></main></lb-hub></body>`;
+    /** Assemble a chrome and one page, and hand back whatever it did. */
+    async function build(files) {
+        const src = await tree({ "chrome.html": CHROME, ...files });
+        try {
+            const locations = await resolveLocations({ src, out: `${src}/dist` });
+            const scans = await scansFor(locations);
+            return await assemble({ ...locations, scans });
+        }
+        finally {
+            await rm(src, { recursive: true, force: true });
+        }
+    }
+    async function refuses(page, pattern) {
+        await assert.rejects(() => build({ "a.page.html": page }), pattern);
+    }
+    it("refuses both scope attributes on one element", async () => {
+        await refuses(`<ul lb-list="roster" lb-row="prefs"></ul>`, /carries both lb-list and lb-row/);
+    });
+    it("refuses a cell with no scope around it", async () => {
+        await refuses(`<p><span lb-cell="name"></span></p>`, /carries lb-cell="name" with no lb-list or lb-row scope/);
+    });
+    it("refuses a cell whose only scope is inside a template with none around it", async () => {
+        // A template's children are walked in the scope enclosing the template,
+        // because a row template's clones land in the list around it.
+        await refuses(`<template><span lb-cell="name"></span></template>`, /carries lb-cell="name" with no lb-list or lb-row scope/);
+    });
+    it("refuses lb-key on anything but a template", async () => {
+        await refuses(`<ul lb-list="roster"><li lb-key="id"></li></ul>`, /<li> carries lb-key; it names the column/);
+    });
+    it("refuses lb-key on a template outside any list scope", async () => {
+        await refuses(`<div lb-row="prefs"><template lb-key="id"><p></p></template></div>`, /carries lb-key outside any lb-list scope/);
+    });
+    it("refuses a template carrying lb-key with no scope at all", async () => {
+        await refuses(`<template lb-key="id"><p></p></template>`, /carries lb-key outside any lb-list scope/);
+    });
+    it("reports every problem in one build, not the first", async () => {
+        await refuses(`<span lb-cell="name"></span><ul lb-list="a" lb-row="b"></ul>`, /no lb-list or lb-row scope[\s\S]*carries both lb-list and lb-row/);
+    });
+    it("names the file the problem is in", async () => {
+        await refuses(`<span lb-cell="name"></span>`, /a\.page\.html' binding:/);
+    });
+    it("checks the chrome as well as the pages", async () => {
+        const src = await tree({
+            "chrome.html": `<!doctype html><body><lb-hub><main></main><span lb-cell="name"></span></lb-hub></body>`,
+        });
+        try {
+            const locations = await resolveLocations({ src, out: `${src}/dist` });
+            const scans = await scansFor(locations);
+            await assert.rejects(() => assemble({ ...locations, scans }), /chrome\.html' binding:/);
+        }
+        finally {
+            await rm(src, { recursive: true, force: true });
+        }
+    });
+    it("accepts a cell in either kind of scope", async () => {
+        const { html } = await build({
+            "a.page.html": `
+        <div lb-row="prefs"><span lb-cell="theme"></span></div>
+        <ul lb-list="roster">
+          <template lb-key="id"><li lb-cell="name"></li></template>
+        </ul>`,
+        });
+        assert.match(html, /lb-cell="theme"/);
+        assert.match(html, /lb-cell="name"/);
+    });
+    it("accepts a nested scope, which begins a scope of its own", async () => {
+        const { html } = await build({
+            "a.page.html": `
+        <div lb-row="prefs">
+          <ul lb-list="roster">
+            <template lb-key="id"><li lb-cell="name"></li></template>
+          </ul>
+        </div>`,
+        });
+        assert.match(html, /lb-cell="name"/);
+    });
+    it("scopes a template's content by the scope the template itself carries", async () => {
+        // A template with no scope of its own is walked in the scope enclosing
+        // it, which is what makes a row template's cells legal. One that carries
+        // a scope establishes it for its own content instead. That is today's
+        // behavior, and this is the test that flips if it changes.
+        const { html } = await build({
+            "a.page.html": `<template lb-row="prefs"><span lb-cell="theme"></span></template>`,
+        });
+        assert.match(html, /lb-cell="theme"/);
+    });
+    it("accepts a list scope with no row template, which displays nothing", async () => {
+        // An insert form names the list it adds to and has no rows of its own.
+        const { html } = await build({
+            "a.page.html": `<form lb-list="roster" lb-action="lb-row-insert"></form>`,
+        });
+        assert.match(html, /lb-list="roster"/);
+    });
+});