@texuli/tools 0.0.0-stage → 0.1.0-next.0

package/dist/cli-update/update.js

@@ -0,0 +1,261 @@
+/**
+ * `texuli diff` and `texuli update`: three-way merge of a copied component
+ * (the consumer's files) against the source it was copied from (the base,
+ * at the installed version) and the new source. Local filesystem only.
+ * Reads and writes use the same containment as `texuli add`.
+ */
+import { existsSync, lstatSync } from 'node:fs';
+import { mkdir, readdir, readFile, realpath, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { hasProvenance, provenanceHeader, provenanceSource } from "../cli-add/provenance.js";
+import { getAddable, isPrimitivesPath, listAddableIds } from "../cli-add/registry.js";
+import { assertNoSymlinkOnPath, assertSourceFileInside, resolveContainedOutDir, resolveContainedSourceDir, validateRegistryEntry, } from "../internal/paths.js";
+import { merge3, unifiedDiff } from "./lines.js";
+import { parseProvenance } from "./provenance.js";
+const DEFAULT_VERSION = '0.0.0';
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git']);
+async function walk(dir, root = dir) {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name))
+                out.push(...(await walk(full, root)));
+        }
+        else if (entry.isFile()) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+const toRel = (root, full) => relative(root, full).split(sep).join('/');
+/** Read one component's source tree, contained like `texuli add`. */
+async function readSource(root, entry, label) {
+    if (!existsSync(root))
+        return `${label} does not exist: ${root}`;
+    if (isPrimitivesPath(root))
+        return `${label} must not be the primitives package.`;
+    const resolved = resolveContainedSourceDir(root, entry);
+    if (!resolved.ok)
+        return resolved.error;
+    const dir = resolved.sourceDir;
+    if (isPrimitivesPath(dir))
+        return `Refusing to read primitives source for "${entry.id}".`;
+    const files = new Map();
+    if (!existsSync(dir))
+        return { dir, relDir: '', files };
+    for (const file of await walk(dir)) {
+        const inside = assertSourceFileInside(dir, file);
+        if (!inside.ok)
+            return inside.error;
+        files.set(toRel(dir, file), await readFile(inside.realFile, 'utf8'));
+    }
+    // Relative to the real root, so a symlinked root never stamps a parent path.
+    const relDir = toRel(await realpath(root), await realpath(dir));
+    for (const path of files.keys()) {
+        if (provenanceSource(relDir, path) === null) {
+            return `Provenance source would not be a plain relative path: ${relDir}/${path}`;
+        }
+    }
+    return { dir, relDir, files };
+}
+/**
+ * Plan (and with `apply`, perform) an update. `diff` is this with
+ * `apply: false`.
+ */
+async function run(options, apply) {
+    const id = options.id.trim().toLowerCase();
+    const version = options.version ?? DEFAULT_VERSION;
+    const dryRun = !apply || Boolean(options.dryRun);
+    const mode = options.conflicts ?? 'refuse';
+    const result = {
+        ok: false,
+        id,
+        package: '',
+        outDir: resolve(options.cwd),
+        installedVersion: null,
+        version,
+        files: [],
+        conflicts: 0,
+        errors: [],
+        dryRun,
+    };
+    const fail = (error) => ({ ...result, errors: [...result.errors, error] });
+    if (!id)
+        return fail('Component id is required.');
+    const entry = getAddable(id, options.registry);
+    if (!entry) {
+        return fail(`Unknown or non-addable component "${id}". Known: ${listAddableIds(options.registry).join(', ') || '(none)'}.`);
+    }
+    const entryCheck = validateRegistryEntry(entry);
+    if (!entryCheck.ok)
+        return fail(entryCheck.error);
+    if (entry.package === '@texuli/primitives' || entry.package === 'primitives') {
+        return fail(`Refusing to update primitives package component "${id}".`);
+    }
+    result.package = entry.package;
+    const out = resolveContainedOutDir(options.cwd, options.outDir ?? join('src', 'components', 'texuli', id));
+    if (!out.ok)
+        return fail(out.error);
+    const outDir = out.outDir;
+    result.outDir = outDir;
+    const cwdReal = existsSync(options.cwd) ? await realpath(options.cwd) : resolve(options.cwd);
+    const upstream = await readSource(options.sourceRoot, entry, 'Source root');
+    if (typeof upstream === 'string')
+        return fail(upstream);
+    if (upstream.files.size === 0)
+        return fail(`No files found under ${upstream.dir}`);
+    let base = null;
+    if (options.baseRoot !== undefined) {
+        const read = await readSource(options.baseRoot, entry, 'Base root');
+        if (typeof read === 'string')
+            return fail(read);
+        base = read;
+    }
+    // Local files: never through a symlink; tracked ones carry this component's header.
+    const local = new Map();
+    if (existsSync(outDir)) {
+        const link = assertNoSymlinkOnPath(outDir, cwdReal);
+        if (!link.ok)
+            return fail(link.error);
+        for (const full of await walk(outDir)) {
+            if (lstatSync(full).isSymbolicLink())
+                return fail(`Refusing symlink in component: ${full}`);
+            const content = await readFile(full, 'utf8');
+            const parsed = parseProvenance(content);
+            const tracked = parsed !== null && parsed.meta.id === entry.id;
+            local.set(toRel(outDir, full), {
+                full: content,
+                body: tracked ? parsed.body : content,
+                version: tracked ? parsed.meta.version : '',
+                tracked,
+            });
+        }
+    }
+    const versions = new Set([...local.values()].filter((f) => f.tracked).map((f) => f.version));
+    if (versions.size > 1) {
+        return fail(`Local files carry different versions (${[...versions].sort().join(', ')}).`);
+    }
+    result.installedVersion = versions.size === 1 ? [...versions][0] : null;
+    if (options.baseVersion !== undefined &&
+        result.installedVersion !== null &&
+        result.installedVersion !== options.baseVersion) {
+        return fail(`Installed version is ${result.installedVersion}, but the base root is ${options.baseVersion}.`);
+    }
+    const labels = {
+        local: 'local',
+        base: `base ${result.installedVersion ?? '(unknown)'}`,
+        upstream: `${entry.package} ${version}`,
+    };
+    const stamp = (path, body) => {
+        if (hasProvenance(body))
+            return body;
+        const meta = {
+            id: entry.id,
+            package: entry.package,
+            version,
+            // Checked in readSource for every upstream path.
+            source: provenanceSource(upstream.relDir, path) ?? '',
+        };
+        return provenanceHeader(meta, path) + body;
+    };
+    const paths = new Set([
+        ...upstream.files.keys(),
+        ...(base ? base.files.keys() : []),
+        ...local.keys(),
+    ]);
+    const planned = [];
+    const plan = (path, status, content, conflicts = 0) => {
+        const to = resolve(outDir, path);
+        const before = local.get(path)?.full ?? '';
+        let action = 'none';
+        if (content === null && status === 'removed' && options.prune)
+            action = 'delete';
+        else if (content !== null && content !== before)
+            action = 'write';
+        if (dryRun && action !== 'none')
+            action = action === 'write' ? 'would-write' : 'would-delete';
+        const after = action === 'delete' || action === 'would-delete' ? '' : (content ?? before);
+        const diff = unifiedDiff(before, after, { from: `a/${path}`, to: `b/${path}` });
+        planned.push({ path, status, action, diff, conflicts, to, content });
+    };
+    for (const path of [...paths].sort()) {
+        const mine = local.get(path);
+        const theirs = upstream.files.get(path);
+        const origin = base?.files.get(path);
+        if (mine && !mine.tracked) {
+            plan(path, 'untracked', null);
+        }
+        else if (theirs !== undefined && !mine) {
+            if (origin !== undefined && result.installedVersion !== null)
+                plan(path, 'deleted-locally', null);
+            else
+                plan(path, 'added', stamp(path, theirs));
+        }
+        else if (theirs !== undefined && mine) {
+            if (mine.body === theirs)
+                plan(path, 'unchanged', stamp(path, theirs));
+            else if (!base)
+                plan(path, 'needs-base', null);
+            else if (origin === mine.body)
+                plan(path, 'fast-forward', stamp(path, theirs));
+            else if (origin === theirs)
+                plan(path, 'kept-local', stamp(path, mine.body));
+            else {
+                const merged = merge3(origin ?? '', mine.body, theirs, labels);
+                plan(path, merged.conflicts > 0 ? 'conflict' : 'merged', stamp(path, merged.text), merged.conflicts);
+            }
+        }
+        else if (mine) {
+            const untouched = base !== null && origin === mine.body;
+            plan(path, untouched ? 'removed' : 'removed-modified', null);
+        }
+    }
+    result.files = planned.map(({ to: _to, content: _content, ...file }) => file);
+    result.conflicts = planned.reduce((sum, file) => sum + file.conflicts, 0);
+    const blocked = planned.filter((f) => f.status === 'needs-base').map((f) => f.path);
+    if (apply && blocked.length > 0) {
+        result.errors.push(`Local edits cannot be merged without the installed source (--base-root): ${blocked.join(', ')}`);
+    }
+    if (apply && result.conflicts > 0 && mode === 'refuse') {
+        result.errors.push(`${result.conflicts} conflict(s); nothing was written. Resolve them, or pass --conflicts markers.`);
+    }
+    result.ok = result.errors.length === 0;
+    if (!result.ok || dryRun) {
+        if (!result.ok)
+            result.files = result.files.map((f) => ({ ...f, action: 'none' }));
+        return result;
+    }
+    for (const file of planned) {
+        if (file.action === 'none')
+            continue;
+        const link = assertNoSymlinkOnPath(file.to, cwdReal);
+        if (!link.ok)
+            return { ...result, ok: false, errors: [link.error] };
+        if (file.action === 'delete') {
+            await unlink(file.to);
+            continue;
+        }
+        await mkdir(dirname(file.to), { recursive: true });
+        const after = assertNoSymlinkOnPath(file.to, cwdReal);
+        if (!after.ok)
+            return { ...result, ok: false, errors: [after.error] };
+        await writeFile(file.to, file.content ?? '', 'utf8');
+    }
+    return result;
+}
+/**
+ * Show what `texuli update` would do: each file's status and a unified diff
+ * from the local file to its result. Writes nothing.
+ */
+export function diffComponent(options) {
+    return run(options, false);
+}
+/**
+ * Update a copied component to the new source with a three-way merge.
+ * Writes nothing when any file conflicts (unless `conflicts: 'markers'`) or
+ * needs a base that was not given.
+ */
+export function updateComponent(options) {
+    return run(options, true);
+}

