@loadbare/app 0.4.0

package/dist/build/elements.js

@@ -0,0 +1,158 @@
+/**
+ * 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 { 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) : {};
+    const resolved = new Map();
+    for (const tag of used) {
+        const hits = [];
+        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)
+                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(", "));
+        }
+        if (hits.length === 1) {
+            resolved.set(tag, hits[0][1]);
+            continue;
+        }
+        // No script anywhere. Valid only if a definition gave the tag its
+        // content — otherwise nothing, ever, would upgrade or fill it, and the
+        // 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)`);
+        }
+    }
+    return { resolved };
+}
+/**
+ * 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 function clientEntrySource(resolved, outDir) {
+    const lines = [];
+    for (const tag of [...resolved.keys()].sort()) {
+        const entry = resolved.get(tag);
+        if (entry.kind === "specifier") {
+            lines.push(`import ${JSON.stringify(entry.value)};`);
+        }
+        else {
+            const rel = path.relative(outDir, entry.value).split(path.sep).join("/");
+            lines.push(`import ${JSON.stringify(rel.startsWith(".") ? rel : `./${rel}`)};`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/build/expand.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Expansion — see docs/expansion.md.
+ *
+ * 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
+ * why there is no control flow here: nothing to branch on.
+ *
+ * Substitution is applied to a parsed tree with setAttribute and node values,
+ * never to a string. A value applied through the DOM API cannot be reparsed
+ * as markup, so injection is impossible by construction.
+ */
+export type Definitions = Record<string, string>;
+/**
+ * Load one definition per file, named by the tag it defines.
+ *
+ * Later directories win, so an application can override a built-in widget.
+ */
+export declare function loadDefinitions(dirs: string[]): Promise<Definitions>;
+/**
+ * Overlay definitions read from explicit files, each already keyed by the
+ * tag it defines — for a source, like an application's own `src` tree, that
+ * is discovered file by file rather than listed by directory. A tag here
+ * overrides the same tag in `defs`, the same override `loadDefinitions`
+ * gives a later directory over an earlier one.
+ */
+export declare function addDefinitions(defs: Definitions, files: Map<string, string>): Promise<Definitions>;
+/**
+ * Every hyphenated tag name left in a document, template content included.
+ *
+ * Meant to run on already-expanded output: an `LB-*` tag with a definition
+ * is gone by then, replaced by the tree it stands for, so what remains is
+ * whatever is left for the browser to upgrade itself — a built-in widget
+ * class, an application's own custom element, or one from a package. A
+ * hyphen in the tag name is the one thing a custom element is guaranteed to
+ * have, per the Custom Elements spec, and nothing native has one.
+ */
+export declare function customElementTags(html: string): Set<string>;
+/**
+ * Expand every widget tag in an authored page. Throws rather than shipping.
+ *
+ * Definitions must come from `loadDefinitions`, which is where the graph is
+ * checked for cycles. Handed a cyclic map directly, this recurses forever.
+ */
+export declare function expand(source: string, defs: Definitions): string;
+//# sourceMappingURL=expand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../../build/expand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA0CH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AA8BjD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAmB1E;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACzB,OAAO,CAAC,WAAW,CAAC,CAStB;AA4CD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAS3D;AAkPD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAIhE"}

package/dist/build/expand.js

