@loadbare/app 0.4.0 → 0.5.0

package/dist/build/elements.js

@@ -3,127 +3,41 @@
  * 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 script registers the class that upgrades it.
+ *   - a definition (an `.html` file) 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 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.
+ * Both halves are looked for in the same ordered origins, and the later
+ * origin wins: an application's own script overrides one from a package it
+ * imported, which overrides a built-in. Two files claiming one tag *within*
+ * one origin is the error case, and build/origins.ts raises it while
+ * scanning. Nothing is scanned here.
  */
-import { readdir } from "node:fs/promises";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { CUSTOM_ELEMENT_TAG } from "./locations.js";
-/** This package's own built-in sources are still a directory scan — that layout is fixed and internal, not discovered from an application's tree. */
-async function scanBuiltinDir(dir) {
-    const found = new Map();
-    let names;
-    try {
-        names = await readdir(dir);
-    }
-    catch {
-        return found;
-    }
-    const entry = (tag) => {
-        let w = found.get(tag);
-        if (!w) {
-            w = {};
-            found.set(tag, w);
-        }
-        return w;
-    };
-    for (const name of names) {
-        if (name.endsWith(".ts")) {
-            entry(name.slice(0, -".ts".length).toLowerCase()).script = path.join(dir, name);
-        }
-        else if (name.endsWith(".html")) {
-            entry(name.slice(0, -".html".length).toLowerCase()).html = path.join(dir, name);
-        }
-    }
-    return found;
-}
-/**
- * `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 async function loadElementManifest(file) {
-    let mod;
-    try {
-        // pathToFileURL requires an absolute path; the caller's may not be one.
-        mod = (await import(pathToFileURL(path.resolve(file)).href));
-    }
-    catch (err) {
-        if (err.code === "ERR_MODULE_NOT_FOUND")
-            return {};
-        throw new Error(`elements: '${file}' failed to load: ${err.message}`);
-    }
-    const manifest = (mod.default ?? {});
-    for (const [tag, spec] of Object.entries(manifest)) {
-        if (!CUSTOM_ELEMENT_TAG.test(tag)) {
-            throw new Error(`elements.ts: '${tag}' is not a valid custom element name`);
-        }
-        if (typeof spec !== "string") {
-            throw new Error(`elements.ts: '${tag}' must map to an import specifier string, got ${typeof spec}`);
-        }
-    }
-    return manifest;
-}
-export async function resolveElements({ used, widgets, elementsFile, builtinWidgetsDir, builtinHubDir, packageName, }) {
-    // lb-hub is found here the same way as any other built-in: hub/ is just a
-    // second built-in source, named specifiers differently because it is the
-    // package's main entry point rather than a widgets/ subpath.
-    const builtinSources = [
-        {
-            dir: builtinWidgetsDir,
-            specifier: (tag) => `${packageName}/widgets/${tag}`,
-        },
-        { dir: builtinHubDir, specifier: () => packageName },
-    ];
-    const builtinDirs = await Promise.all(builtinSources.map((source) => scanBuiltinDir(source.dir)));
-    const manifest = elementsFile ? await loadElementManifest(elementsFile) : {};
+export { loadElementManifest } from "./origins.js";
+export function resolveElements({ used, scans, }) {
     const resolved = new Map();
     for (const tag of used) {
-        const hits = [];
+        let script;
         let hasDefinition = false;
-        builtinSources.forEach((source, i) => {
-            const entry = builtinDirs[i].get(tag);
-            if (entry?.script) {
-                hits.push([
-                    source.dir,
-                    { kind: "specifier", value: source.specifier(tag) },
-                ]);
-            }
-            if (entry?.html)
+        // In order, so the last origin holding a script is the one that wins.
+        for (const scan of scans) {
+            if (scan.definitions.has(tag))
                 hasDefinition = true;
-        });
-        const local = widgets.get(tag);
-        if (local?.script) {
-            hits.push(["src", { kind: "file", value: local.script }]);
-        }
-        if (local?.html)
-            hasDefinition = true;
-        if (tag in manifest) {
-            hits.push([elementsFile, { kind: "specifier", value: manifest[tag] }]);
-        }
-        if (hits.length > 1) {
-            throw new Error(`build: <${tag}> is declared in more than one place: ` +
-                hits.map(([where]) => where).join(", "));
+            const found = scan.scripts.get(tag);
+            if (found === undefined)
+                continue;
+            script = scan.specifier
+                ? { kind: "specifier", value: scan.specifier(tag) }
+                : { kind: "file", value: found };
         }
-        if (hits.length === 1) {
-            resolved.set(tag, hits[0][1]);
+        if (script) {
+            resolved.set(tag, script);
             continue;
         }
         // No script anywhere. Valid only if a definition gave the tag its
@@ -131,7 +45,7 @@ export async function resolveElements({ used, widgets, elementsFile, builtinWidg
         // tag would do nothing were it to reach the browser.
         if (!hasDefinition) {
             throw new Error(`build: <${tag}> has neither a script nor a definition, so it would ` +
-                `do nothing (checked built-in widgets, the src tree, and elements.ts)`);
+                `do nothing (checked ${scans.map((s) => `'${s.name}'`).join(", ")})`);
         }
     }
     return { resolved };

package/dist/build/expand.d.ts

@@ -1,5 +1,5 @@
 /**
- * Expansion — see docs/expansion.md.
+ * Expansion — see docs/reference/custom-elements.md, "HTML".
  *
  * A page author writes one tag and gets the tree it stands for. Expansion
  * runs at build time, before any request exists, so it has no data. That is

package/dist/build/expand.js

@@ -1,5 +1,5 @@
 /**
- * Expansion — see docs/expansion.md.
+ * Expansion — see docs/reference/custom-elements.md, "HTML".
  *
  * A page author writes one tag and gets the tree it stands for. Expansion
  * runs at build time, before any request exists, so it has no data. That is

package/dist/build/locations.d.ts

@@ -1,16 +1,12 @@
 /**
- * Finding every file a build needs by what it's named, not by which
- * directory it happens to sit in.
+ * Finding the application's own files by what they're named, not by which
+ * directory they happen to sit in.
  *
  * A page and a widget definition can be byte-for-byte identical markup —
  * the only thing that says which one a file is, is extrinsic to its
  * content. `pages/` vs. `widgets/` used to carry that meaning; here a
- * filename suffix does instead: `*.chrome.html` is the one chrome file,
- * `*.page.html` is a page, and anything else `.html` is a widget
- * definition. A `.ts` file shaped like a custom element tag is a widget
- * script, found the same way regardless of where it lives. Both halves of
- * one widget — its markup and its class — are free to sit side by side or
- * apart; nothing here requires a `widgets/` directory to exist at all.
+ * filename suffix does instead: `chrome.html` is the one chrome file, and
+ * `*.page.html` is a page.
  *
  * A page's server half is named the same way: `*.hooks.ts` and
  * `*.queries.ts` pair with a `*.page.html` by sharing its basename, and are
@@ -18,12 +14,10 @@
  * neither — but one with no matching `*.page.html` is a naming mistake and
  * is rejected below.
  *
- * A `.css` file is not paired with anything — it is not a widget's, a
- * page's, or the chrome's, because build/styles.ts does not distinguish
- * them. Every `.css` file anywhere under `src` is concatenated, in an order
- * controlled entirely by the author: sorted by filename first, so a global
- * stylesheet sorts to the front by naming itself `00-reset.css` or similar,
- * regardless of which directory it lives in.
+ * Widget definitions, widget scripts and stylesheets are not found here.
+ * They arrive from more than one origin — this package's own widgets, an
+ * imported package, or `src` — and all three are scanned the same way by
+ * build/origins.ts. `src` is simply the last origin in that cascade.
  *
  * `--src` names the one tree scanned this way; `--out` names where the
  * build lands. Those, plus this package's own root (for its built-in
@@ -31,18 +25,12 @@
  * other module takes the result as a plain parameter and never
  * reconstructs one of its own.
  */
