@dharta/cli 0.6.77 → 0.6.78

package/dist/genui.js

@@ -0,0 +1,1130 @@
+// RFC 0056 generative UI: the CLI-side mirror of the data plane's `[genui]`
+// contract, plus the compiler that turns a source folder into the bundle the
+// data plane serves.
+//
+// SOURCE OF TRUTH: apps/dharta-python/src/dharta/genui/manifest.py (the
+// `[genui]` table) and apps/dharta-python/src/dharta/genui/bundle.py (the
+// `dharta.genui-bundle.v1` file). Those two files decide what a release is
+// allowed to carry; everything here is a local mirror whose only job is to fail
+// on the developer's machine instead of at deploy. Change either Python file and
+// this one has to move with it. test/genui-crossplane.test.ts reads both files
+// out of the monorepo and pins every constant below against them. The widget
+// re-validates the same shape a third time in
+// sdks/widget/src/transport/managedAgents.ts (`coerceGenuiCatalog`).
+//
+// The mirror is hand-written rather than generated from a @dharta/contracts
+// schema because that package's established pattern is a language-neutral JSON
+// file pinned by conformance tests on BOTH sides (see its README). The Python
+// side of that pin lives in apps/dharta-python, so a half-pinned schema would
+// claim a guarantee it does not have - and the CLI would gain a runtime
+// dependency it does not otherwise need.
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import TOML from "@iarna/toml";
+import { setGenuiBundleSha256, tableScalarLiteral } from "./manifest.js";
+// --- The contract, mirrored -------------------------------------------------
+export const BUNDLE_FORMAT = "dharta.genui-bundle.v1";
+export const MAX_BUNDLE_BYTES = 5 * 1024 * 1024;
+export const MAX_COMPONENTS = 128;
+export const MAX_WORKER_BYTES = 500 * 1024;
+export const MAX_HTML_BYTES = 1024 * 1024;
+export const MAX_EVENTS = 64;
+export const MAX_EVENT_NAME_LENGTH = 128;
+export const EVENT_CADENCES = ["agent_action", "reference", "side_effect"];
+// Must equal bundle.py's TIER1_BUILTINS exactly: a Tier-1 component is only an
+// alias for one of Dharta's own host-rendered primitives.
+export const TIER1_BUILTINS = [
+    "Badge",
+    "Button",
+    "Card",
+    "Checkbox",
+    "Column",
+    "Divider",
+    "Heading",
+    "Row",
+    "Select",
+    "Text",
+    "TextField",
+];
+// manifest.py's _IDENTIFIER, for both catalog_id and component names.
+export const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.:/@-]{0,127}$/;
+// Where `dharta genui build` looks for component sources when
+// `[genui.build] source` is unset. One directory per component, named exactly
+// as the component.
+export const DEFAULT_SOURCE_DIR = "genui/components";
+export const COMPONENT_SPEC_FILE = "component.json";
+export const TIER2_SOURCE_FILE = "worker.js";
+export const TIER3_SOURCE_FILE = "index.html";
+// The data plane's own wording for the two path rejections in
+// bundle.py::_read_regular_file. `checkGenui` reports them verbatim, because a
+// pre-flight refusal should read exactly like the release rejection it
+// predicts; the build appends the offending path, because there the developer
+// is being told which link to remove.
+const CROSSES_SYMLINK = "[genui] bundle path crosses a non-directory or symlink";
+const NOT_A_REGULAR_FILE = "[genui] bundle must be a regular file";
+/** A `[genui]` section, or a bundle, that the data plane would reject. */
+export class GenuiError extends Error {
+}
+function plainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse the `[genui]` table out of a loaded `dharta.toml`. Returns null when
+ * there is no section (generative UI is opt-in); throws `GenuiError` on a
+ * section the data plane would reject.
+ */
+export function parseGenuiSection(manifest, options = {}) {
+    const requireDigest = options.requireDigest !== false;
+    const raw = manifest.genui;
+    if (raw === undefined)
+        return null;
+    if (!plainObject(raw))
+        throw new GenuiError("[genui] must be a table");
+    const catalogId = raw.catalog_id;
+    if (typeof catalogId !== "string" || !IDENTIFIER.test(catalogId.trim())) {
+        throw new GenuiError("[genui] requires a non-empty string catalog_id");
+    }
+    const rawBundle = raw.bundle;
+    if (rawBundle !== undefined && (typeof rawBundle !== "string" || !rawBundle.trim())) {
+        throw new GenuiError("[genui] bundle must be a non-empty string path when set");
+    }
+    const bundle = typeof rawBundle === "string" ? rawBundle.trim() : null;
+    if (options.text !== undefined)
+        rejectFloatVersion(options.text);
+    const version = raw.version === undefined ? 1 : raw.version;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        throw new GenuiError("[genui] version must be a positive integer");
+    }
+    const digest = raw.bundle_sha256;
+    const digestValid = typeof digest === "string" && /^[0-9a-f]{64}$/.test(digest);
+    if (bundle !== null) {
+        if (requireDigest && !digestValid) {
+            throw new GenuiError("[genui] bundle_sha256 must be a lowercase 64-character SHA-256 digest");
+        }
+    }
+    else if (digest !== undefined) {
+        throw new GenuiError("[genui] bundle_sha256 requires bundle");
+    }
+    const enabled = raw.enabled === undefined ? true : raw.enabled;
+    if (typeof enabled !== "boolean")
+        throw new GenuiError("[genui] enabled must be a boolean");
+    return {
+        catalogId: catalogId.trim(),
+        version,
+        bundle,
+        bundleSha256: digestValid ? digest : null,
+        components: parseComponents(raw.components === undefined ? [] : raw.components, bundle !== null),
+        enabled,
+        source: parseBuildTable(raw.build),
+    };
+}
+// `[genui.build]` is a CLI-only sub-table: `dharta genui build` reads it, the
+// release contract never does. Safe because manifest.py's parse_genui reads
+// only its own known keys off the section mapping (catalog_id, bundle, version,
+// bundle_sha256, enabled, components) and nothing in releases.py rejects
+// unrecognized keys, so an extra sub-table is simply ignored at deploy. Keeping
+// it out of `[genui]` itself means a CLI-only key can never collide with a key
+// the data plane later adds there.
+function parseBuildTable(raw) {
+    if (raw === undefined)
+        return DEFAULT_SOURCE_DIR;
+    if (!plainObject(raw))
+        throw new GenuiError("[genui.build] must be a table");
+    const source = raw.source;
+    if (source === undefined)
+        return DEFAULT_SOURCE_DIR;
+    if (typeof source !== "string" || !source.trim()) {
+        throw new GenuiError("[genui.build] source must be a non-empty string path when set");
+    }
+    return source.trim();
+}
+// `@iarna/toml` returns a JavaScript number for both `version = 1` and
+// `version = 1.0`, so by the time the value reaches us the two are identical.
+// Python's tomllib keeps them apart: `1.0` is a float, and manifest.py's
+// `isinstance(version, int)` rejects it. Read the literal back out of the
+// manifest text so the deploy-time failure surfaces here instead.
+//
+// Best effort by construction: it only sees a plain `[genui]` table with a
+// `version = ...` line. An inline (`genui = { version = 1.0 }`) or dotted
+// (`genui.version = 1.0`) spelling is invisible to it and still fails at
+// deploy, with this same message.
+function rejectFloatVersion(text) {
+    const literal = tableScalarLiteral(text, "genui", "version");
+    if (literal === null || !isTomlFloatLiteral(literal))
+        return;
+    throw new GenuiError("[genui] version must be a positive integer");
+}
+function isTomlFloatLiteral(literal) {
+    if (/^[+-]?(inf|nan)$/.test(literal))
+        return true;
+    if (/^[+-]?0[xob]/i.test(literal))
+        return false; // hex/octal/binary are integers
+    return /[.eE]/.test(literal);
+}
+function parseComponents(raw, hasBundle) {
+    if (!Array.isArray(raw))
+        throw new GenuiError("[genui] components must be an array of tables");
+    const out = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        if (!plainObject(entry))
+            throw new GenuiError("each [genui] component must be a table");
+        const rawName = entry.name;
+        if (typeof rawName !== "string" || !IDENTIFIER.test(rawName.trim())) {
+            throw new GenuiError("each [genui] component needs a non-empty name");
+        }
+        const name = rawName.trim();
+        if (seen.has(name))
+            throw new GenuiError(`duplicate genui component: '${name}'`);
+        seen.add(name);
+        const tier = entry.tier === undefined ? 1 : entry.tier;
+        if (tier !== 1 && tier !== 2 && tier !== 3) {
+            throw new GenuiError(`component '${name}' tier must be one of 1, 2, 3`);
+        }
+        if (tier >= 2 && !hasBundle) {
+            throw new GenuiError(`component '${name}' is tier ${tier} (builder code) but [genui] declares no bundle`);
+        }
+        out.push({ name, tier });
+    }
+    return out;
+}
+// --- bundle validation (mirror of bundle.py _validate_payload) --------------
+/**
+ * The catalog the data plane synthesizes when `[genui]` declares no bundle
+ * (bundle.py load_genui_bundle_with_bytes). It runs the SAME payload validation
+ * over it, so a Tier-1-only catalog is not unvalidated: a component whose name
+ * is not a Dharta builtin, or a 129th component, is rejected at deploy.
+ */
+export function synthesizeBundlePayload(section) {
+    return {
+        format: BUNDLE_FORMAT,
+        catalog_id: section.catalogId,
+        version: section.version,
+        components: section.components.map((component) => ({
+            name: component.name,
+            tier: component.tier,
+            implementation: { builtin: component.name },
+        })),
+    };
+}
+/**
+ * Throw `GenuiError` unless `payload` is a bundle this manifest can ship.
+ *
+ * `rawText` is the bundle file's bytes as read off disk, when there was one.
+ * The whole integer rule lives here because JavaScript cannot see it in the
+ * parsed value: `JSON.parse` collapses `1.0` to `1`, while Python's
+ * `json.loads` yields a float that fails `isinstance(..., int)`.
+ */
+export function validateBundlePayload(payload, section, rawText) {
+    if (!plainObject(payload))
+        throw new GenuiError("[genui] bundle root must be an object");
+    if (payload.format !== BUNDLE_FORMAT) {
+        throw new GenuiError(`[genui] bundle format must be '${BUNDLE_FORMAT}'`);
+    }
+    if (rawText !== undefined)
+        rejectNonIntegerLiterals(rawText);
+    if (payload.catalog_id !== section.catalogId ||
+        typeof payload.version !== "number" ||
+        !Number.isInteger(payload.version) ||
+        payload.version !== section.version) {
+        throw new GenuiError("[genui] bundle identity does not match dharta.toml");
+    }
+    const rawComponents = payload.components;
+    if (!Array.isArray(rawComponents) || rawComponents.length > MAX_COMPONENTS) {
+        throw new GenuiError(`[genui] bundle components must be an array of at most ${MAX_COMPONENTS} entries`);
+    }
+    const actual = new Map();
+    for (const component of rawComponents) {
+        if (!plainObject(component)) {
+            throw new GenuiError("[genui] every bundled component must be an object");
+        }
+        const name = component.name;
+        const tier = component.tier;
+        if (typeof name !== "string" ||
+            !name ||
+            actual.has(name) ||
+            (tier !== 1 && tier !== 2 && tier !== 3)) {
+            throw new GenuiError("[genui] bundled component name/tier is invalid or duplicated");
+        }
+        actual.set(name, tier);
+        if (component.props_schema !== undefined && !plainObject(component.props_schema)) {
+            throw new GenuiError(`[genui] component '${name}' props_schema must be an object`);
+        }
+        const events = component.events === undefined ? {} : component.events;
+        if (!plainObject(events)) {
+            throw new GenuiError(`[genui] component '${name}' events must be an object`);
+        }
+        validateEvents(name, events);
+        if (!plainObject(component.implementation)) {
+            throw new GenuiError(`[genui] component '${name}' needs an implementation object`);
+        }
+        validateImplementation(name, tier, component.implementation);
+    }
+    const expected = new Map(section.components.map((c) => [c.name, c.tier]));
+    const matches = actual.size === expected.size &&
+        [...expected].every(([name, tier]) => actual.get(name) === tier);
+    if (!matches) {
+        throw new GenuiError("[genui] bundled components do not exactly match dharta.toml " +
+            `(dharta.toml: ${describeComponents(expected)}; bundle: ${describeComponents(actual)})`);
+    }
+}
+function describeComponents(components) {
+    const entries = [...components].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return entries.length === 0
+        ? "(none)"
+        : entries.map(([name, tier]) => `${name}@tier${tier}`).join(", ");
+}
+function validateImplementation(name, tier, impl) {
+    if (tier === 1) {
+        const keys = Object.keys(impl);
+        const builtin = impl.builtin;
+        if (keys.length !== 1 ||
+            keys[0] !== "builtin" ||
+            typeof builtin !== "string" ||
+            !TIER1_BUILTINS.includes(builtin)) {
+            throw new GenuiError(`[genui] Tier-1 component '${name}' must alias a Dharta builtin ` +
+                `(one of ${TIER1_BUILTINS.join(", ")})`);
+        }
+        // A built-in name may only alias itself. The widget merges a registered
+        // catalog OVER the built-in one, so `{ name: "Card", builtin: "Badge" }`
+        // reads as an alias but takes the built-in's name, and every Card in the
+        // transcript - including surfaces that never asked for this catalog - would
+        // draw as a Badge.
+        if (TIER1_BUILTINS.includes(name) && builtin !== name) {
+            throw new GenuiError(`[genui] Tier-1 component '${name}' takes a built-in component name and aliases ` +
+                `'${builtin}'; a built-in name may only alias itself. Rename the component, or ` +
+                `drop the alias so '${name}' renders as the built-in '${name}'.`);
+        }
+        return;
+    }
+    // A builder component may not take a built-in's name: the renderer resolves
+    // by name, so a Tier-2/3 component called `Card` would shadow the host
+    // primitive every other surface expects. Tier-1 entries are aliases FOR those
+    // primitives, so they keep the name.
+    if (TIER1_BUILTINS.includes(name)) {
+        throw new GenuiError(`[genui] Tier-${tier} component '${name}' may not reuse the name of a Dharta builtin; ` +
+            "rename it, or declare it as a Tier-1 alias");
+    }
+    const field = tier === 2 ? "worker" : "html";
+    const limit = tier === 2 ? MAX_WORKER_BYTES : MAX_HTML_BYTES;
+    const source = impl[field];
+    const keys = Object.keys(impl);
+    if (keys.length !== 1 ||
+        keys[0] !== field ||
+        typeof source !== "string" ||
+        Buffer.byteLength(source, "utf8") > limit) {
+        throw new GenuiError(`[genui] Tier-${tier} component '${name}' needs bounded ${field} source ` +
+            `(a string of at most ${limit} bytes)`);
+    }
+}
+function validateEvents(name, events) {
+    const entries = Object.entries(events);
+    if (entries.length > MAX_EVENTS) {
+        throw new GenuiError(`[genui] component '${name}' declares too many events`);
+    }
+    for (const [eventName, raw] of entries) {
+        if (!eventName ||
+            // Python's len() counts code points, so an emoji costs 1 there and 2 in
+            // UTF-16. Count the same units it does.
+            Array.from(eventName).length > MAX_EVENT_NAME_LENGTH ||
+            !plainObject(raw) ||
+            !EVENT_CADENCES.includes(raw.cadence)) {
+            throw new GenuiError(`[genui] component '${name}' has an invalid event declaration '${eventName}' ` +
+                `(each event needs cadence = ${EVENT_CADENCES.join(" | ")})`);
+        }
+        // `context_schema: null` is accepted: Python tests `is not None` first.
+        if (raw.context_schema !== undefined &&
+            raw.context_schema !== null &&
+            !plainObject(raw.context_schema)) {
+            throw new GenuiError(`[genui] component '${name}' event schema must be an object`);
+        }
+    }
+}
+/**
+ * Reject a numeric literal the contract requires to be an integer but which was
+ * written as a float: the root object's `version`, and `tier` inside the root's
+ * `components` array. Python's `json.loads` returns a float for `1.0` / `1e0`
+ * and the data plane's `isinstance(..., int)` refuses it, while JavaScript has
+ * a single number type and cannot tell after parsing.
+ *
+ * Depth-tracked so it judges only those two positions: a component's
+ * `props_schema` may legitimately describe a `version` or `tier` of its own,
+ * and that is builder data, not the bundle's contract.
+ */
+function rejectNonIntegerLiterals(text) {
+    // The key that opened each container: null for the root object and for the
+    // objects inside an array, "components" for the components array itself.
+    const containers = [];
+    let lastKey = null;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (char === '"') {
+            let end = index + 1;
+            while (end < text.length && text[end] !== '"')
+                end += text[end] === "\\" ? 2 : 1;
+            lastKey = text.slice(index + 1, end);
+            index = end;
+            continue;
+        }
+        if (char === "{" || char === "[") {
+            containers.push(lastKey);
+            lastKey = null;
+            continue;
+        }
+        if (char === "}" || char === "]") {
+            containers.pop();
+            lastKey = null;
+            continue;
+        }
+        if (char !== ":")
+            continue;
+        const atRoot = containers.length === 1;
+        const inComponent = containers.length === 3 && containers[1] === "components" && containers[2] === null;
+        if (!(atRoot && lastKey === "version") && !(inComponent && lastKey === "tier"))
+            continue;
+        const literal = text.slice(index + 1).match(/^\s*([^\s,}\]]+)/)?.[1];
+        if (literal === undefined || !isJsonFloatLiteral(literal))
+            continue;
+        throw new GenuiError(lastKey === "version"
+            ? "[genui] bundle identity does not match dharta.toml"
+            : "[genui] bundled component name/tier is invalid or duplicated");
+    }
+}
+function isJsonFloatLiteral(literal) {
+    return /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(literal) && /[.eE]/.test(literal);
+}
+/**
+ * The first number literal in `text` that a JavaScript double cannot carry, or
+ * null when there is none. Two shapes qualify, and both are silent:
+ *
+ * An integer beyond `Number.MAX_SAFE_INTEGER`. `JSON.parse` rounds
+ * `12345678901234567890` to `12345678901234567000` and nothing downstream can
+ * tell, so a build would write digits into the bundle that the source never
+ * had - and the data plane, whose `int` is arbitrary precision, would read the
+ * builder's own digits back out of its own copy.
+ *
+ * A float that overflows a double. `1e400` parses to `Infinity`, which
+ * `JSON.stringify` writes as `null`: the bundle would carry no number at all
+ * where the source had one, while Python's `float` reads the same literal as
+ * `inf` and keeps it.
+ *
+ * Every other float is left alone. `0.1` and `1.5e300` are IEEE doubles on both
+ * planes, so the two lose exactly the same precision and still agree.
+ *
+ * The only place the real number still exists is the raw text, so read it
+ * there, the same way `rejectNonIntegerLiterals` reads `version` and `tier`.
+ */
+function findUnsafeNumberLiteral(text) {
+    // One frame per open container. `base` is the path of the container itself;
+    // `key` and `index` say where the container's NEXT value goes.
+    const frames = [];
+    // The path of the value about to be read.
+    const at = () => {
+        const frame = frames[frames.length - 1];
+        if (frame === undefined)
+            return "the document root";
+        if (frame.array)
+            return `${frame.base}[${frame.index}]`;
+        return frame.base === "" ? frame.key : `${frame.base}.${frame.key}`;
+    };
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (char === '"') {
+            let end = index + 1;
+            while (end < text.length && text[end] !== '"')
+                end += text[end] === "\\" ? 2 : 1;
+            const value = text.slice(index + 1, end);
+            index = end;
+            // A string followed by `:` is its object's next key. Every other string
+            // is a value, and a value never moves the path.
+            const frame = frames[frames.length - 1];
+            if (frame !== undefined && !frame.array && /^\s*:/.test(text.slice(index + 1))) {
+                frame.key = value;
+            }
+            continue;
+        }
+        if (char === "{" || char === "[") {
+            frames.push({
+                array: char === "[",
+                base: frames.length === 0 ? "" : at(),
+                key: "",
+                index: 0,
+            });
+            continue;
+        }
+        if (char === "}" || char === "]") {
+            frames.pop();
+            continue;
+        }
+        if (char === ",") {
+            const frame = frames[frames.length - 1];
+            if (frame?.array)
+                frame.index += 1;
+            continue;
+        }
+        if (char !== "-" && (char < "0" || char > "9"))
+            continue;
+        const literal = text.slice(index).match(/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/)?.[0];
+        if (literal === undefined)
+            continue;
+        index += literal.length - 1;
+        if (/^-?\d+$/.test(literal)) {
+            // BigInt, not Number: the comparison has to be exact at the boundary,
+            // and Number() has already lost the digits that decide it.
+            const digits = literal.startsWith("-") ? literal.slice(1) : literal;
+            if (BigInt(digits) > BigInt(Number.MAX_SAFE_INTEGER)) {
+                return { path: at(), literal, kind: "integer" };
+            }
+        }
+        else if (!Number.isFinite(Number(literal))) {
+            return { path: at(), literal, kind: "overflow" };
+        }
+    }
+    return null;
+}
+// --- canonical serialization ------------------------------------------------
+/**
+ * Byte-for-byte reproducible JSON, matching the data plane's own canonical form
+ * (`json.dumps(..., ensure_ascii=True, separators=(",", ":"), sort_keys=True)`):
+ * sorted keys, compact separators, ASCII only. The digest recorded in
+ * dharta.toml is over these exact bytes, so a rebuild of unchanged sources must
+ * produce an unchanged file.
+ *
+ * Written out key by key rather than sorted into an object and handed to
+ * `JSON.stringify`, because a JavaScript object does not preserve the order you
+ * insert integer-like keys in: it emits those first, in ascending numeric
+ * order. `{"1","10","2","alpha"}` is Python's order and `{"1","2","10","alpha"}`
+ * is what an object round-trip produces, which is a different digest for the
+ * same catalog.
+ *
+ * Numbers are JavaScript doubles, and this writes back whatever `JSON.parse`
+ * produced. `1.0` therefore serializes as `1` and `-0.0` as `0` - the source
+ * spelling is already gone by the time the value gets here, and re-deriving it
+ * is not possible. Both forms are the same double on the data plane too, so
+ * this only ever narrows the spelling, never the value.
+ *
+ * Two shapes a double cannot carry at all: an integer beyond
+ * `Number.MAX_SAFE_INTEGER`, which arrives already rounded, and a float that
+ * overflows a double, which arrives as `Infinity` and would be written out as
+ * `null`. `findUnsafeNumberLiteral` refuses both in a component.json rather
+ * than letting the build ship a number the source never wrote.
+ */
+export function canonicalJson(value) {
+    return escapeNonAscii(encodeCanonical(value));
+}
+function encodeCanonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(encodeCanonical).join(",")}]`;
+    if (plainObject(value)) {
+        const members = Object.keys(value)
+            .sort(byCodePoint)
+            .map((key) => `${JSON.stringify(key)}:${encodeCanonical(value[key])}`);
+        return `{${members.join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+// Python sorts by Unicode code point; JavaScript's default sort compares UTF-16
+// code units, which orders astral-plane keys differently. Compare code points so
+// a builder's exotic props_schema key cannot make the two planes disagree.
+function byCodePoint(a, b) {
+    const ca = Array.from(a);
+    const cb = Array.from(b);
+    for (let i = 0; i < Math.min(ca.length, cb.length); i++) {
+        const delta = (ca[i].codePointAt(0) ?? 0) - (cb[i].codePointAt(0) ?? 0);
+        if (delta !== 0)
+            return delta;
+    }
+    return ca.length - cb.length;
+}
+function escapeNonAscii(json) {
+    // U+007F..U+FFFF, matching Python's ensure_ascii, which escapes everything
+    // outside the printable ASCII range - DEL included.
+    return json.replace(/[\u007f-\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Read `dir/dharta.toml`. Throws when it is missing or unparseable. */
+export async function readManifest(dir) {
+    const manifestPath = path.join(dir, "dharta.toml");
+    let text;
+    try {
+        text = await fs.readFile(manifestPath, "utf8");
+    }
+    catch {
+        throw new GenuiError(`No dharta.toml at ${manifestPath}. Run this from an agent folder, or pass its path.`);
+    }
+    try {
+        return { path: manifestPath, text, parsed: TOML.parse(text) };
+    }
+    catch (error) {
+        throw new GenuiError(`Could not parse ${manifestPath}: ${error.message}`);
+    }
+}
+/**
+ * Read and parse an agent's `[genui]` section once. Every command path threads
+ * the result rather than re-reading the manifest: `dharta dev`'s doctor already
+ * holds a parsed one and hands it straight in.
+ */
+export async function loadGenui(source, options = {}) {
+    const manifest = typeof source === "string" ? await readManifest(source) : source;
+    return {
+        ...manifest,
+        section: parseGenuiSection(manifest.parsed, { ...options, text: manifest.text }),
+    };
+}
+// Release-relative paths are split on "/" only, matching pathlib's Path.parts
+// on the POSIX data plane: there, a backslash is an ordinary filename
+// character, and treating it as a separator here would reject paths the server
+// accepts.
+function relativeParts(relative) {
+    return relative.split("/").filter((part) => part !== "" && part !== ".");
+}
+// A release-relative path may not escape the agent folder - the data plane
+// rejects the same thing in load_genui_bundle.
+function requireInsideRelease(relative, label) {
+    if (path.isAbsolute(relative) ||
+        relative.startsWith("/") ||
+        relativeParts(relative).includes("..")) {
+        throw new GenuiError(`[genui] ${label} must stay inside the release: ${relative}`);
+    }
+    return relative;
+}
+/**
+ * Walk a release-relative path's parent components, refusing a symlink or a
+ * non-directory exactly the way bundle.py's `_read_regular_file` does. Returns
+ * the absolute leaf path.
+ *
+ * `withPath` names the offending component in the message. The read path leaves
+ * it off so a pre-flight refusal reads exactly like the release rejection it
+ * predicts; the build turns it on, because there the developer needs to know
+ * which link to remove.
+ */
+async function walkBundleParents(root, relative, options) {
+    const parts = relativeParts(relative);
+    let cursor = root;
+    for (const part of parts.slice(0, -1)) {
+        cursor = path.join(cursor, part);
+        let stats;
+        try {
+            stats = await fs.lstat(cursor);
+        }
+        catch {
+            // Python reaches a missing parent as "crosses a non-directory". The
+            // rejection is the same either way; which sentence is more useful
+            // depends on the caller, so it decides.
+            if (options.onMissingParent === "throw") {
+                throw new GenuiError(missingBundleMessage(relative));
+            }
+            return null;
+        }
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw new GenuiError(options.withPath
+                ? `${CROSSES_SYMLINK}: ${path.relative(root, cursor)}`
+                : CROSSES_SYMLINK);
+        }
+    }
+    return path.join(root, ...parts);
+}
+function missingBundleMessage(relative) {
+    return `[genui] bundle does not exist: ${relative} - run \`dharta genui build\` to build it.`;
+}
+/**
+ * Read the bundle exactly the way bundle.py's `_read_regular_file` does: no
+ * symlink anywhere on the path, a regular file at the leaf, and nothing larger
+ * than the cap. `lstat` throughout, because the point is the link itself, not
+ * what it points at - a symlinked bundle resolves fine locally and is refused
+ * by the release validator's O_NOFOLLOW open.
+ */
+async function readBundleBytes(root, relative) {
+    const file = await walkBundleParents(root, relative, {
+        withPath: false,
+        onMissingParent: "throw",
+    });
+    let stats;
+    try {
+        stats = await fs.lstat(file);
+    }
+    catch {
+        throw new GenuiError(missingBundleMessage(relative));
+    }
+    if (stats.isSymbolicLink() || !stats.isFile())
+        throw new GenuiError(NOT_A_REGULAR_FILE);
+    if (stats.size > MAX_BUNDLE_BYTES) {
+        throw new GenuiError(`${NOT_A_REGULAR_FILE} no larger than 5 MiB`);
+    }
+    return fs.readFile(file);
+}
+/**
+ * The write-side of the same policy. Without it the build happily writes
+ * THROUGH a symlink that every later read then refuses, so `build` would report
+ * success and `check` would immediately contradict it.
+ */
+async function assertBundleWritable(root, relative) {
+    const file = await walkBundleParents(root, relative, {
+        withPath: true,
+        onMissingParent: "stop", // mkdir will create it; nothing to inspect yet
+    });
+    if (file === null)
+        return;
+    const stats = await fs.lstat(file).catch(() => null);
+    if (stats === null)
+        return; // does not exist yet: the normal first build
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+        throw new GenuiError(`${NOT_A_REGULAR_FILE}: ${relative}`);
+    }
+}
+/**
+ * Report every reason the data plane would reject this agent's `[genui]`
+ * declaration. Shared by `dharta genui check`, `dharta dev`'s doctor
+ * (warnings), and the deploy pre-flight (refusal) so all three say the same
+ * thing. Pass an already-read manifest to avoid a second read.
+ */
+export async function checkGenui(source) {
+    let manifest;
+    try {
+        manifest = typeof source === "string" ? await readManifest(source) : source;
+    }
+    catch {
+        // A missing or unparseable dharta.toml is not a genui problem: the doctor
+        // and the deploy both report it in their own words, on their own path.
+        return { manifest: path.join(source, "dharta.toml"), section: null, problems: [] };
+    }
+    const dir = path.dirname(manifest.path);
+    let section;
+    try {
+        section = parseGenuiSection(manifest.parsed, { text: manifest.text });
+    }
+    catch (error) {
+        return { manifest: manifest.path, section: null, problems: [error.message] };
+    }
+    // No section: generative UI is off. Disabled: the data plane skips the
+    // catalog entirely (releases.py _validate_genui_tree), so nothing below can
+    // fail a deploy.
+    if (section === null || !section.enabled) {
+        return { manifest: manifest.path, section, problems: [] };
+    }
+    const problems = [];
+    try {
+        // A Tier-1-only catalog carries no file, but the data plane still
+        // synthesizes and validates a payload for it, so we do too.
+        if (section.bundle === null) {
+            validateBundlePayload(synthesizeBundlePayload(section), section);
+        }
+        else {
+            requireInsideRelease(section.bundle, "bundle");
+            const raw = await readBundleBytes(dir, section.bundle);
+            const digest = sha256Hex(raw);
+            if (digest !== section.bundleSha256) {
+                problems.push("[genui] bundle bytes do not match bundle_sha256 " +
+                    `(${section.bundle} is ${digest}, dharta.toml records ${section.bundleSha256}) - ` +
+                    "run `dharta genui build` to rebuild it and re-record the digest.");
+            }
+            else {
+                const text = decodeUtf8(raw, `[genui] bundle must be valid UTF-8 JSON`);
+                let payload;
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch {
+                    throw new GenuiError("[genui] bundle must be valid UTF-8 JSON");
+                }
+                validateBundlePayload(payload, section, text);
+            }
+        }
+    }
+    catch (error) {
+        problems.push(error.message);
+    }
+    return { manifest: manifest.path, section, problems };
+}
+// Decode UTF-8 strictly. Node's default replaces an invalid byte with U+FFFD,
+// which would silently ship a mangled worker or document.
+function decodeUtf8(bytes, message) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new GenuiError(message);
+    }
+}
+/**
+ * Deploy pre-flight: refuse locally, before anything is pushed or uploaded,
+ * with the message the release validator would return.
+ */
+export async function genuiPreflight(dir, options = {}) {
+    const { section, problems } = await checkGenui(dir);
+    if (options.deployFiles && section?.enabled && section.bundle) {
+        problems.push(...(await missingFromDeploy(dir, section.bundle, options.deployFiles)));
+    }
+    if (problems.length === 0)
+        return;
+    throw new Error("Generative-UI pre-flight failed - the release would be rejected:\n" +
+        problems.map((problem) => `  ${problem}`).join("\n") +
+        "\n\n  Fix the [genui] section in dharta.toml (or run `dharta genui build`), then re-deploy.");
+}
+async function missingFromDeploy(dir, bundle, deployFiles) {
+    // A bundle that is not on disk is already reported by checkGenui, with the
+    // fix that actually applies: build it. "git is not shipping it" is true of
+    // every file that does not exist, so saying it here would name a second
+    // cause that is only a consequence of the first.
+    const onDisk = await fs
+        .stat(path.join(dir, ...relativeParts(bundle)))
+        .then(() => true)
+        .catch(() => false);
+    if (!onDisk)
+        return [];
+    // Listing can fail for reasons that are the deploy's own to report (a nested
+    // repository, a git that will not run). An advisory pre-flight never blocks
+    // on its inability to answer.
+    const files = await deployFiles().catch(() => null);
+    if (files === null)
+        return [];
+    // Compare normalized paths, not the two spellings of one path. A bundle
+    // declared with a leading "./" or a doubled slash names the file git lists
+    // plainly, on both planes: pathlib's Path.parts drops the same "." and empty
+    // segments relativeParts does. Comparing the raw strings would refuse a
+    // bundle the deploy is carrying, with a git-ignore diagnosis that is wrong.
+    const wanted = relativeParts(bundle).join("/");
+    if (files.some((file) => relativeParts(file).join("/") === wanted))
+        return [];
+    return [
+        `${wanted} is not among the files this deploy ships, so the release would fail on a ` +
+            "missing [genui] bundle. Git ignore rules exclude it: unignore it, or force-add it " +
+            `with \`git add -f ${wanted}\`, then commit it and re-run \`dharta deploy\`.`,
+    ];
+}
+/** `dharta genui check`: the structured result. Throws when something is wrong. */
+export async function genuiCheckData(dir) {
+    const manifest = await readManifest(dir); // a missing manifest is an error here
+    const { section, problems } = await checkGenui(manifest);
+    if (problems.length > 0) {
+        throw new Error("[genui] check failed - a deploy would be rejected:\n" +
+            problems.map((problem) => `  ${problem}`).join("\n"));
+    }
+    if (section === null) {
+        return { manifest: manifest.path, configured: false, components: [] };
+    }
+    return {
+        manifest: manifest.path,
+        configured: true,
+        catalogId: section.catalogId,
+        version: section.version,
+        enabled: section.enabled,
+        bundle: section.bundle,
+        bundleSha256: section.bundleSha256,
+        components: section.components,
+    };
+}
+export function formatGenuiStatus(status) {
+    if (!status.configured) {
+        return `No [genui] section in ${status.manifest} - generative UI is off for this agent.`;
+    }
+    const count = status.components.length;
+    const lines = [
+        `✓ [genui] catalog '${status.catalogId}' v${status.version}: ` +
+            `${count} component${count === 1 ? "" : "s"} (${describeTiers(status.components)})`,
+    ];
+    if (status.enabled === false) {
+        // The catalog is registered but not served, and neither the data plane nor
+        // this check read its bundle. Saying the digest matches would be a claim
+        // nothing verified.
+        lines.push("  enabled = false: the catalog is not served, so its bundle was not checked.");
+    }
+    else if (status.bundle === null) {
+        lines.push("  No bundle: every component is Tier 1, so Dharta renders them with its own primitives.");
+    }
+    else {
+        lines.push(`  Bundle ${status.bundle} matches bundle_sha256 ${status.bundleSha256}.`);
+    }
+    return lines.join("\n");
+}
+function describeTiers(components) {
+    const parts = [1, 2, 3]
+        .map((tier) => ({ tier, count: components.filter((c) => c.tier === tier).length }))
+        .filter((entry) => entry.count > 0)
+        .map((entry) => `${entry.count} Tier ${entry.tier}`);
+    return parts.length > 0 ? parts.join(", ") : "none";
+}
+const SPEC_KEYS = ["tier", "builtin", "props_schema", "events"];
+/**
+ * Compile `[genui.build] source` into a validated bundle payload. Nothing is
+ * written: this is the seam at the data plane's contract, so a caller can
+ * assert on the exact object a release would carry.
+ */
+export async function compileBundlePayload(section, dir) {
+    requireInsideRelease(section.source, "source");
+    const sourceDir = path.join(dir, section.source);
+    await requireExactMatch(section, sourceDir, await discoverComponents(sourceDir, section.source));
+    const components = await Promise.all(section.components.map((component) => compileComponent(sourceDir, section.source, component)));
+    const payload = { format: BUNDLE_FORMAT, catalog_id: section.catalogId, version: section.version, components };
+    validateBundlePayload(payload, section);
+    return payload;
+}
+/**
+ * Compile `[genui.build] source` into the bundle at `[genui] bundle` and record
+ * its digest in dharta.toml. Validates everything the data plane validates
+ * before writing, so a bad catalog fails here rather than at deploy.
+ */
+export async function buildGenui(dir, log) {
+    const { path: manifestPath, text, section } = await loadGenui(dir, { requireDigest: false });
+    if (section === null) {
+        throw new GenuiError(`No [genui] section in ${manifestPath}. Add one (see the commented block a ` +
+            "scaffolded dharta.toml ships with) before building a component bundle.");
+    }
+    if (section.bundle === null) {
+        // parseGenuiSection already rejected a Tier-2/3 component without a bundle,
+        // so reaching here means Tier-1 only. Nothing is written, but the catalog
+        // the data plane will synthesize still has to be valid.
+        validateBundlePayload(synthesizeBundlePayload(section), section);
+        log(`Nothing to build: [genui] declares no bundle and all ${section.components.length} ` +
+            "component(s) are Tier 1, which Dharta renders with its own primitives.");
+        return { status: "nothing-to-build", components: section.components.length };
+    }
+    requireInsideRelease(section.bundle, "bundle");
+    const payload = await compileBundlePayload(section, dir);
+    const digest = await writeBundle(dir, { manifestPath, text, section }, payload);
+    log(`✓ Built ${section.components.length} component${section.components.length === 1 ? "" : "s"} ` +
+        `(${describeTiers(section.components)}) -> ${section.bundle}`);
+    log(`  bundle_sha256 = "${digest}" recorded in dharta.toml`);
+    if (!section.enabled) {
+        log("  Note: enabled = false, so this catalog is registered but not served.");
+    }
+    return {
+        status: "built",
+        bundle: section.bundle,
+        digest,
+        components: section.components.length,
+    };
+}
+async function writeBundle(dir, manifest, payload) {
+    const { manifestPath, text, section } = manifest;
+    const relative = section.bundle;
+    const bytes = Buffer.from(`${canonicalJson(payload)}\n`, "utf8");
+    if (bytes.byteLength > MAX_BUNDLE_BYTES) {
+        throw new GenuiError(`Built bundle is ${bytes.byteLength} bytes; the limit is ${MAX_BUNDLE_BYTES}. ` +
+            "Move the largest component to a leaner implementation or split the catalog.");
+    }
+    const digest = sha256Hex(bytes);
+    // Refuse to write through a symlink the read side would then reject: `build`
+    // must not report success that `check` immediately contradicts.
+    await assertBundleWritable(dir, relative);
+    // Record the digest, in memory, before anything lands. A manifest whose
+    // [genui] table cannot be patched (an inline table, or dotted keys) must fail
+    // with setGenuiBundleSha256's hand-edit guidance and leave no half-built tree:
+    // a bundle on disk with no matching digest is exactly the state `check`
+    // exists to catch.
+    const patched = setGenuiBundleSha256(text, digest);
+    const bundlePath = path.join(dir, ...relativeParts(relative));
+    await fs.mkdir(path.dirname(bundlePath), { recursive: true });
+    await fs.writeFile(bundlePath, bytes);
+    // Read back what actually landed, BEFORE dharta.toml records the digest. An
+    // editor, a filter driver, or a CRLF checkout can change the bytes between
+    // write and hash, and a manifest patched first would be left naming a digest
+    // the file on disk does not have - the state this check exists to prevent.
+    const written = sha256Hex(await fs.readFile(bundlePath));
+    if (written !== digest) {
+        throw new GenuiError(`Wrote ${relative} but it hashes to ${written}, not the expected ${digest}. ` +
+            "Something is rewriting the file on disk (a Git filter or editor hook is the " +
+            "usual cause); the release would be rejected. dharta.toml was left untouched, so " +
+            "it still records whatever digest it had before this build.");
+    }
+    try {
+        await fs.writeFile(manifestPath, patched, "utf8");
+    }
+    catch (error) {
+        // The bundle is on disk and dharta.toml still names the previous digest,
+        // so `check` reports a mismatch until the two agree. Nothing is lost: the
+        // build is a pure function of the sources, so a rerun produces the same
+        // bytes and records the same digest.
+        throw new GenuiError(`Wrote ${relative}, but could not record its digest in ${manifestPath}: ` +
+            `${error.message}. The bundle is built and correct; only the manifest ` +
+            "is behind, so `dharta genui check` reports a digest mismatch until it is written. " +
+            "Fix the cause (a read-only file, a full disk), then run `dharta genui build` " +
+            "again - it rebuilds the same bytes, so repeating it is safe.");
+    }
+    return digest;
+}
+/**
+ * Every component directory under `sourceDir`, named by its path relative to
+ * it. A directory holding a `component.json` IS a component and is not
+ * descended into, so a namespaced name like `charts/Bar` (legal in the
+ * identifier both planes share) lives at `charts/Bar/component.json`.
+ *
+ * Unlike the bundle path these follow symlinks - the source layout is a CLI
+ * concern the data plane never sees, and `readdir`'s Dirent would report a
+ * symlinked component folder as a link rather than a directory and silently
+ * hide it.
+ */
+async function discoverComponents(sourceDir, label) {
+    const found = [];
+    const walk = async (absolute, relative) => {
+        let names;
+        try {
+            names = await fs.readdir(absolute);
+        }
+        catch {
+            if (relative !== "")
+                return;
+            throw new GenuiError(`[genui.build] source folder not found: ${label}. Create one directory per component ` +
+                `there (for example ${label}/Card/${COMPONENT_SPEC_FILE}), or set ` +
+                '`source = "<path>"` in [genui.build].');
+        }
+        for (const name of names.sort()) {
+            // Dot-directories are tooling, never components.
+            if (name.startsWith("."))
+                continue;
+            const child = path.join(absolute, name);
+            const stats = await fs.stat(child).catch(() => null);
+            if (!stats?.isDirectory())
+                continue;
+            const childRelative = relative === "" ? name : `${relative}/${name}`;
+            const isComponent = await fs
+                .stat(path.join(child, COMPONENT_SPEC_FILE))
+                .then((spec) => spec.isFile())
+                .catch(() => false);
+            if (isComponent)
+                found.push(childRelative);
+            else
+                await walk(child, childRelative);
+        }
+    };
+    await walk(sourceDir, "");
+    return found.sort();
+}
+// The manifest's `components` array is the builder's declaration of what this
+// release ships and at what trust tier. A build never edits it: a mismatch is a
+// question only the builder can answer, so name both sides and stop.
+async function requireExactMatch(section, sourceDir, found) {
+    const declared = new Set(section.components.map((c) => c.name));
+    const onDisk = new Set(found);
+    const missing = [...declared].filter((name) => !onDisk.has(name)).sort();
+    const extra = found.filter((name) => !declared.has(name));
+    if (missing.length === 0 && extra.length === 0)
+        return;
+    // A component is DISCOVERED by its component.json, so a folder that exists
+    // but has no spec reads as "missing" here. Say the more useful thing.
+    for (const name of missing) {
+        const folder = componentDir(sourceDir, section.source, name);
+        const exists = await fs.stat(folder).then((st) => st.isDirectory()).catch(() => false);
+        if (exists) {
+            throw new GenuiError(`[genui] component '${name}': ${section.source}/${name}/${COMPONENT_SPEC_FILE} is missing.`);
+        }
+    }
+    const lines = ["[genui] source folders do not match the components declared in dharta.toml."];
+    if (missing.length > 0) {
+        lines.push(`  Declared but missing from ${section.source}/: ${missing.join(", ")}`);
+    }
+    if (extra.length > 0) {
+        lines.push(`  Present in ${section.source}/ but not declared: ${extra.join(", ")}`);
+    }
+    lines.push("  Add the missing folders, or add/remove entries in the [genui] components array.", "  `dharta genui build` never edits that array - the trust tier is your declaration.");
+    throw new GenuiError(lines.join("\n"));
+}
+// A component name is only ever a JSON string on the data plane, but the CLI
+// turns it into a path - and the identifier both planes share permits "." and
+// "/", so "a/../b" is a legal name. Resolve here, once, and refuse to climb out
+// of the source folder.
+function componentDir(sourceDir, label, name) {
+    const parts = relativeParts(name);
+    if (name.startsWith("/") || parts.includes("..")) {
+        throw new GenuiError(`[genui] component '${name}' cannot be a source path: it escapes ${label}/.`);
+    }
+    return path.join(sourceDir, ...parts);
+}
+async function compileComponent(sourceDir, label, component) {
+    const dir = componentDir(sourceDir, label, component.name);
+    const where = `${label}/${component.name}/${COMPONENT_SPEC_FILE}`;
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(dir, COMPONENT_SPEC_FILE), "utf8");
+    }
+    catch {
+        throw new GenuiError(`[genui] component '${component.name}': ${where} is missing.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new GenuiError(`[genui] component '${component.name}': ${where} is not valid JSON (${error.message}).`);
+    }
+    if (!plainObject(parsed)) {
+        throw new GenuiError(`[genui] component '${component.name}': ${where} must be a JSON object.`);
+    }
+    const unsafe = findUnsafeNumberLiteral(raw);
+    if (unsafe !== null) {
+        throw new GenuiError(`[genui] component '${component.name}': ${where} has the number ${unsafe.literal} at ` +
+            `${unsafe.path}, which ` +
+            (unsafe.kind === "integer"
+                ? "is outside the range JavaScript represents exactly (up to " +
+                    `${Number.MAX_SAFE_INTEGER}). The build would round it and ship a number you ` +
+                    "never wrote, while the data plane keeps yours exactly."
+                : "overflows a JavaScript double to Infinity. The build would ship `null` where " +
+                    "you wrote a number, while the data plane reads the same literal as a float " +
+                    "and keeps it.") +
+            " Write it as a string, or use a number a double can hold.");
+    }
+    const unknownKeys = Object.keys(parsed).filter((key) => !SPEC_KEYS.includes(key));
+    if (unknownKeys.length > 0) {
+        throw new GenuiError(`[genui] component '${component.name}': ${where} has unknown key(s) ` +
+            `${unknownKeys.join(", ")}. Supported: ${SPEC_KEYS.join(", ")}.`);
+    }
+    const tier = parsed.tier;
+    if (tier !== 1 && tier !== 2 && tier !== 3) {
+        throw new GenuiError(`[genui] component '${component.name}': ${where} needs tier 1, 2, or 3.`);
+    }
+    if (tier !== component.tier) {
+        throw new GenuiError(`[genui] component '${component.name}': ${where} declares tier ${tier} but ` +
+            `dharta.toml declares tier ${component.tier}. The manifest is the trust declaration; ` +
+            "make them agree.");
+    }
+    if (parsed.builtin !== undefined && typeof parsed.builtin !== "string") {
+        throw new GenuiError(`[genui] component '${component.name}': ${where} builtin must be a string.`);
+    }
+    for (const key of ["props_schema", "events"]) {
+        if (parsed[key] !== undefined && !plainObject(parsed[key])) {
+            throw new GenuiError(`[genui] component '${component.name}': ${where} ${key} must be an object.`);
+        }
+    }
+    const spec = {
+        builtin: parsed.builtin,
+        props_schema: parsed.props_schema,
+        events: parsed.events,
+    };
+    const out = { name: component.name, tier: component.tier };
+    if (spec.props_schema !== undefined)
+        out.props_schema = spec.props_schema;
+    if (spec.events !== undefined)
+        out.events = spec.events;
+    out.implementation = await readImplementation(dir, label, component, spec);
+    return out;
+}
+async function readImplementation(dir, label, component, spec) {
+    if (component.tier === 1) {
+        // A Tier-1 component is an alias for a Dharta builtin; the common case is
+        // that the folder is named after the builtin it aliases.
+        return { builtin: spec.builtin ?? component.name };
+    }
+    if (spec.builtin !== undefined) {
+        throw new GenuiError(`[genui] component '${component.name}': builtin is Tier-1 only; ` +
+            `a Tier-${component.tier} component ships its own source.`);
+    }
+    const file = component.tier === 2 ? TIER2_SOURCE_FILE : TIER3_SOURCE_FILE;
+    const field = component.tier === 2 ? "worker" : "html";
+    const where = `${label}/${component.name}/${file}`;
+    let bytes;
+    try {
+        bytes = await fs.readFile(path.join(dir, file));
+    }
+    catch {
+        throw new GenuiError(`[genui] component '${component.name}' is tier ${component.tier}, so it needs ${where}.`);
+    }
+    // The bundle is UTF-8 JSON. Decoding leniently would replace an invalid byte
+    // with U+FFFD and ship a silently corrupted worker or document.
+    return {
+        [field]: decodeUtf8(bytes, `[genui] component '${component.name}': ${where} is not valid UTF-8.`),
+    };
+}
+//# sourceMappingURL=genui.js.map