@@ -0,0 +1,386 @@
+/**
+ * Expansion — see docs/expansion.md.
+ *
+ * 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
+ * why there is no control flow here: nothing to branch on.
+ *
+ * Substitution is applied to a parsed tree with setAttribute and node values,
+ * never to a string. A value applied through the DOM API cannot be reparsed
+ * as markup, so injection is impossible by construction.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { JSDOM } from "jsdom";
+import { ATTR_SLOT, ATTR_TEMPLATE, HUB_TAG_NAME, } from "../core/lb-constants.js";
+/**
+ * The framework's reserved namespace. Every one of these must resolve to a
+ * definition — a typo here is caught immediately rather than shipped as an
+ * inert tag. A tag outside this namespace still expands when a definition
+ * exists for it (an application is free to name its own widgets anything),
+ * but is not required to have one: with no definition, it is assumed to be
+ * a plain custom element, registered by script alone.
+ */
+const WIDGET_TAG = /^LB-/;
+/**
+ * The one LB-* tag that is not a widget: the hub itself, always present in
+ * the chrome, registered by script rather than by definition. Expanding the
+ * chrome (see build/assemble.ts) would otherwise demand a definition for it
+ * that could never exist.
+ */
+const HUB_TAG = HUB_TAG_NAME.toUpperCase();
+/** A placeholder is an entire attribute value or an entire text node. */
+const PLACEHOLDER = /^\{\{([A-Za-z][\w-]*)\}\}$/;
+/**
+ * Marks an attribute as input to expansion. Three namespaces share the tag:
+ * `lb-` is the hub's, `exp-` is expansion's, and everything unprefixed is
+ * HTML's and means what HTML says it means. So an author is free to write
+ * `class`, `title` or `hidden` on any widget, whatever its parameters happen
+ * to be named. The prefix marks the slot on the tag, where the ambiguity was;
+ * inside a definition `{{ }}` already says the same thing, so `exp-label`
+ * fills `{{label}}`.
+ */
+const EXP_PREFIX = "exp-";
+const dom = new JSDOM("");
+const doc = dom.window.document;
+const { Element, HTMLTemplateElement, Node } = dom.window;
+function parse(source) {
+    const holder = doc.createElement("div");
+    holder.innerHTML = source;
+    return holder;
+}
+/**
+ * A tree and the content of every template in it, however deep.
+ *
+ * A template's children are parsed into a fragment rather than into the tree,
+ * so `querySelectorAll` does not reach them. Everything expansion does has to
+ * reach them anyway: a definition may supply its own row template, and
+ * `lb-picker` does, so `{{key}}` written inside one has to be a
+ * placeholder rather than literal text that ships. `walk` already descends
+ * into template content to expand widget tags; this is the same rule stated
+ * once for every pass that reads a tree.
+ */
+function* scopes(root) {
+    yield root;
+    for (const el of root.querySelectorAll("template")) {
+        yield* scopes(el.content);
+    }
+}
+/**
+ * Load one definition per file, named by the tag it defines.
+ *
+ * Later directories win, so an application can override a built-in widget.
+ */
+export async function loadDefinitions(dirs) {
+    const defs = {};
+    for (const dir of dirs) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.endsWith(".html"))
+                continue;
+            const file = `${dir}/${name}`;
+            const source = await readFile(file, "utf-8");
+            checkNames(file, source);
+            defs[name.slice(0, -".html".length).toUpperCase()] = source;
+        }
+    }
+    checkAcyclic(defs);
+    return defs;
+}
+/**
+ * Overlay definitions read from explicit files, each already keyed by the
+ * tag it defines — for a source, like an application's own `src` tree, that
+ * is discovered file by file rather than listed by directory. A tag here
+ * overrides the same tag in `defs`, the same override `loadDefinitions`
+ * gives a later directory over an earlier one.
+ */
+export async function addDefinitions(defs, files) {
+    const merged = { ...defs };
+    for (const [tag, file] of files) {
+        const source = await readFile(file, "utf-8");
+        checkNames(file, source);
+        merged[tag.toUpperCase()] = source;
+    }
+    checkAcyclic(merged);
+    return merged;
+}
+/** Every placeholder a definition declares. */
+function placeholdersOf(source) {
+    const names = [];
+    for (const scope of scopes(parse(source))) {
+        for (const el of scope.querySelectorAll("*")) {
+            for (const attr of el.attributes) {
+                const match = PLACEHOLDER.exec(attr.value.trim());
+                if (match)
+                    names.push(match[1]);
+            }
+        }
+        const walker = doc.createTreeWalker(scope, 4 /* TEXT */);
+        while (walker.nextNode()) {
+            const match = PLACEHOLDER.exec(walker.currentNode.data.trim());
+            if (match)
+                names.push(match[1]);
+        }
+    }
+    return names;
+}
+/**
+ * A placeholder must be spelled the way a tag can supply it.
+ *
+ * HTML lowercases attribute names, so `exp-inputClass` reaches expansion as
+ * `exp-inputclass` and could never fill `{{inputClass}}`. A definition is the
+ * only file that can hold such a name and the only one that can fix it, so it
+ * is rejected here, once, rather than at every page that uses the widget.
+ *
+ * Recognition stays broad on purpose. Narrowing PLACEHOLDER to lowercase would
+ * make `{{inputClass}}` not a placeholder at all, and ship it to the browser as
+ * literal text — the same silent failure somewhere new.
+ */
+function checkNames(file, source) {
+    for (const name of placeholdersOf(source)) {
+        if (!/[A-Z]/.test(name))
+            continue;
+        const kebab = name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+        throw new Error(`expand: ${file} declares {{${name}}}, but HTML lowercases attribute ` +
+            `names, so no tag can supply it. Write {{${kebab}}}.`);
+    }
+}
+/**
+ * Every hyphenated tag name left in a document, template content included.
+ *
+ * Meant to run on already-expanded output: an `LB-*` tag with a definition
+ * is gone by then, replaced by the tree it stands for, so what remains is
+ * whatever is left for the browser to upgrade itself — a built-in widget
+ * class, an application's own custom element, or one from a package. A
+ * hyphen in the tag name is the one thing a custom element is guaranteed to
+ * have, per the Custom Elements spec, and nothing native has one.
+ */
+export function customElementTags(html) {
+    const tags = new Set();
+    for (const scope of scopes(parse(html))) {
+        for (const el of scope.querySelectorAll("*")) {
+            const tag = el.tagName.toLowerCase();
+            if (tag.includes("-"))
+                tags.add(tag);
+        }
+    }
+    return tags;
+}
+/** Which widgets a definition uses. Undefined tags are caught during expansion. */
+function referencesOf(source) {
+    const refs = new Set();
+    for (const scope of scopes(parse(source))) {
+        for (const el of scope.querySelectorAll("*")) {
+            const tag = el.tagName.toUpperCase();
+            if (WIDGET_TAG.test(tag))
+                refs.add(tag);
+        }
+    }
+    return [...refs];
+}
+/**
+ * Expansion is a fixpoint, so it terminates only on an acyclic graph. A depth
+ * cap would hide the bug behind a limit instead of reporting it.
+ */
+function checkAcyclic(defs) {
+    const refs = new Map();
+    for (const [tag, source] of Object.entries(defs)) {
+        refs.set(tag, referencesOf(source));
+    }
+    const done = new Set();
+    const path = [];
+    const visit = (tag) => {
+        if (done.has(tag))
+            return;
+        const cycle = path.indexOf(tag);
+        if (cycle !== -1) {
+            throw new Error(`expand: cycle in the definition graph: ` +
+                [...path.slice(cycle), tag].map((t) => t.toLowerCase()).join(" → "));
+        }
+        path.push(tag);
+        for (const ref of refs.get(tag) ?? [])
+            visit(ref);
+        path.pop();
+        done.add(tag);
+    };
+    for (const tag of refs.keys())
+        visit(tag);
+}
+/**
+ * Resolve a placeholder against what the author wrote. Unset means absent.
+ *
+ * Every name the definition asks for is recorded, whether or not it was
+ * supplied, so expansion can report a parameter the definition never declared.
+ */
+function resolve(text, attrs, asked) {
+    const match = PLACEHOLDER.exec(text.trim());
+    if (!match)
+        return text;
+    const name = match[1];
+    asked.add(name);
+    return attrs.get(name) ?? null;
+}
+function substitute(root, attrs, asked) {
+    for (const scope of scopes(root)) {
+        for (const el of scope.querySelectorAll("*")) {
+            for (const attr of [...el.attributes]) {
+                const value = resolve(attr.value, attrs, asked);
+                // Presence propagates: a placeholder with nothing behind it drops the
+                // attribute rather than emitting it empty, which is what HTML's own
+                // boolean-attribute semantics require.
+                if (value === null)
+                    el.removeAttribute(attr.name);
+                else if (value !== attr.value)
+                    el.setAttribute(attr.name, value);
+            }
+        }
+        const walker = doc.createTreeWalker(scope, 4 /* TEXT */);
+        const texts = [];
+        while (walker.nextNode())
+            texts.push(walker.currentNode);
+        for (const text of texts) {
+            const raw = text.data;
+            if (!PLACEHOLDER.test(raw.trim()))
+                continue;
+            const value = resolve(raw, attrs, asked) ?? "";
+            // Keep the author's surrounding whitespace: "{{label}} <input>" should
+            // still separate the label from the control.
+            const lead = raw.slice(0, raw.length - raw.trimStart().length);
+            const tail = raw.slice(raw.trimEnd().length);
+            text.data = lead + value + tail;
+        }
+    }
+}
+/**
+ * Fill the definition's named destinations from the authored templates that
+ * name them, and hand back the content that is left for the slot.
+ *
+ * A destination is filled with the template's contents, not with the
+ * template, so what ships is ordinary markup in an ordinary place — a real
+ * `<tr>` inside a real `<thead>`, visible in view-source like everything
+ * else. The wrapper existed only to survive the parser and is gone.
+ *
+ * Unlike the slot, there may be several, because the reason for wrapping is
+ * per-destination: a table has a head and a body, and each needs its own
+ * markup past the same obstacle. They are matched by name, and an empty name
+ * is a name, so a widget with one destination costs the author nothing.
+ */
+function fillTemplates(tag, root, content) {
+    const destinations = new Map();
+    for (const el of root.querySelectorAll(`[${ATTR_TEMPLATE}]`)) {
+        const name = el.getAttribute(ATTR_TEMPLATE);
+        if (destinations.has(name)) {
+            throw new Error(`expand: <${tag.toLowerCase()}> declares two ${ATTR_TEMPLATE}="${name}" destinations`);
+        }
+        destinations.set(name, el);
+        el.removeAttribute(ATTR_TEMPLATE);
+    }
+    const rest = [];
+    const filled = new Set();
+    for (const node of content) {
+        const named = node instanceof HTMLTemplateElement && node.hasAttribute(ATTR_TEMPLATE);
+        if (!named) {
+            rest.push(node);
+            continue;
+        }
+        const template = node;
+        const name = template.getAttribute(ATTR_TEMPLATE);
+        const destination = destinations.get(name);
+        if (!destination) {
+            throw new Error(`expand: a <template ${ATTR_TEMPLATE}="${name}"> was written inside ` +
+                `<${tag.toLowerCase()}>, whose definition has no destination by that name.`);
+        }
+        if (filled.has(name)) {
+            throw new Error(`expand: <${tag.toLowerCase()}> was given two templates for '${name}'`);
+        }
+        filled.add(name);
+        destination.append(template.content);
+    }
+    return rest;
+}
+/** Place authored inner content in the single slot, if the definition has one. */
+function fillSlot(tag, root, content) {
+    const slots = root.querySelectorAll(`[${ATTR_SLOT}]`);
+    if (slots.length > 1) {
+        throw new Error(`expand: <${tag.toLowerCase()}> declares more than one ${ATTR_SLOT}`);
+    }
+    if (slots.length === 0) {
+        // Whitespace is not content. An author who writes only named templates
+        // still leaves the newlines between them, and those are the file's
+        // formatting rather than something anybody meant to place.
+        const wrote = content.some((node) => node.nodeType !== Node.TEXT_NODE || node.data.trim());
+        if (wrote) {
+            throw new Error(`expand: content was written inside <${tag.toLowerCase()}>, whose definition has no ${ATTR_SLOT}`);
+        }
+        return;
+    }
+    const slot = slots[0];
+    // The authored nodes move rather than copy. The caller replaces the tag's
+    // children with the expanded tree immediately after, so there is nothing
+    // left behind for a clone to protect.
+    slot.append(...content);
+    slot.removeAttribute(ATTR_SLOT);
+}
+function expandElement(el, defs) {
+    const tag = el.tagName.toUpperCase();
+    const source = defs[tag];
+    if (source === undefined) {
+        throw new Error(`expand: <${tag.toLowerCase()}> has no definition. Every hub tag must resolve.`);
+    }
+    // The tag survives expansion carrying every attribute the author wrote,
+    // `exp-` ones included. They cost nothing where they are, and what ships
+    // shows what was asked for beside what it produced.
+    const attrs = new Map();
+    for (const attr of el.attributes) {
+        if (!attr.name.startsWith(EXP_PREFIX))
+            continue;
+        attrs.set(attr.name.slice(EXP_PREFIX.length), attr.value);
+    }
+    const tree = parse(source);
+    const asked = new Set();
+    substitute(tree, attrs, asked);
+    // A parameter the definition never declared is a name that resolves to
+    // nothing. Unprefixed attributes could not support this check, because a
+    // stray one is indistinguishable from a deliberate HTML attribute.
+    for (const name of attrs.keys()) {
+        if (asked.has(name))
+            continue;
+        throw new Error(`expand: <${tag.toLowerCase()}> was given ${EXP_PREFIX}${name}, ` +
+            `but its definition has no {{${name}}}.`);
+    }
+    // Named destinations first: what they take is addressed to them, and only
+    // what is left is the slot's.
+    fillSlot(tag, tree, fillTemplates(tag, tree, [...el.childNodes]));
+    el.replaceChildren(...tree.childNodes);
+}
+function walk(root, defs) {
+    for (const child of [...root.children]) {
+        const tag = child.tagName.toUpperCase();
+        if (tag in defs || (WIDGET_TAG.test(tag) && tag !== HUB_TAG)) {
+            expandElement(child, defs);
+        }
+        // Definitions may use other widgets, so descend after expanding. The
+        // acyclicity check is what makes this terminate.
+        walk(child, defs);
+        // Template content is markup in a file like any other, and it is inert,
+        // so a row template ships already expanded.
+        if (child instanceof HTMLTemplateElement)
+            walk(child.content, defs);
+    }
+}
+/**
+ * Expand every widget tag in an authored page. Throws rather than shipping.
+ *
+ * Definitions must come from `loadDefinitions`, which is where the graph is
+ * checked for cycles. Handed a cyclic map directly, this recurses forever.
+ */
+export function expand(source, defs) {
+    const tree = parse(source);
+    walk(tree, defs);
+    return tree.innerHTML;
+}