package/dist/elements/content.d.ts

@@ -0,0 +1,15 @@
+import { type RenderCatalog, type RenderComponentSpec } from '@texuli/catalog/render/renderer';
+import type { Component } from 'svelte';
+/**
+ * The content preset (T-tool-elements): one lazy loader per catalog content
+ * component (blocks, charts, media), and the render catalog of their
+ * manifests. Each loader is its own dynamic import, so a page pays only for
+ * the components its trees use.
+ */
+export type ElementComponent = Component<any>;
+export type ElementComponentLoader = () => Promise<ElementComponent>;
+export declare const CONTENT_ELEMENT_LOADERS: Readonly<Record<string, ElementComponentLoader>>;
+/** Render specs of the content manifests (labels, prop schemas, emit tiers). */
+export declare function contentRenderSpecs(): RenderComponentSpec[];
+/** The render catalog the content elements validate trees against. */
+export declare function contentRenderCatalog(): RenderCatalog;

package/dist/elements/content.js

@@ -0,0 +1,53 @@
+import { CONTENT_MANIFESTS } from '@texuli/catalog/manifests/content';
+import { renderCatalogFromSpecs, } from '@texuli/catalog/render/renderer';
+export const CONTENT_ELEMENT_LOADERS = Object.freeze({
+    'blocks-text': async () => (await (await import('@texuli/blocks/text')).loadTextFamily()).default,
+    'blocks-data': async () => (await (await import('@texuli/blocks/data')).loadDataFamily()).default,
+    'blocks-diagram': async () => (await (await import('@texuli/blocks/diagram')).loadDiagramFamily()).default,
+    'blocks-media': async () => (await (await import('@texuli/blocks/media')).loadMediaFamily()).default,
+    'blocks-embed': async () => (await (await import('@texuli/blocks/embed')).loadEmbedFamily()).default,
+    'blocks-structure': async () => (await (await import('@texuli/blocks/structure')).loadStructureFamily()).default,
+    'blocks-code': async () => (await (await import('@texuli/blocks/code')).loadCodeFamily()).default,
+    'blocks-interactive': async () => (await (await import('@texuli/blocks/interactive')).loadInteractiveFamily()).default,
+    'blocks-map': async () => (await (await import('@texuli/blocks/map')).loadMapFamily()).default,
+    'charts-area': async () => (await import('@texuli/charts/cartesian')).AreaChart,
+    'charts-bar': async () => (await import('@texuli/charts/cartesian')).BarChart,
+    'charts-cartesian': async () => (await import('@texuli/charts/cartesian')).CartesianChart,
+    'charts-combo': async () => (await import('@texuli/charts/cartesian')).ComboChart,
+    'charts-line': async () => (await import('@texuli/charts/cartesian')).LineChart,
+    'charts-stacked-bar': async () => (await import('@texuli/charts/cartesian')).StackedBarChart,
+    'charts-bullet': async () => (await import('@texuli/charts/compact')).BulletChart,
+    'charts-gauge': async () => (await import('@texuli/charts/compact')).Gauge,
+    'charts-progress-ring': async () => (await import('@texuli/charts/compact')).ProgressRing,
+    'charts-sparkline': async () => (await import('@texuli/charts/compact')).Sparkline,
+    'charts-canvas-renderer': async () => (await import('@texuli/charts/canvas')).CanvasRenderer,
+    'charts-funnel': async () => (await import('@texuli/charts/flow')).FunnelChart,
+    'charts-network': async () => (await import('@texuli/charts/flow')).NetworkGraph,
+    'charts-sankey': async () => (await import('@texuli/charts/flow')).SankeyChart,
+    'charts-geo-map': async () => (await import('@texuli/charts/geo')).GeoMap,
+    'charts-geo-point-map': async () => (await import('@texuli/charts/geo')).GeoPointMap,
+    'charts-bubble': async () => (await import('@texuli/charts/matrix')).BubbleChart,
+    'charts-heatmap': async () => (await import('@texuli/charts/matrix')).HeatmapChart,
+    'charts-scatter': async () => (await import('@texuli/charts/matrix')).ScatterChart,
+    'charts-donut': async () => (await import('@texuli/charts/part-whole')).DonutChart,
+    'charts-pie': async () => (await import('@texuli/charts/part-whole')).PieChart,
+    'charts-sunburst': async () => (await import('@texuli/charts/part-whole')).SunburstChart,
+    'charts-treemap': async () => (await import('@texuli/charts/part-whole')).TreemapChart,
+    'media-image': async () => (await import('@texuli/media/image')).Image,
+    'media-composition-svg': async () => (await import('@texuli/media/composition-svg')).CompositionSvg,
+    'media-composition-canvas': async () => (await import('@texuli/media/composition-canvas')).CompositionCanvas,
+});
+/** Render specs of the content manifests (labels, prop schemas, emit tiers). */
+export function contentRenderSpecs() {
+    return CONTENT_MANIFESTS.map((manifest) => ({
+        id: manifest.id,
+        label: manifest.label,
+        props: manifest.props,
+        agentEmittable: manifest.agentEmittable === true,
+        emit: manifest.agentEmittable === true ? ['developer', 'untrusted'] : ['developer'],
+    }));
+}
+/** The render catalog the content elements validate trees against. */
+export function contentRenderCatalog() {
+    return renderCatalogFromSpecs(contentRenderSpecs());
+}

