@loadbare/app 0.4.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,95 @@
+# Loadbare App
+
+> **This project is being refactored.** While @loadbare/db is highly mature
+> and in use reliably by the author, this ui project is being built from
+> scratch.  We know what it will do, but everything has to be built.
+
+## Purpose
+
+Loadbare App is a web app framework built specifically to deliver high performance
+to the user for server-bound applications. 
+
+Loadbare App has two twin primary goals
+- To follow the loadbare philosophy of reducing accidental complexity
+  to near zero, so the app developer is spending maximum time on the app
+  instead of the tooling.
+- To give the developer a fighting chance to provide complete server round
+  trips, from request to final paint, in 300ms or less
+
+## Current WIP
+
+Restructuring the docs.  Right now "getting started"
+and other docs are very limited because they only document what we've
+tested and proven.  Once the build is doing everything it needs to,
+then we can write the docs to flow more like:
+- setting up your infra:
+  - add the package
+  - chrome
+  - express server
+- writing a page with mock db access
+  - wiring express to call our handler
+  - the html
+  - hooks and handlers
+- plugging in your database, just replace mock with your
+  own adapter.
+
+
+## SLOP LINE
+
+Below here is LLM-generated slop, not yet edited to conform to our rules
+against LLM-generated markdown docs.
+
+
+## Ideals
+
+Loadbare App should be fully inspectable. "View Source" should show the source, and
+what it shows should be what the developer tools show. Frameworks commonly
+lose this property as a side effect of how they generate markup; Loadbare App treats
+keeping it as a requirement.
+
+Stated precisely, because two things legitimately differ: no markup exists in
+the DOM that is not in view-source, and the difference between view-source and
+the developer tools is exactly the dynamic half. Navigation moves markup that
+is already in the document, and data lands on it as attributes. Neither
+invents markup.
+
+Some widgets, an enriched table being the obvious one, must clone a template
+once per row, and the number of rows is not known until the data arrives. That
+cloning is allowable: the markup is in view-source, and only the count comes
+from the data. Where the boundary of that allowance sits is stated in
+[Theory of Loadbare App](./docs/theory.md).
+
+Nothing here is about protecting the HTML, which is visible in the developer
+tools regardless. It is about the technology being open to inspection by
+whoever wants to look.
+
+## Documentation
+
+[`docs/theory.md`](./docs/theory.md) states what Loadbare App is and
+why. It is authoritative; where any other document disagrees with it, the other
+document is wrong.
+
+- [Programmer's Guide](./docs/guide.md) — how to build an application with
+  Loadbare App. Each section is marked with whether the code does it yet.
+- [Hosting a Loadbare App Application](./docs/hosting.md) — registering pages,
+  assembling the shell, navigation, and serving the two endpoints from
+  Express. Everything you do once per application rather than once per page.
+- [Theory of Loadbare App](./docs/theory.md) — scope, the performance budget,
+  the thesis, and what is settled so far.
+- [Communication channels](./docs-llm-slop/communication-channels.md) — what
+  the host/data split means on the wire.
+- [Data binding](./docs-llm-slop/data-binding.md) — the addressing vocabulary
+  and how a data fragment lands on a widget.
+- [Requests](./docs-llm-slop/requests.md) — how a widget reaches the server,
+  and what the server may trust.
+- [Bundling](./docs-llm-slop/bundling.md) — how the static half is packaged
+  and shipped.
+- [Expansion](./docs-llm-slop/expansion.md) — how one authored tag becomes the
+  tree it stands for, and why the definition language has no control flow.
+- [Coming from other frameworks](./docs-llm-slop/coming-from-other-frameworks.md)
+  — what changes if you already know React, Angular, htmx or Datastar.
+- [Prior art](./docs-llm-slop/prior-art.md) — what has been done before, and
+  why nothing was adopted off the shelf.
+
+The guide states the API as it should be and marks each section with whether
+the code does it yet. Where the two disagree, the code is what moves.

package/dist/build/assemble.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Assembling one document out of a chrome file and a set of pages.
+ *
+ * Every `.html` file in play — the chrome and each page — goes through the
+ * same `expand()` (see build/expand.ts) against the same definitions: the
+ * built-in widgets and whatever definitions were found in the caller's own
+ * source tree. `expand()` only ever sees a fragment, so the chrome's own is
+ * the text between its `<body>` tags; a page's is the whole file. A page's
+ * expanded host is wrapped in `<template id="page-<name>">` and, together
+ * with the chrome's own expanded body content, spliced back into the
+ * chrome's `<body>`. The result is the one document a server has to serve
+ * for every route — see docs/getting-started.md and docs/application-chrome.md.
+ *
+ * Every path here is a parameter, resolved once by build/locations.ts — this
+ * module never reconstructs one of its own, and never reads a directory
+ * looking for pages or widgets; it is handed exactly which files those are.
+ */
+import type { PageFile, WidgetSource } from "./locations.js";
+export interface AssembleOptions {
+    chromeFile: string;
+    pages: PageFile[];
+    widgets: Map<string, WidgetSource>;
+    builtinWidgetsDir: string;
+}
+export interface Assembled {
+    html: string;
+    /** Every custom element tag left in the document once expansion is done. */
+    usedTags: Set<string>;
+}
+export declare function assemble({ chromeFile, pages, widgets, builtinWidgetsDir, }: AssembleOptions): Promise<Assembled>;
+//# sourceMappingURL=assemble.d.ts.map

package/dist/build/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../build/assemble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB;AAED,wBAAsB,QAAQ,CAAC,EAC7B,UAAU,EACV,KAAK,EACL,OAAO,EACP,iBAAiB,GAClB,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CA2CtC"}

package/dist/build/assemble.js

@@ -0,0 +1,53 @@
+/**
+ * Assembling one document out of a chrome file and a set of pages.
+ *
+ * Every `.html` file in play — the chrome and each page — goes through the
+ * same `expand()` (see build/expand.ts) against the same definitions: the
+ * built-in widgets and whatever definitions were found in the caller's own
+ * source tree. `expand()` only ever sees a fragment, so the chrome's own is
+ * the text between its `<body>` tags; a page's is the whole file. A page's
+ * expanded host is wrapped in `<template id="page-<name>">` and, together
+ * with the chrome's own expanded body content, spliced back into the
+ * chrome's `<body>`. The result is the one document a server has to serve
+ * for every route — see docs/getting-started.md and docs/application-chrome.md.
+ *
+ * Every path here is a parameter, resolved once by build/locations.ts — this
+ * module never reconstructs one of its own, and never reads a directory
+ * looking for pages or widgets; it is handed exactly which files those are.
+ */
+import { readFile } from "node:fs/promises";
+import { addDefinitions, customElementTags, expand, loadDefinitions, } from "./expand.js";
+import { formatHtml } from "./format.js";
+import { PAGE_TEMPLATE_PREFIX } from "../core/lb-constants.js";
+export async function assemble({ chromeFile, pages, widgets, builtinWidgetsDir, }) {
+    const widgetHtmlFiles = new Map();
+    for (const [tag, source] of widgets) {
+        if (source.html)
+            widgetHtmlFiles.set(tag, source.html);
+    }
+    const defs = await addDefinitions(await loadDefinitions([builtinWidgetsDir]), widgetHtmlFiles);
+    const templates = [];
+    for (const { name, file } of pages) {
+        const authored = await readFile(file, "utf-8");
+        const host = expand(authored, defs);
+        templates.push(`<template id="${PAGE_TEMPLATE_PREFIX}${name}">${host}</template>`);
+    }
+    let chromeSource;
+    try {
+        chromeSource = await readFile(chromeFile, "utf-8");
+    }
+    catch {
+        throw new Error(`assemble: no chrome file at '${chromeFile}'`);
+    }
+    const body = /<body([^>]*)>([\s\S]*)<\/body>/i.exec(chromeSource);
+    if (!body) {
+        throw new Error(`assemble: '${chromeFile}' has no <body>...</body> to expand`);
+    }
+    const [whole, bodyAttrs, bodyContent] = body;
+    const expandedBody = expand(bodyContent, defs);
+    const withPages = chromeSource.replace(whole, () => `<body${bodyAttrs}>${expandedBody}\n${templates.join("\n")}\n</body>`);
+    return {
+        html: await formatHtml(withPages),
+        usedTags: customElementTags(withPages),
+    };
+}

package/dist/build/cli.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * loadbare-app-build — assemble a chrome file and its pages into one HTML
+ * document, and bundle the client script for exactly the custom elements
+ * that document uses. See docs/getting-started.md.
+ *
+ *   loadbare-app-build [--src src] [--out dist] [--watch]
+ *
+ * `--src` names the tree scanned for everything: the one `*.chrome.html`
+ * file, every `*.page.html` page, every other `.html`/`.ts` as a widget,
+ * `*.hooks.ts`/`*.queries.ts` pairs, and `elements.ts` if there is one — see
+ * build/locations.ts for how a file's name says what it is. The assembled
+ * document is written to `<out>/app.html`; the client bundle to
+ * `<out>/client.js`, by way of a generated `<out>/client-entry.ts` — see
+ * build/elements.ts for how a tag is resolved to the script that registers
+ * it. When any page has a hooks or queries file, the hub registry that used
+ * to be hand-maintained is written to `<out>/pages.ts` — see build/pages.ts.
+ * Every `.css` file anywhere under `<src>` is concatenated, in the order
+ * described in build/locations.ts, and written to `<out>/app.css` — see
+ * build/styles.ts.
+ *
+ * Without `--watch`, this runs once and exits. With it, every `.html`,
+ * `.ts` and `.css` file under `<src>` is watched — a page, a widget's
+ * markup, a widget's class, a stylesheet, and `elements.ts` all feed the
+ * same build — and a rebuild that throws is reported without stopping the
+ * watch. There is no dev server and no browser reload here, only the files
+ * on disk staying current for the next manual refresh.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/build/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../build/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/build/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * loadbare-app-build — assemble a chrome file and its pages into one HTML
+ * document, and bundle the client script for exactly the custom elements
+ * that document uses. See docs/getting-started.md.
+ *
+ *   loadbare-app-build [--src src] [--out dist] [--watch]
+ *
+ * `--src` names the tree scanned for everything: the one `*.chrome.html`
+ * file, every `*.page.html` page, every other `.html`/`.ts` as a widget,
+ * `*.hooks.ts`/`*.queries.ts` pairs, and `elements.ts` if there is one — see
+ * build/locations.ts for how a file's name says what it is. The assembled
+ * document is written to `<out>/app.html`; the client bundle to
+ * `<out>/client.js`, by way of a generated `<out>/client-entry.ts` — see
+ * build/elements.ts for how a tag is resolved to the script that registers
+ * it. When any page has a hooks or queries file, the hub registry that used
+ * to be hand-maintained is written to `<out>/pages.ts` — see build/pages.ts.
+ * Every `.css` file anywhere under `<src>` is concatenated, in the order
+ * described in build/locations.ts, and written to `<out>/app.css` — see
+ * build/styles.ts.
+ *
+ * Without `--watch`, this runs once and exits. With it, every `.html`,
+ * `.ts` and `.css` file under `<src>` is watched — a page, a widget's
+ * markup, a widget's class, a stylesheet, and `elements.ts` all feed the
+ * same build — and a rebuild that throws is reported without stopping the
+ * watch. There is no dev server and no browser reload here, only the files
+ * on disk staying current for the next manual refresh.
+ */
+import { parseArgs } from "node:util";
+import { mkdir, watch, writeFile } from "node:fs/promises";
+import path from "node:path";
+import * as esbuild from "esbuild";
+import { assemble } from "./assemble.js";
+import { clientEntrySource, resolveElements } from "./elements.js";
+import { resolveLocations } from "./locations.js";
+import { pagesSource } from "./pages.js";
+import { stylesSource } from "./styles.js";
+const { values } = parseArgs({
+    options: {
+        src: { type: "string", default: "src" },
+        out: { type: "string", default: "dist" },
+        watch: { type: "boolean", default: false },
+    },
+});
+const srcDir = values.src;
+async function build() {
+    const locations = await resolveLocations({ src: srcDir, out: values.out });
+    const outFile = path.join(locations.outDir, "app.html");
+    const entryFile = path.join(locations.outDir, "client-entry.ts");
+    const clientFile = path.join(locations.outDir, "client.js");
+    const { html, usedTags } = await assemble(locations);
+    await mkdir(locations.outDir, { recursive: true });
+    await writeFile(outFile, html, "utf-8");
+    const { resolved } = await resolveElements({ used: usedTags, ...locations });
+    await writeFile(entryFile, clientEntrySource(resolved, locations.outDir), "utf-8");
+    await esbuild.build({
+        entryPoints: [entryFile],
+        bundle: true,
+        format: "iife",
+        outfile: clientFile,
+    });
+    const generatedPages = pagesSource(locations.pages, locations.pageSources, locations.outDir, locations.packageName);
+    let pagesMessage = "";
+    if (generatedPages) {
+        const pagesFile = path.join(locations.outDir, "pages.ts");
+        await writeFile(pagesFile, generatedPages, "utf-8");
+        pagesMessage = ` and ${pagesFile}`;
+    }
+    const generatedCss = await stylesSource(locations.cssFiles);
+    let cssMessage = "";
+    if (generatedCss) {
+        const cssFile = path.join(locations.outDir, "app.css");
+        await writeFile(cssFile, generatedCss, "utf-8");
+        cssMessage = ` and ${cssFile}`;
+    }
+    console.log(`loadbare-app-build: wrote ${outFile} and ${clientFile}${pagesMessage}${cssMessage} ` +
+        `(${resolved.size} custom element${resolved.size === 1 ? "" : "s"})`);
+}
+async function main() {
+    try {
+        await build();
+    }
+    catch (err) {
+        console.error(`loadbare-app-build: ${err.message}`);
+        if (!values.watch) {
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (!values.watch)
+        return;
+    console.log(`loadbare-app-build: watching ${srcDir}`);
+    const watcher = watch(srcDir, { recursive: true });
+    for await (const event of watcher) {
+        if (!event.filename?.endsWith(".html") &&
+            !event.filename?.endsWith(".ts") &&
+            !event.filename?.endsWith(".css"))
+            continue;
+        try {
+            await build();
+        }
+        catch (err) {
+            console.error(`loadbare-app-build: ${err.message}`);
+        }
+    }
+}
+void main();

package/dist/build/elements.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Validating that a custom element a build actually uses can do something —
+ * and finding the script to import for it when it can.
+ *
+ * A used tag is valid if it has a script, a definition, or both:
+ *   - a script registers the class that upgrades it. It can come from a
+ *     built-in source (this package's own widgets/ or hub/ — hub/ is where
+ *     lb-hub itself lives, discovered exactly the same way as any built-in
+ *     widget, no special case for it here), an application's own — found
+ *     anywhere in its source tree by build/locations.ts, not confined to a
+ *     directory — or a third party's, declared by tag in `elements.ts`.
+ *   - a definition (an `.html` file, built-in or local) expands the tag's
+ *     content at build time. A widget with only a definition and no script
+ *     is markup only: expansion already gave it everything it will ever
+ *     have, and the tag survives just as an inert wrapper (see expand.ts).
+ *
+ * A tag with neither — no script anywhere and no definition — would do
+ * nothing were it ever to reach the browser, so that is an error.
+ *
+ * Every directory and file here is a parameter, resolved once by
+ * build/locations.ts — this module never reconstructs one of its own, and
+ * the application's own widgets are handed over already found, not scanned
+ * again here.
+ */
+import { type WidgetSource } from "./locations.js";
+/** The shape of an `elements.ts` module's default export. */
+export type ElementManifest = Record<string, string>;
+/** A resolved tag: a bare specifier to import, or a local file to import by relative path. */
+export type Resolved = {
+    kind: "specifier";
+    value: string;
+} | {
+    kind: "file";
+    value: string;
+};
+/**
+ * `elements.ts`, executed rather than parsed — it runs through the same
+ * loader as the rest of the build, so it is ordinary TypeScript, not a data
+ * format with its own rules.
+ */
+export declare function loadElementManifest(file: string): Promise<ElementManifest>;
+export interface ResolveOptions {
+    used: Set<string>;
+    widgets: Map<string, WidgetSource>;
+    elementsFile?: string;
+    builtinWidgetsDir: string;
+    builtinHubDir: string;
+    packageName: string;
+}
+export interface ResolveResult {
+    resolved: Map<string, Resolved>;
+}
+export declare function resolveElements({ used, widgets, elementsFile, builtinWidgetsDir, builtinHubDir, packageName, }: ResolveOptions): Promise<ResolveResult>;
+/**
+ * The generated client entry point — every custom element the assembled
+ * document actually uses, and nothing else. Written to `outDir` so a
+ * relative import to a local widget resolves the ordinary way; a specifier
+ * (built-in or third-party) is written as the bare string it is.
+ */
+export declare function clientEntrySource(resolved: Map<string, Resolved>, outDir: string): string;
+//# sourceMappingURL=elements.d.ts.map

package/dist/build/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../build/elements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEvE,6DAA6D;AAC7D,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD,8FAA8F;AAC9F,MAAM,MAAM,QAAQ,GAClB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAmCzE;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACjC;AAED,wBAAsB,eAAe,CAAC,EACpC,IAAI,EACJ,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,WAAW,GACZ,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAoEzC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAC/B,MAAM,EAAE,MAAM,GACb,MAAM,CAcR"}