-/** Lowercase, hyphenated — the one shape every custom element tag has, and the one native elements never do. */
-export declare const CUSTOM_ELEMENT_TAG: RegExp;
+import type { BuiltinDirs } from "./origins.js";
+export { CUSTOM_ELEMENT_TAG } from "./origins.js";
 export interface PageFile {
     name: string;
     file: string;
 }
-export interface WidgetSource {
-    /** Absolute path to the `.html` definition, if this tag has one. */
-    html?: string;
-    /** Absolute path, without extension, to the `.ts` script, if this tag has one. */
-    script?: string;
-}
 export interface PageSource {
     /** Absolute path, without extension, to the `.hooks.ts` module, if this page has one. */
     hooks?: string;
@@ -53,20 +41,11 @@ interface Discovered {
     chromeCandidates: string[];
     pages: PageFile[];
     pageSources: Map<string, PageSource>;
-    widgets: Map<string, WidgetSource>;
-    elementsCandidates: string[];
-    cssFiles: string[];
+    importsCandidates: string[];
 }
 /** The raw walk, with no uniqueness checks — usable on its own by anything that does not need a chrome file. */
 export declare function discoverSrc(src: string): Promise<Discovered>;
-export interface PackageInfo {
-    /** This package's own widgets/ — the built-in widget definitions and classes. */
-    builtinWidgetsDir: string;
-    /** This package's own hub/ — where lb-hub's script lives, found the same way as any built-in widget. */
-    builtinHubDir: string;
-    /** This package's own name, e.g. "@loadbare/app" — for naming a built-in's import specifier. */
-    packageName: string;
-}
+export type PackageInfo = BuiltinDirs;
 export declare function packageInfo(): Promise<PackageInfo>;
 export interface LocationArgs {
     /** The application's source tree, e.g. "src". Scanned as a whole — see this file's header. */
@@ -74,14 +53,12 @@ export interface LocationArgs {
     out: string;
 }
 export interface Locations extends PackageInfo {
+    srcDir: string;
     chromeFile: string;
     pages: PageFile[];
     pageSources: Map<string, PageSource>;
-    widgets: Map<string, WidgetSource>;
-    elementsFile?: string;
-    cssFiles: string[];
+    importsFile?: string;
     outDir: string;
 }
 export declare function resolveLocations(args: LocationArgs): Promise<Locations>;
-export {};
 //# sourceMappingURL=locations.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"locations.d.ts","sourceRoot":"","sources":["../../build/locations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAQH,gHAAgH;AAChH,eAAO,MAAM,kBAAkB,QAAkC,CAAC;AASlE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,gHAAgH;AAChH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA+ElE;AAED,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wGAAwG;IACxG,aAAa,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAiBxD;AAED,MAAM,WAAW,YAAY;IAC3B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAoD7E"}
+{"version":3,"file":"locations.d.ts","sourceRoot":"","sources":["../../build/locations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAQlD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,gHAAgH;AAChH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA6ClE;AAED,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC;AAEtC,wBAAsB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAgBxD;AAED,MAAM,WAAW,YAAY;IAC3B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CA6C7E"}

package/dist/build/locations.js

@@ -1,16 +1,12 @@
 /**
- * Finding every file a build needs by what it's named, not by which
- * directory it happens to sit in.
+ * Finding the application's own files by what they're named, not by which
+ * directory they happen to sit in.
  *
  * A page and a widget definition can be byte-for-byte identical markup —
  * the only thing that says which one a file is, is extrinsic to its
  * content. `pages/` vs. `widgets/` used to carry that meaning; here a
- * filename suffix does instead: `*.chrome.html` is the one chrome file,
- * `*.page.html` is a page, and anything else `.html` is a widget
- * definition. A `.ts` file shaped like a custom element tag is a widget
- * script, found the same way regardless of where it lives. Both halves of
- * one widget — its markup and its class — are free to sit side by side or
- * apart; nothing here requires a `widgets/` directory to exist at all.
+ * filename suffix does instead: `chrome.html` is the one chrome file, and
+ * `*.page.html` is a page.
  *
  * A page's server half is named the same way: `*.hooks.ts` and
  * `*.queries.ts` pair with a `*.page.html` by sharing its basename, and are
@@ -18,12 +14,10 @@
  * neither — but one with no matching `*.page.html` is a naming mistake and
  * is rejected below.
  *
- * A `.css` file is not paired with anything — it is not a widget's, a
- * page's, or the chrome's, because build/styles.ts does not distinguish
- * them. Every `.css` file anywhere under `src` is concatenated, in an order
- * controlled entirely by the author: sorted by filename first, so a global
- * stylesheet sorts to the front by naming itself `00-reset.css` or similar,
- * regardless of which directory it lives in.
+ * Widget definitions, widget scripts and stylesheets are not found here.
+ * They arrive from more than one origin — this package's own widgets, an
+ * imported package, or `src` — and all three are scanned the same way by
+ * build/origins.ts. `src` is simply the last origin in that cascade.
  *
  * `--src` names the one tree scanned this way; `--out` names where the
  * build lands. Those, plus this package's own root (for its built-in
@@ -35,22 +29,18 @@ import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { findPackageRoot } from "./package-root.js";
-/** Lowercase, hyphenated — the one shape every custom element tag has, and the one native elements never do. */
-export const CUSTOM_ELEMENT_TAG = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
-const CHROME_SUFFIX = ".chrome.html";
+export { CUSTOM_ELEMENT_TAG } from "./origins.js";
+const CHROME_FILENAME = "chrome.html";
 const PAGE_SUFFIX = ".page.html";
 const HOOKS_SUFFIX = ".hooks.ts";
 const QUERIES_SUFFIX = ".queries.ts";
-const CSS_SUFFIX = ".css";
-const ELEMENTS_FILENAME = "elements.ts";
+const IMPORTS_FILENAME = "imports.ts";
 /** The raw walk, with no uniqueness checks — usable on its own by anything that does not need a chrome file. */
 export async function discoverSrc(src) {
     const chromeCandidates = [];
     const pages = [];
     const pageSources = new Map();
-    const widgets = new Map();
-    const elementsCandidates = [];
-    const cssFiles = [];
+    const importsCandidates = [];
     let entries;
     try {
         entries = await readdir(src, { withFileTypes: true, recursive: true });
@@ -58,14 +48,6 @@ export async function discoverSrc(src) {
     catch {
         entries = [];
     }
-    const widget = (tag) => {
-        let w = widgets.get(tag);
-        if (!w) {
-            w = {};
-            widgets.set(tag, w);
-        }
-        return w;
-    };
     const pageSource = (name) => {
         let p = pageSources.get(name);
         if (!p) {
@@ -78,10 +60,10 @@ export async function discoverSrc(src) {
         if (!entry.isFile())
             continue;
         const file = path.join(entry.parentPath, entry.name);
-        if (entry.name === ELEMENTS_FILENAME) {
-            elementsCandidates.push(file);
+        if (entry.name === IMPORTS_FILENAME) {
+            importsCandidates.push(file);
         }
-        else if (entry.name.endsWith(CHROME_SUFFIX)) {
+        else if (entry.name === CHROME_FILENAME) {
             chromeCandidates.push(file);
         }
         else if (entry.name.endsWith(PAGE_SUFFIX)) {
@@ -94,32 +76,9 @@ export async function discoverSrc(src) {
             pageSource(entry.name.slice(0, -QUERIES_SUFFIX.length)).queries =
                 file.slice(0, -".ts".length);
         }
-        else if (entry.name.endsWith(CSS_SUFFIX)) {
-            cssFiles.push(file);
-        }
-        else if (entry.name.endsWith(".html")) {
-            widget(entry.name.slice(0, -".html".length).toLowerCase()).html = file;
-        }
-        else if (entry.name.endsWith(".ts")) {
-            const tag = entry.name.slice(0, -".ts".length).toLowerCase();
-            // Without the extension: this becomes an import specifier, and esbuild
-            // resolves ".ts" from the bare path the same way it resolves ".js".
-            if (CUSTOM_ELEMENT_TAG.test(tag))
-                widget(tag).script = file.slice(0, -".ts".length);
-        }
     }
     pages.sort((a, b) => a.name.localeCompare(b.name));
-    // By filename first, full path only to break a tie — see this file's
-    // header. A directory a file happens to sit in never affects the order.
-    cssFiles.sort((a, b) => path.basename(a).localeCompare(path.basename(b)) || a.localeCompare(b));
-    return {
-        chromeCandidates,
-        pages,
-        pageSources,
-        widgets,
-        elementsCandidates,
-        cssFiles,
-    };
+    return { chromeCandidates, pages, pageSources, importsCandidates };
 }
 export async function packageInfo() {
     const root = await findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
@@ -131,7 +90,6 @@ export async function packageInfo() {
         throw new Error(`locations: could not read '${root}/package.json': ${err.message}`);
     }
     return {
-        builtinWidgetsDir: path.join(root, "widgets"),
         builtinHubDir: path.join(root, "hub"),
         packageName: pkg.name,
     };
@@ -141,17 +99,17 @@ export async function resolveLocations(args) {
         packageInfo(),
         discoverSrc(args.src),
     ]);
-    const { chromeCandidates, elementsCandidates, pages, pageSources, widgets, cssFiles, } = discovered;
+    const { chromeCandidates, importsCandidates, pages, pageSources } = discovered;
     if (chromeCandidates.length === 0) {
-        throw new Error(`locations: no *${CHROME_SUFFIX} file found under '${args.src}'`);
+        throw new Error(`locations: no ${CHROME_FILENAME} file found under '${args.src}'`);
     }
     if (chromeCandidates.length > 1) {
-        throw new Error(`locations: more than one *${CHROME_SUFFIX} file found under '${args.src}': ` +
+        throw new Error(`locations: more than one ${CHROME_FILENAME} file found under '${args.src}': ` +
             chromeCandidates.join(", "));
     }
-    if (elementsCandidates.length > 1) {
-        throw new Error(`locations: more than one ${ELEMENTS_FILENAME} found under '${args.src}': ` +
-            elementsCandidates.join(", "));
+    if (importsCandidates.length > 1) {
+        throw new Error(`locations: more than one ${IMPORTS_FILENAME} found under '${args.src}': ` +
+            importsCandidates.join(", "));
     }
     const pageNames = new Set(pages.map((p) => p.name));
     for (const name of pageSources.keys()) {
@@ -162,12 +120,11 @@ export async function resolveLocations(args) {
     }
     return {
         ...info,
+        srcDir: args.src,
         chromeFile: chromeCandidates[0],
         pages,
         pageSources,
-        widgets,
-        elementsFile: elementsCandidates[0],
-        cssFiles,
+        ...(importsCandidates[0] ? { importsFile: importsCandidates[0] } : {}),
         outDir: args.out,
     };
 }

package/dist/build/origins.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Where a build's files come from — see docs/reference/builder.md.
+ *
+ * Three kinds of file reach the assembled application: a `.html` definition
+ * that expands a tag, a `.ts` script that registers its class, and a `.css`
+ * stylesheet. All three arrive from the same places, so all three are found
+ * the same way: one ordered list of origins, scanned once each, read by
+ * whoever needs them.
+ *
+ * The order is the cascade, and it is the same for every file kind:
+ *
+ *   1. this package's own `hub/`
+ *   2. each package declared in `imports.ts`, in first-mention order
+ *   3. the application's own `--src` tree
+ *
+ * A package contributes one directory of its own choosing — `loadbare.widgets`
+ * in its package.json, or the whole package when it says nothing.  See
+ * `widgetDir` below for why a package gets to answer that.
+ *
+ * The one built-in origin holds one tag, `lb-hub`, and it is there because
+ * every application has a hub whether or not it says so. A widget is not in
+ * that position: `@loadbare/widgets` is a declared package like any other,
+ * and the builder cannot tell it from someone else's.
+ *
+ * Two rules fall out of that list, and there is no third:
+ *
+ *   - Within one origin, two files claiming the same tag are an error. That
+ *     is a typo, and the origin's own author is the one who can fix it.
+ *   - Across origins, the later one wins. An application always has the
+ *     final say over a package it imported, and a package over a built-in,
+ *     without anyone having to out-name a dependency they do not control.
+ */
+/** Lowercase, hyphenated — the one shape every custom element tag has, and the one native elements never do. */
+export declare const CUSTOM_ELEMENT_TAG: RegExp;
+export interface Origin {
+    /** How this origin is named in an error message: a package name, or "src". */
+    name: string;
+    /** The roots to scan. */
+    dirs: string[];
+    /**
+     * How a script from here is imported, when a bare specifier is wanted
+     * instead of the scanned file's own path. Only this package's `hub/` uses
+     * it: `lb-hub` is the package's main entry point rather than a file an
+     * application should reach into.
+     */
+    specifier?: (tag: string) => string;
+}
+export interface OriginScan {
+    name: string;
+    specifier?: (tag: string) => string;
+    /** Tag to its `.html` definition. */
+    definitions: Map<string, string>;
+    /** Tag to its `.ts` script, extension stripped. */
+    scripts: Map<string, string>;
+    /** Every `.css` file here, sorted by filename with the full path breaking a tie. */
+    css: string[];
+}
+/**
+ * One origin's contribution, classified by filename alone.
+ *
+ * A `.html` or `.ts` file is a widget's only when its basename is a tag —
+ * which is what excludes `chrome.html`, `about.page.html`, `about.hooks.ts`
+ * and `imports.ts` here without naming any of them. Those are the
+ * application's own files, and build/locations.ts picks them out of `src`
+ * separately.
+ */
+export declare function scanOrigin(origin: Origin): Promise<OriginScan>;
+/** The shape of an `imports.ts` module's default export: the packages an application pulls widgets from. */
+export type ElementManifest = string[];
+/**
+ * `imports.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. It lists the packages an application pulls
+ * widgets from, and each one becomes an origin, scanned exactly as `src` is.
+ */
+export declare function loadElementManifest(file: string): Promise<ElementManifest>;
+/**
+ * The ordinary node_modules walk, stopping at the first directory that has
+ * the package installed — not a full resolution of an entry file, on
+ * purpose: this only needs the package's root directory, and stopping short
+ * avoids caring whether the package exposes an "exports" map at all.  Which
+ * part of that root holds the widgets is the package's own answer to give —
+ * `widgetDir` asks it.
+ */
+export declare function findInstalledPackage(packageName: string, fromDir: string): Promise<string>;
+export interface BuiltinDirs {
+    /** This package's own hub/ — where lb-hub's script lives, found the same way as any widget. */
+    builtinHubDir: string;
+    /** This package's own name, e.g. "@loadbare/app" — for naming the built-in's import specifier. */
+    packageName: string;
+}
+/**
+ * The cascade, in order. A declared package is an origin like any other: the
+ * directory it points `loadbare.widgets` at is scanned the way `src` is — its
+ * whole installed directory, when it points at nothing — and a widget there is
+ * found by its filename, not by being named in a manifest.
+ *
+ * `hub/` is the only origin naming a specifier, because `lb-hub` is the
+ * package's main entry point rather than a file to reach into.
+ */
+export declare function buildOrigins(builtin: BuiltinDirs, declared: ElementManifest, src: string): Promise<Origin[]>;
+/**
+ * The whole cascade, scanned. Everything a build reads from disk that is not
+ * a page, the chrome, or a page's server half comes back from here.
+ */
+export declare function scanAll(builtin: BuiltinDirs, src: string, importsFile?: string): Promise<OriginScan[]>;
+/** Every origin's stylesheets, concatenated in cascade order. */
+export declare function cssFrom(scans: OriginScan[]): string[];
+//# sourceMappingURL=origins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"origins.d.ts","sourceRoot":"","sources":["../../build/origins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAOH,gHAAgH;AAChH,eAAO,MAAM,kBAAkB,QAAkC,CAAC;AAMlE,MAAM,WAAW,MAAM;IACrB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,qCAAqC;IACrC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mDAAmD;IACnD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,oFAAoF;IACpF,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAsBD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA4DpE;AAED,4GAA4G;AAC5G,MAAM,MAAM,eAAe,GAAG,MAAM,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAwED,MAAM,WAAW,WAAW;IAC1B,+FAA+F;IAC/F,aAAa,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBnB;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,UAAU,EAAE,CAAC,CAIvB;AAED,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,CAErD"}