package/dist/elements/define.d.ts

@@ -0,0 +1,49 @@
+import { type RenderCatalog, type RenderTier } from '@texuli/catalog/render/renderer';
+import { type ElementComponentLoader } from './content.js';
+/**
+ * `@texuli/tools/elements` (T-tool-elements): light-DOM custom elements so a
+ * non-Svelte host (plain HTML, React, Vue, a server template) can render
+ * catalog trees with the real Texuli content components.
+ *
+ * - `<tx-catalog>` takes an untrusted catalog tree (the `tree` property, a
+ *   `tree` JSON attribute, or a child `<script type="application/json">`),
+ *   checks it against the tree limits and the sink-free renderer, and builds
+ *   one `<tx-{id}>` element per component, or a labelled placeholder.
+ * - `<tx-{id}>` (one per content component) mounts the Svelte component in
+ *   its own light DOM, so page styles and the Texuli CSS layers apply.
+ *
+ * Nothing here writes markup from data: elements are created with
+ * `createElement`, text with `textContent`, and every props bag passes the
+ * catalog renderer (unknown ids, forbidden props and HTML strings never
+ * reach a component). The render tier is fixed when the elements are
+ * defined; markup cannot raise it.
+ */
+export declare const ELEMENT_ID_PATTERN: RegExp;
+export interface DefineElementsOptions {
+    /** id → lazy Svelte component. Default: the content preset. */
+    loaders?: Readonly<Record<string, ElementComponentLoader>>;
+    /** Render catalog the trees and props are checked against. Default: content manifests. */
+    catalog?: RenderCatalog;
+    /** Who authors the trees. Default `untrusted` (agent content). */
+    tier?: RenderTier;
+    /** Tag prefix: `tx` gives `<tx-catalog>` and `<tx-blocks-text>`. */
+    prefix?: string;
+    /** Registry to define into (a window's `customElements`). */
+    registry?: CustomElementRegistry;
+    /** The window whose `HTMLElement` the classes extend. */
+    window?: Window & typeof globalThis;
+}
+export interface DefinedElements {
+    catalogTag: string;
+    /** id → tag of every component element. */
+    componentTags: Readonly<Record<string, string>>;
+}
+/** The custom element tag for a catalog id, or `null` for an invalid id. */
+export declare function elementTagFor(id: string, prefix?: string): string | null;
+/** Parses a JSON attribute or script body; anything invalid is `undefined`. */
+export declare function parseJsonData(text: string | null | undefined): unknown;
+/**
+ * Defines `<{prefix}-catalog>` and one `<{prefix}-{id}>` per loader. Safe to
+ * call again: tags already defined are kept as they are.
+ */
+export declare function defineTexuliElements(options?: DefineElementsOptions): DefinedElements;