package/dist/build/format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pretty-printing the assembled document — cosmetic, and deliberately so.
+ *
+ * Loadbare App ships the DOM the browser holds, so view-source is a real view of the
+ * application. That only pays if it is legible. Expansion produces correct
+ * markup but inherits its whitespace from the definition files, so the
+ * assembled document reads like a concatenation, which is what it is.
+ *
+ * Prettier is a nice-to-have here and is treated as one. It runs on the whole
+ * document once, after everything is assembled, and every way it can fail —
+ * throwing, or not being installed — leaves the unformatted string in place.
+ *
+ * Ignoring the throw is the point rather than an oversight. The correct output
+ * is what `expand` already returned; formatting only makes it pleasant. If a
+ * failure could fail the build, we would end up writing checks upstream whose
+ * only purpose was to keep the formatter happy, and an error message about
+ * markup the author never wrote is worse than an ugly line. So: nothing in this
+ * codebase exists to keep prettier from throwing. It either helps or it doesn't.
+ *
+ * The one failure that would retire this outright is whitespace. Whitespace is
+ * semantic in inline contexts — `<label>Name <input></label>` needs that space —
+ * and prettier has no display information for `lb-*` elements. If formatting
+ * is ever observed to change what renders, delete this file. A prettier page
+ * that shows the wrong thing is not a trade worth making.
+ */
+/** Format if we can, and return the input unchanged if we cannot. */
+export declare function formatHtml(source: string): Promise<string>;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../build/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,qEAAqE;AACrE,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBhE"}

package/dist/build/format.js

@@ -0,0 +1,42 @@
+/**
+ * Pretty-printing the assembled document — cosmetic, and deliberately so.
+ *
+ * Loadbare App ships the DOM the browser holds, so view-source is a real view of the
+ * application. That only pays if it is legible. Expansion produces correct
+ * markup but inherits its whitespace from the definition files, so the
+ * assembled document reads like a concatenation, which is what it is.
+ *
+ * Prettier is a nice-to-have here and is treated as one. It runs on the whole
+ * document once, after everything is assembled, and every way it can fail —
+ * throwing, or not being installed — leaves the unformatted string in place.
+ *
+ * Ignoring the throw is the point rather than an oversight. The correct output
+ * is what `expand` already returned; formatting only makes it pleasant. If a
+ * failure could fail the build, we would end up writing checks upstream whose
+ * only purpose was to keep the formatter happy, and an error message about
+ * markup the author never wrote is worse than an ugly line. So: nothing in this
+ * codebase exists to keep prettier from throwing. It either helps or it doesn't.
+ *
+ * The one failure that would retire this outright is whitespace. Whitespace is
+ * semantic in inline contexts — `<label>Name <input></label>` needs that space —
+ * and prettier has no display information for `lb-*` elements. If formatting
+ * is ever observed to change what renders, delete this file. A prettier page
+ * that shows the wrong thing is not a trade worth making.
+ */
+/** Format if we can, and return the input unchanged if we cannot. */
+export async function formatHtml(source) {
+    try {
+        const prettier = await import("prettier");
+        return await prettier.format(source, {
+            parser: "html",
+            // The default. Prettier respects each element's CSS display default when
+            // deciding where whitespace may move, and treats elements it does not
+            // know — every hub widget — as inline, which is the conservative side.
+            htmlWhitespaceSensitivity: "css",
+        });
+    }
+    catch (err) {
+        console.warn(`loadbare: shipping unformatted markup, prettier declined: ${err}`);
+        return source;
+    }
+}