package/dist/elements/define.js

@@ -0,0 +1,281 @@
+import { renderCatalogTreeWithLimits } from '@texuli/catalog/render/limits';
+import { renderCatalogTree, } from '@texuli/catalog/render/renderer';
+import { mount, unmount } from 'svelte';
+import { CONTENT_ELEMENT_LOADERS, contentRenderCatalog, } from "./content.js";
+/**
+ * `@texuli/tools/elements` (T-tool-elements): light-DOM custom elements so a
+ * non-Svelte host (plain HTML, React, Vue, a server template) can render
+ * catalog trees with the real Texuli content components.
+ *
+ * - `<tx-catalog>` takes an untrusted catalog tree (the `tree` property, a
+ *   `tree` JSON attribute, or a child `<script type="application/json">`),
+ *   checks it against the tree limits and the sink-free renderer, and builds
+ *   one `<tx-{id}>` element per component, or a labelled placeholder.
+ * - `<tx-{id}>` (one per content component) mounts the Svelte component in
+ *   its own light DOM, so page styles and the Texuli CSS layers apply.
+ *
+ * Nothing here writes markup from data: elements are created with
+ * `createElement`, text with `textContent`, and every props bag passes the
+ * catalog renderer (unknown ids, forbidden props and HTML strings never
+ * reach a component). The render tier is fixed when the elements are
+ * defined; markup cannot raise it.
+ */
+export const ELEMENT_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const PREFIX_PATTERN = /^[a-z][a-z0-9]*$/;
+/** The custom element tag for a catalog id, or `null` for an invalid id. */
+export function elementTagFor(id, prefix = 'tx') {
+    if (!PREFIX_PATTERN.test(prefix) || !ELEMENT_ID_PATTERN.test(id))
+        return null;
+    return `${prefix}-${id}`;
+}
+/** Parses a JSON attribute or script body; anything invalid is `undefined`. */
+export function parseJsonData(text) {
+    if (typeof text !== 'string' || text.trim() === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function placeholder(doc, label, reason) {
+    const note = doc.createElement('p');
+    note.className = 'tx-element-placeholder';
+    note.setAttribute('role', 'note');
+    note.dataset.reason = reason;
+    note.textContent = label;
+    return note;
+}
+/**
+ * Defines `<{prefix}-catalog>` and one `<{prefix}-{id}>` per loader. Safe to
+ * call again: tags already defined are kept as they are.
+ */
+export function defineTexuliElements(options = {}) {
+    const win = options.window ?? globalThis;
+    const registry = options.registry ?? win.customElements;
+    const prefix = options.prefix ?? 'tx';
+    if (!PREFIX_PATTERN.test(prefix))
+        throw new TypeError(`Invalid element prefix: ${prefix}`);
+    if (!registry || typeof win.HTMLElement !== 'function') {
+        throw new TypeError('Custom elements are not available in this environment.');
+    }
+    const loaders = options.loaders ?? CONTENT_ELEMENT_LOADERS;
+    const catalog = options.catalog ?? contentRenderCatalog();
+    const tier = options.tier === 'developer' ? 'developer' : 'untrusted';
+    const componentTags = {};
+    for (const id of Object.keys(loaders)) {
+        const tag = elementTagFor(id, prefix);
+        if (!tag)
+            continue;
+        componentTags[id] = tag;
+    }
+    const cache = new Map();
+    const load = (id) => {
+        let pending = cache.get(id);
+        if (!pending) {
+            const loader = loaders[id];
+            pending = loader ? loader() : Promise.reject(new Error(`No loader for ${id}`));
+            // A failed load may be retried on the next render.
+            pending.catch(() => cache.delete(id));
+            cache.set(id, pending);
+        }
+        return pending;
+    };
+    class ComponentElement extends win.HTMLElement {
+        static observedAttributes = ['props'];
+        /** The catalog id; set by the subclass per tag. */
+        static componentId = '';
+        #props = undefined;
+        #instance;
+        #renderToken = 0;
+        #diagnostics = [];
+        get componentId() {
+            return this.constructor.componentId;
+        }
+        /** The component's props: plain data, validated against its manifest. */
+        get props() {
+            return this.#props;
+        }
+        set props(value) {
+            this.#props = value;
+            if (this.isConnected)
+                void this.#render();
+        }
+        /** Why the last props were refused or changed (empty when they were fine). */
+        get diagnostics() {
+            return this.#diagnostics;
+        }
+        attributeChangedCallback(name, _old, value) {
+            if (name === 'props')
+                this.props = parseJsonData(value);
+        }
+        connectedCallback() {
+            void this.#render();
+        }
+        disconnectedCallback() {
+            this.#renderToken += 1;
+            this.#teardown();
+        }
+        #teardown() {
+            if (this.#instance) {
+                void unmount(this.#instance);
+                this.#instance = undefined;
+            }
+        }
+        async #render() {
+            const token = ++this.#renderToken;
+            const id = this.componentId;
+            const result = renderCatalogTree({ id, props: this.#props ?? {} }, { catalog, tier });
+            this.#diagnostics = result.diagnostics;
+            const node = result.roots[0];
+            this.#teardown();
+            if (node?.kind !== 'component') {
+                const reason = node?.kind === 'placeholder' ? node.reason : 'invalid-props';
+                const label = node?.kind === 'placeholder' ? node.label : (catalog.get(id)?.label ?? id);
+                this.dataset.state = 'invalid';
+                this.replaceChildren(placeholder(this.ownerDocument, label, reason));
+                this.dispatchEvent(new CustomEvent('tx-invalid', { detail: result.diagnostics }));
+                return;
+            }
+            this.dataset.state = 'loading';
+            this.setAttribute('aria-busy', 'true');
+            let Component;
+            try {
+                Component = await load(id);
+            }
+            catch {
+                if (token !== this.#renderToken)
+                    return;
+                this.removeAttribute('aria-busy');
+                this.dataset.state = 'error';
+                this.replaceChildren(placeholder(this.ownerDocument, catalog.get(id)?.label ?? id, 'load-error'));
+                return;
+            }
+            if (token !== this.#renderToken || !this.isConnected)
+                return;
+            const target = this.ownerDocument.createElement('div');
+            target.dataset.txElementRoot = '';
+            this.replaceChildren(target);
+            const props = { ...node.props };
+            // Validation callbacks become DOM events: trees carry data, never functions.
+            if (catalog.get(id)?.props.some((prop) => prop.name === 'oninvalid')) {
+                props.oninvalid = (issues) => this.dispatchEvent(new CustomEvent('tx-invalid', { detail: issues }));
+            }
+            try {
+                this.#instance = mount(Component, { target, props });
+            }
+            catch (error) {
+                // A component that refuses its props (a chart with an invalid series)
+                // must not break the page: show its placeholder and report why.
+                this.removeAttribute('aria-busy');
+                this.dataset.state = 'invalid';
+                this.replaceChildren(placeholder(this.ownerDocument, catalog.get(id)?.label ?? id, 'render-error'));
+                this.dispatchEvent(new CustomEvent('tx-invalid', {
+                    detail: [
+                        {
+                            code: 'render-error',
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    ],
+                }));
+                return;
+            }
+            this.removeAttribute('aria-busy');
+            this.dataset.state = 'ready';
+            this.dispatchEvent(new CustomEvent('tx-ready'));
+        }
+    }
+    class CatalogElement extends win.HTMLElement {
+        static observedAttributes = ['tree'];
+        #tree = undefined;
+        #diagnostics = [];
+        /** The catalog tree (one node or a list of nodes): untrusted data. */
+        get tree() {
+            return this.#tree;
+        }
+        set tree(value) {
+            this.#tree = value;
+            if (this.isConnected)
+                this.#render();
+        }
+        /** Why nodes were dropped, replaced or refused in the last render. */
+        get diagnostics() {
+            return this.#diagnostics;
+        }
+        attributeChangedCallback(name, _old, value) {
+            if (name === 'tree')
+                this.tree = parseJsonData(value);
+        }
+        connectedCallback() {
+            if (this.#tree === undefined) {
+                const script = this.querySelector(':scope > script[type="application/json"]');
+                if (script)
+                    this.#tree = parseJsonData(script.textContent);
+            }
+            this.#render();
+        }
+        #render() {
+            const doc = this.ownerDocument;
+            const input = this.#tree;
+            const nodes = Array.isArray(input)
+                ? input
+                : input === undefined
+                    ? []
+                    : [input];
+            const roots = [];
+            const diagnostics = [];
+            let limited = false;
+            nodes.forEach((node, index) => {
+                const result = renderCatalogTreeWithLimits(node, {
+                    catalog,
+                    tier,
+                    enforceRenderTime: false,
+                });
+                if (!result.withinLimits)
+                    limited = true;
+                roots.push(...result.roots);
+                diagnostics.push(...result.diagnostics.map((d) => ({ ...d, path: `${index}.${d.path}` })));
+            });
+            this.#diagnostics = diagnostics;
+            const fragment = doc.createDocumentFragment();
+            for (const node of roots)
+                fragment.append(this.#build(node));
+            this.replaceChildren(fragment);
+            this.dataset.state = limited ? 'over-limits' : 'ready';
+            this.dispatchEvent(new CustomEvent('tx-render', { detail: { diagnostics, rendered: roots.length } }));
+        }
+        #build(node) {
+            const doc = this.ownerDocument;
+            if (node.kind === 'placeholder')
+                return placeholder(doc, node.label, node.reason);
+            const tag = componentTags[node.id];
+            if (!tag)
+                return placeholder(doc, catalog.get(node.id)?.label ?? node.id, 'no-element');
+            const element = doc.createElement(tag);
+            element.props = node.props;
+            if (node.children.length === 0)
+                return element;
+            // Content components take no DOM children; nested nodes follow in order.
+            const group = doc.createElement('div');
+            group.dataset.txElementGroup = node.id;
+            const children = doc.createElement('div');
+            children.dataset.txElementChildren = '';
+            for (const child of node.children)
+                children.append(this.#build(child));
+            group.append(element, children);
+            return group;
+        }
+    }
+    const catalogTag = `${prefix}-catalog`;
+    if (!registry.get(catalogTag))
+        registry.define(catalogTag, CatalogElement);
+    for (const [id, tag] of Object.entries(componentTags)) {
+        if (registry.get(tag))
+            continue;
+        registry.define(tag, class extends ComponentElement {
+            static componentId = id;
+        });
+    }
+    return { catalogTag, componentTags: Object.freeze({ ...componentTags }) };
+}

package/dist/elements/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@texuli/tools/elements` — light-DOM custom elements for the catalog
+ * content components (T-tool-elements). See `docs/elements.md`.
+ */
+export { CONTENT_ELEMENT_LOADERS, contentRenderCatalog, contentRenderSpecs, type ElementComponent, type ElementComponentLoader, } from './content.js';
+export { type DefinedElements, type DefineElementsOptions, defineTexuliElements, ELEMENT_ID_PATTERN, elementTagFor, parseJsonData, } from './define.js';

package/dist/elements/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@texuli/tools/elements` — light-DOM custom elements for the catalog
+ * content components (T-tool-elements). See `docs/elements.md`.
+ */
+export { CONTENT_ELEMENT_LOADERS, contentRenderCatalog, contentRenderSpecs, } from "./content.js";
+export { defineTexuliElements, ELEMENT_ID_PATTERN, elementTagFor, parseJsonData, } from "./define.js";