@box-kite/react 2.0.0 → 2.1.0

package/spec.mjs

@@ -0,0 +1,382 @@
+"use client";
+import { n as e } from "./effects.mjs";
+import { t } from "./specSchema.mjs";
+import { t as n } from "./specData.mjs";
+import { Component as r, Fragment as i, createElement as a, useEffect as o, useRef as s, useState as c } from "react";
+import { jsx as l } from "react/jsx-runtime";
+//#region src/utils/spec/specValidate.ts
+var u;
+(function(e) {
+	let t = [
+		"__proto__",
+		"constructor",
+		"prototype"
+	], n = /* @__PURE__ */ new Map();
+	function r(e) {
+		if (!n.has(e)) try {
+			n.set(e, new RegExp(e));
+		} catch {
+			n.set(e, null);
+		}
+		return n.get(e) ?? null;
+	}
+	function i(e) {
+		return !t.includes(e);
+	}
+	e.isSafeKey = i;
+	function a(e) {
+		return typeof e == "object" && !!e && !Array.isArray(e);
+	}
+	e.isPlainObject = a;
+	function o(e, t) {
+		if (!e.$ref) return e;
+		let n = e.$ref.startsWith("#/$defs/") ? e.$ref.slice(8) : null, r = n ? t.$defs?.[n] : void 0;
+		return r ? o(r, t) : null;
+	}
+	function s(e, t, n) {
+		return !a(t) || e.required?.some((e) => !(e in t)) ? !1 : Object.keys(t).every((r) => {
+			let a = e.properties?.[r];
+			return a ? i(r) && c(a, t[r], n) : e.additionalProperties !== !1 && i(r);
+		});
+	}
+	function c(e, t, n = e) {
+		let i = o(e, n);
+		if (!i) return !1;
+		if (i.anyOf) return i.anyOf.some((e) => c(e, t, n));
+		if (i.enum && !i.enum.includes(t)) return !1;
+		switch (i.type) {
+			case "string": return typeof t == "string" ? !i.pattern || (r(i.pattern)?.test(t) ?? !1) : !1;
+			case "number": return typeof t == "number" && Number.isFinite(t);
+			case "integer": return typeof t == "number" && Number.isInteger(t);
+			case "boolean": return typeof t == "boolean";
+			case "array": return Array.isArray(t) && (!i.items || t.every((e) => c(i.items, e, n)));
+			case "object": return s(i, t, n);
+			default: return t !== void 0;
+		}
+	}
+	e.matches = c;
+})(u ||= {});
+var d = u, f;
+(function(e) {
+	function t(e) {
+		let t = JSON.stringify(e) ?? "undefined";
+		return t.length > 40 ? `${t.slice(0, 39)}…` : t;
+	}
+	function r(e, t) {
+		return typeof e == "string" ? { action: e } : !d.isPlainObject(e) || typeof e.action != "string" ? null : {
+			action: e.action,
+			payload: n.deep(e.payload, t)
+		};
+	}
+	function i(e, i, a, o) {
+		let s = typeof e.type == "string" ? e.type : void 0, c = [], l = {}, u = {}, f = i.props, p = f?.properties;
+		if (d.isPlainObject(e.props)) for (let [r, i] of Object.entries(e.props)) {
+			let e = `${o}.props.${r}`;
+			if (!d.isSafeKey(r)) {
+				c.push({
+					code: "unknown-prop",
+					path: e,
+					component: s,
+					prop: r,
+					message: `${r} is not a prop a spec can set.`
+				});
+				continue;
+			}
+			let u = p?.[r];
+			if (!u && (!f || f.additionalProperties === !1)) {
+				c.push({
+					code: "unknown-prop",
+					path: e,
+					component: s,
+					prop: r,
+					message: `${s ?? "The component"} has no ${r} prop.`
+				});
+				continue;
+			}
+			let m = null, h = n.deep(i, a, (e) => {
+				m ??= e;
+			});
+			if (m) {
+				c.push({
+					code: "unresolved-data",
+					path: e,
+					component: s,
+					prop: r,
+					message: `${m} resolved to nothing.`
+				});
+				continue;
+			}
+			if (u && !d.matches(u, h, f)) {
+				c.push({
+					code: "invalid-prop",
+					path: e,
+					component: s,
+					prop: r,
+					message: `${t(h)} is not a value ${r} takes.`
+				});
+				continue;
+			}
+			l[r] = h;
+		}
+		if (d.isPlainObject(e.on)) for (let [t, n] of Object.entries(e.on)) {
+			let e = `${o}.on.${t}`, l = i.events.includes(t) ? r(n, a) : null;
+			if (!l) {
+				c.push({
+					code: "unknown-event",
+					path: e,
+					component: s,
+					prop: t,
+					message: `${s ?? "The component"} has no ${t} event.`
+				});
+				continue;
+			}
+			u[t] = l;
+		}
+		return {
+			props: l,
+			actions: u,
+			issues: c,
+			missing: (f?.required ?? []).filter((e) => !(e in l))
+		};
+	}
+	e.resolve = i;
+})(f ||= {});
+var p = f, m = class extends r {
+	state = {
+		message: null,
+		resetKey: this.props.resetKey
+	};
+	static getDerivedStateFromProps(e, t) {
+		return e.resetKey === t.resetKey ? null : {
+			message: null,
+			resetKey: e.resetKey
+		};
+	}
+	static getDerivedStateFromError(e) {
+		return { message: e instanceof Error ? e.message : String(e) };
+	}
+	componentDidCatch(e) {
+		this.props.onError?.(this.issue(e instanceof Error ? e.message : String(e)));
+	}
+	issue(e) {
+		return {
+			code: "render-error",
+			path: this.props.path,
+			component: this.props.component,
+			message: e
+		};
+	}
+	render() {
+		return this.state.message === null ? this.props.children : this.props.fallback(this.issue(this.state.message));
+	}
+}, h = 1e3, g = 32;
+function _(e, t) {
+	e.issues.push(t);
+}
+function v(e, t, n) {
+	_(e, t);
+	let r = e.fallback(t);
+	return n === void 0 || r == null ? r ?? null : a(i, { key: n }, r);
+}
+function y(e, t, r, i, a) {
+	if (e == null || typeof e == "boolean") return null;
+	if (typeof e == "string" || typeof e == "number") return e;
+	if (Array.isArray(e)) return e.map((e, n) => y(e, t, r, `${i}.${n}`, a));
+	if (n.isRef(e)) {
+		let a = n.resolve(e, r);
+		return a.found ? a.value === null || a.value === void 0 || typeof a.value == "boolean" ? null : typeof a.value == "string" || typeof a.value == "number" ? a.value : (_(t, {
+			code: "invalid-child",
+			path: i,
+			message: `${n.pathOf(e)} is not text.`
+		}), null) : (_(t, {
+			code: "unresolved-data",
+			path: i,
+			message: `${n.pathOf(e)} resolved to nothing.`
+		}), null);
+	}
+	return d.isPlainObject(e) ? "type" in e ? typeof e.type == "string" ? e.type === "" ? null : x(e, t, r, i, a, e.type) : (_(t, {
+		code: "invalid-child",
+		path: i,
+		message: "A node names its component in `type`."
+	}), null) : null : (_(t, {
+		code: "invalid-child",
+		path: i,
+		message: "A child is a node, text, or a reference to text."
+	}), null);
+}
+function b(e, t, r, i, a, o) {
+	let s = e.repeat;
+	if (!n.isRef(s)) return v(t, {
+		code: "invalid-repeat",
+		path: `${i}.repeat`,
+		component: o,
+		message: "A repeat is a reference to an array."
+	});
+	let c = n.resolve(s, r);
+	if (!c.found) return _(t, {
+		code: "unresolved-data",
+		path: `${i}.repeat`,
+		component: o,
+		message: `${n.pathOf(s)} resolved to nothing.`
+	}), null;
+	if (!Array.isArray(c.value)) return v(t, {
+		code: "invalid-repeat",
+		path: `${i}.repeat`,
+		component: o,
+		message: `${n.pathOf(s)} is not an array.`
+	});
+	let l = typeof e.key == "string" ? e.key : i;
+	return c.value.map((n, s) => S(e, t, {
+		data: r.data,
+		item: n,
+		index: s,
+		repeating: !0
+	}, i, a, o, `${l}#${s}`));
+}
+function x(e, t, n, r, i, a) {
+	return i > t.maxDepth ? v(t, {
+		code: "too-deep",
+		path: r,
+		component: a,
+		message: `Nested deeper than the ${t.maxDepth} levels allowed.`
+	}) : e.repeat === void 0 ? S(e, t, n, r, i, a, typeof e.key == "string" ? e.key : r) : b(e, t, n, r, i, a);
+}
+function S(e, t, n, r, i, o, s) {
+	if (t.nodes += 1, t.nodes > t.maxNodes) return t.overflowed || (t.overflowed = !0, _(t, {
+		code: "too-many-nodes",
+		path: r,
+		component: o,
+		message: `More than the ${t.maxNodes} nodes allowed.`
+	})), null;
+	let c = t.registry.get(o);
+	if (!c) return v(t, {
+		code: "unknown-component",
+		path: r,
+		component: o,
+		message: `${o} is not a component this app allows.`
+	}, s);
+	let u = p.resolve(e, c, n, r), f = { ...u.props };
+	t.issues.push(...u.issues);
+	let h = t.memory?.get(`${r}:${o}`);
+	if (u.missing.length) {
+		if (!(h && u.missing.every((e) => e in h))) {
+			let e = u.missing.join(", ");
+			return v(t, {
+				code: "missing-prop",
+				path: r,
+				component: o,
+				prop: u.missing[0],
+				message: `${o} cannot render without ${e}.`
+			}, s);
+		}
+		for (let e of u.missing) f[e] = h[e];
+	}
+	if (t.memory) {
+		let e = c.props?.required ?? [];
+		e.length && t.memory.set(`${r}:${o}`, Object.fromEntries(e.map((e) => [e, f[e]])));
+	}
+	for (let [e, n] of Object.entries(u.actions)) f[e] = (...i) => t.onAction?.(n.action, {
+		payload: n.payload,
+		args: i,
+		prop: e,
+		component: o,
+		path: r
+	});
+	if (e.children !== void 0 && (c.slots.includes("default") ? f.children = y(e.children, t, n, `${r}.children`, i + 1) : _(t, {
+		code: "unknown-slot",
+		path: `${r}.children`,
+		component: o,
+		message: `${o} takes no children.`
+	})), d.isPlainObject(e.slots)) for (let [a, s] of Object.entries(e.slots)) {
+		let e = `${r}.slots.${a}`;
+		if (!d.isSafeKey(a) || !c.slots.includes(a)) {
+			_(t, {
+				code: "unknown-slot",
+				path: e,
+				component: o,
+				message: `${o} has no ${a} slot.`
+			});
+			continue;
+		}
+		f[a === "default" ? "children" : a] = y(s, t, n, e, i + 1);
+	}
+	return /* @__PURE__ */ l(m, {
+		path: r,
+		component: o,
+		resetKey: t.resetKey,
+		fallback: t.fallback,
+		onError: t.onError,
+		children: a(c.component, f)
+	}, s);
+}
+function C(e, t) {
+	let n = {
+		registry: t.registry,
+		data: t.data,
+		onAction: t.onAction,
+		onError: t.onError,
+		fallback: t.fallback ?? (() => null),
+		maxNodes: t.maxNodes ?? h,
+		maxDepth: t.maxDepth ?? g,
+		resetKey: t.resetKey,
+		memory: t.memory,
+		issues: [],
+		nodes: 0,
+		overflowed: !1
+	};
+	return {
+		element: y(e, n, { data: t.data }, "spec", 0),
+		issues: n.issues
+	};
+}
+//#endregion
+//#region src/react/spec/specRenderer.tsx
+function w(t) {
+	let n = s(t);
+	return e(() => {
+		n.current = t;
+	}), n;
+}
+function T({ spec: e, onIssues: t, ...n }) {
+	let [r] = c(() => /* @__PURE__ */ new Map()), { element: i, issues: a } = C(e, {
+		...n,
+		memory: r,
+		resetKey: e,
+		onError: (e) => t?.([e])
+	}), s = w(t), l = w(a), u = a.map((e) => `${e.code} ${e.path} ${e.message}`).join("\n");
+	return o(() => {
+		s.current?.(l.current);
+	}, [
+		u,
+		l,
+		s
+	]), i;
+}
+//#endregion
+//#region src/react/spec/specRegistry.ts
+function E(e) {
+	return typeof e == "object" && !!e && "component" in e;
+}
+function D(e, t, n) {
+	let r = E(t) ? t : { component: t }, i = n?.components[e];
+	return {
+		component: r.component,
+		props: r.props ?? i?.props,
+		slots: r.slots ?? i?.slots ?? ["default"],
+		events: r.events ?? i?.events ?? [],
+		description: r.description ?? i?.description
+	};
+}
+function O(e) {
+	let t = Object.keys(e.components), n = new Map(t.map((t) => [t, D(t, e.components[t], e.catalog)]));
+	return {
+		names: t,
+		components: Object.fromEntries([...n].map(([e, { component: t, ...n }]) => [e, n])),
+		get: (e) => n.get(e)
+	};
+}
+//#endregion
+//#region src/spec.ts
+var k = d.matches;
+//#endregion
+export { T as SpecRenderer, T as default, O as createSpecRegistry, k as matchesSchema, C as renderSpec, t as specSchema };

package/specData.cjs

@@ -0,0 +1 @@
+var e;(function(e){function t(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.keys(e);if(t.length!==1)return!1;let n=e;return t[0]===`$data`?typeof n.$data==`string`:t[0]===`$item`?typeof n.$item==`string`:t[0]===`$index`&&n.$index===!0}e.isRef=t;function n(e){return e===``||e===`.`||e===`/`?[]:e.startsWith(`/`)?e.slice(1).split(`/`):e.split(`.`)}function r(e,t){if(Array.isArray(e)){let n=/^\d+$/.test(t)?Number(t):-1;return n>=0&&n<e.length?{value:e[n],found:!0}:{value:void 0,found:!1}}return typeof e==`object`&&e&&Object.hasOwn(e,t)?{value:e[t],found:!0}:{value:void 0,found:!1}}function i(e,t){if(`$index`in e)return t.repeating?{value:t.index,found:!0}:{value:void 0,found:!1};let i=`$item`in e?e.$item:e.$data,a=`$item`in e?t.item:t.data;return`$item`in e&&!t.repeating?{value:void 0,found:!1}:n(i).reduce((e,t)=>e.found?r(e.value,t):e,{value:a,found:!0})}e.resolve=i;function a(e){return`$index`in e?`$index`:`$item`in e?`$item ${e.$item}`:`$data ${e.$data}`}e.pathOf=a;function o(e,n,r,s=0){if(!(s>16)){if(t(e)){let t=i(e,n);return t.found||r?.(a(e)),t.value}return Array.isArray(e)?e.map(e=>o(e,n,r,s+1)):typeof e==`object`&&e?Object.fromEntries(Object.entries(e).map(([e,t])=>[e,o(t,n,r,s+1)])):e}}e.deep=o})(e||={});var t=e;Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});

package/specData.mjs

@@ -0,0 +1,69 @@
+//#region src/utils/spec/specData.ts
+var e;
+(function(e) {
+	function t(e) {
+		if (typeof e != "object" || !e || Array.isArray(e)) return !1;
+		let t = Object.keys(e);
+		if (t.length !== 1) return !1;
+		let n = e;
+		return t[0] === "$data" ? typeof n.$data == "string" : t[0] === "$item" ? typeof n.$item == "string" : t[0] === "$index" && n.$index === !0;
+	}
+	e.isRef = t;
+	function n(e) {
+		return e === "" || e === "." || e === "/" ? [] : e.startsWith("/") ? e.slice(1).split("/") : e.split(".");
+	}
+	function r(e, t) {
+		if (Array.isArray(e)) {
+			let n = /^\d+$/.test(t) ? Number(t) : -1;
+			return n >= 0 && n < e.length ? {
+				value: e[n],
+				found: !0
+			} : {
+				value: void 0,
+				found: !1
+			};
+		}
+		return typeof e == "object" && e && Object.hasOwn(e, t) ? {
+			value: e[t],
+			found: !0
+		} : {
+			value: void 0,
+			found: !1
+		};
+	}
+	function i(e, t) {
+		if ("$index" in e) return t.repeating ? {
+			value: t.index,
+			found: !0
+		} : {
+			value: void 0,
+			found: !1
+		};
+		let i = "$item" in e ? e.$item : e.$data, a = "$item" in e ? t.item : t.data;
+		return "$item" in e && !t.repeating ? {
+			value: void 0,
+			found: !1
+		} : n(i).reduce((e, t) => e.found ? r(e.value, t) : e, {
+			value: a,
+			found: !0
+		});
+	}
+	e.resolve = i;
+	function a(e) {
+		return "$index" in e ? "$index" : "$item" in e ? `$item ${e.$item}` : `$data ${e.$data}`;
+	}
+	e.pathOf = a;
+	function o(e, n, r, s = 0) {
+		if (!(s > 16)) {
+			if (t(e)) {
+				let t = i(e, n);
+				return t.found || r?.(a(e)), t.value;
+			}
+			return Array.isArray(e) ? e.map((e) => o(e, n, r, s + 1)) : typeof e == "object" && e ? Object.fromEntries(Object.entries(e).map(([e, t]) => [e, o(t, n, r, s + 1)])) : e;
+		}
+	}
+	e.deep = o;
+})(e ||= {});
+var t = e;
+//#endregion
+export { t };

package/specDefs.cjs

@@ -0,0 +1 @@
+var e;(function(e){function t(e,n){let r={...e};if(r.$ref?.startsWith(`#/$defs/`)){let e=n[r.$ref.slice(8)];e&&(r.$ref=`#/$defs/${e}`)}return r.anyOf&&=r.anyOf.map(e=>t(e,n)),r.items&&=t(r.items,n),r.properties&&=Object.fromEntries(Object.entries(r.properties).map(([e,r])=>[e,t(r,n)])),r}function n(e,n){let{$defs:r,...i}=e;if(!r)return i;let a={};for(let[e,t]of Object.entries(r)){let r=n[e];if(!r){n[e]=t;continue}if(JSON.stringify(r)===JSON.stringify(t))continue;let i=2;for(;n[`${e}${i}`]&&JSON.stringify(n[`${e}${i}`])!==JSON.stringify(t);)i+=1;n[`${e}${i}`]=t,a[e]=`${e}${i}`}return Object.keys(a).length?t(i,a):i}e.hoist=n})(e||={});var t=e;Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});

package/specDefs.mjs

@@ -0,0 +1,33 @@
+//#region src/utils/spec/specDefs.ts
+var e;
+(function(e) {
+	function t(e, n) {
+		let r = { ...e };
+		if (r.$ref?.startsWith("#/$defs/")) {
+			let e = n[r.$ref.slice(8)];
+			e && (r.$ref = `#/$defs/${e}`);
+		}
+		return r.anyOf &&= r.anyOf.map((e) => t(e, n)), r.items &&= t(r.items, n), r.properties &&= Object.fromEntries(Object.entries(r.properties).map(([e, r]) => [e, t(r, n)])), r;
+	}
+	function n(e, n) {
+		let { $defs: r, ...i } = e;
+		if (!r) return i;
+		let a = {};
+		for (let [e, t] of Object.entries(r)) {
+			let r = n[e];
+			if (!r) {
+				n[e] = t;
+				continue;
+			}
+			if (JSON.stringify(r) === JSON.stringify(t)) continue;
+			let i = 2;
+			for (; n[`${e}${i}`] && JSON.stringify(n[`${e}${i}`]) !== JSON.stringify(t);) i += 1;
+			n[`${e}${i}`] = t, a[e] = `${e}${i}`;
+		}
+		return Object.keys(a).length ? t(i, a) : i;
+	}
+	e.hoist = n;
+})(e ||= {});
+var t = e;
+//#endregion
+export { t };

package/specSchema.cjs

@@ -0,0 +1 @@
+const e=require("./specDefs.cjs");var t=`default`,n=`#/$defs/node`,r=`#/$defs/children`,i=`#/$defs/reference`,a=`#/$defs/action`;function o(e){return e.properties?{...e,properties:Object.fromEntries(Object.entries(e.properties).map(([e,t])=>[e,{anyOf:[t,{$ref:i}]}]))}:e}function s(n,s,c,l){let u=s.slots??[`default`],d=u.filter(e=>e!==t),f=s.events??[],p=s.props&&Object.keys(s.props.properties??{}).length?e.t.hoist(s.props,c):null,m={type:{type:`string`,enum:[n]}};return p&&(m.props=l?o(p):p),u.includes(`default`)&&(m.children={$ref:r}),d.length&&(m.slots={type:`object`,properties:Object.fromEntries(d.map(e=>[e,{$ref:r}])),additionalProperties:!1}),f.length&&(m.on={type:`object`,properties:Object.fromEntries(f.map(e=>[e,{$ref:a}])),additionalProperties:!1}),l&&(m.repeat={$ref:i}),m.key={type:`string`},{...s.description?{description:s.description}:{},type:`object`,properties:m,required:p?.required?.length?[`type`,`props`]:[`type`],additionalProperties:!1}}var c={description:`A value read from the data the view is rendered against, rather than written into the spec.`,anyOf:[{type:`object`,properties:{$data:{type:`string`}},required:[`$data`],additionalProperties:!1},{type:`object`,properties:{$item:{type:`string`}},required:[`$item`],additionalProperties:!1},{type:`object`,properties:{$index:{type:`boolean`,enum:[!0]}},required:[`$index`],additionalProperties:!1}]},l={description:`What to tell the host when this happens. The host decides what it does; the spec never can.`,anyOf:[{type:`string`},{type:`object`,properties:{action:{type:`string`},payload:{type:`object`}},required:[`action`],additionalProperties:!1}]};function u(e,t={}){let r=t.bindings===!0,a=Object.keys(e.components),o={};o.node={anyOf:a.map(e=>({$ref:`#/$defs/${e}`}))},o.children={type:`array`,items:{anyOf:[{type:`string`},{type:`number`},{$ref:n},...r?[{$ref:i}]:[]]}},r&&(o.reference=c),a.some(t=>e.components[t].events?.length)&&(o.action=l);for(let e of a)o[e]={};for(let t of a)o[t]=s(t,e.components[t],o,r);return{description:`A user interface, as a tree of components the application allows.`,$defs:o,anyOf:(t.root?a.filter(e=>t.root.includes(e)):a).map(e=>({$ref:`#/$defs/${e}`}))}}Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return u}});

package/specSchema.mjs

@@ -0,0 +1,88 @@
+import { t as e } from "./specDefs.mjs";
+//#region src/utils/spec/specTypes.ts
+var t = "default", n = "#/$defs/node", r = "#/$defs/children", i = "#/$defs/reference", a = "#/$defs/action";
+function o(e) {
+	return e.properties ? {
+		...e,
+		properties: Object.fromEntries(Object.entries(e.properties).map(([e, t]) => [e, { anyOf: [t, { $ref: i }] }]))
+	} : e;
+}
+function s(n, s, c, l) {
+	let u = s.slots ?? ["default"], d = u.filter((e) => e !== t), f = s.events ?? [], p = s.props && Object.keys(s.props.properties ?? {}).length ? e.hoist(s.props, c) : null, m = { type: {
+		type: "string",
+		enum: [n]
+	} };
+	return p && (m.props = l ? o(p) : p), u.includes("default") && (m.children = { $ref: r }), d.length && (m.slots = {
+		type: "object",
+		properties: Object.fromEntries(d.map((e) => [e, { $ref: r }])),
+		additionalProperties: !1
+	}), f.length && (m.on = {
+		type: "object",
+		properties: Object.fromEntries(f.map((e) => [e, { $ref: a }])),
+		additionalProperties: !1
+	}), l && (m.repeat = { $ref: i }), m.key = { type: "string" }, {
+		...s.description ? { description: s.description } : {},
+		type: "object",
+		properties: m,
+		required: p?.required?.length ? ["type", "props"] : ["type"],
+		additionalProperties: !1
+	};
+}
+var c = {
+	description: "A value read from the data the view is rendered against, rather than written into the spec.",
+	anyOf: [
+		{
+			type: "object",
+			properties: { $data: { type: "string" } },
+			required: ["$data"],
+			additionalProperties: !1
+		},
+		{
+			type: "object",
+			properties: { $item: { type: "string" } },
+			required: ["$item"],
+			additionalProperties: !1
+		},
+		{
+			type: "object",
+			properties: { $index: {
+				type: "boolean",
+				enum: [!0]
+			} },
+			required: ["$index"],
+			additionalProperties: !1
+		}
+	]
+}, l = {
+	description: "What to tell the host when this happens. The host decides what it does; the spec never can.",
+	anyOf: [{ type: "string" }, {
+		type: "object",
+		properties: {
+			action: { type: "string" },
+			payload: { type: "object" }
+		},
+		required: ["action"],
+		additionalProperties: !1
+	}]
+};
+function u(e, t = {}) {
+	let r = t.bindings === !0, a = Object.keys(e.components), o = {};
+	o.node = { anyOf: a.map((e) => ({ $ref: `#/$defs/${e}` })) }, o.children = {
+		type: "array",
+		items: { anyOf: [
+			{ type: "string" },
+			{ type: "number" },
+			{ $ref: n },
+			...r ? [{ $ref: i }] : []
+		] }
+	}, r && (o.reference = c), a.some((t) => e.components[t].events?.length) && (o.action = l);
+	for (let e of a) o[e] = {};
+	for (let t of a) o[t] = s(t, e.components[t], o, r);
+	return {
+		description: "A user interface, as a tree of components the application allows.",
+		$defs: o,
+		anyOf: (t.root ? a.filter((e) => t.root.includes(e)) : a).map((e) => ({ $ref: `#/$defs/${e}` }))
+	};
+}
+//#endregion
+export { t as n, u as t };

package/utils/agent/agentUtils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The model behind the agent chrome — `<ToolCallCard>`, `<ApprovalCard>`, `<Reasoning>` and
+ * `<StreamingText>`. Four judgements, none of which needs React: what a status is *called*, how long a
+ * thought took in words, how a value a model invented becomes text that is safe to put on a page, and
+ * which part of a message arrived since the last render.
+ *
+ * The third is the reason this file exists. A tool's arguments are whatever the model produced —
+ * possibly circular, possibly a `BigInt`, possibly a megabyte — and `JSON.stringify` answers those three
+ * with a throw, a throw and a frozen tab. Components render, models decide.
+ */
+/**
+ * Where a tool call is. The four states every agent runtime reports under its own spelling: AI SDK's
+ * `input-streaming`/`input-available`/`output-available`/`output-error`, and the plainer words the card
+ * shows. Declared out here rather than inside the namespace so a prop naming it resolves to its values —
+ * a catalog that printed the alias would constrain nothing.
+ */
+export type ToolCallStatus = 'pending' | 'running' | 'success' | 'error';
+/** What was decided about an action the agent asked permission for. `null` is "not yet". */
+export type ApprovalDecision = 'approved' | 'rejected';
+declare namespace AgentUtils {
+    function statusLabel(status: ToolCallStatus): string;
+    function decisionLabel(decision: ApprovalDecision): string;
+    /**
+     * How much of a value the card will show. Past this the text is cut and a line says how much was left —
+     * a model that returned a 4 MB tool result should cost a scroll bar, not the frame it is painted in.
+     */
+    const VALUE_LIMIT = 20000;
+    interface FormattedValue {
+        text: string;
+        /** How many characters were cut, or `0`. The card says so rather than showing text that stops. */
+        truncated: number;
+    }
+    /** A tool's input, output or error as text, capped. The one place a model's own data becomes a page. */
+    function formatValue(value: unknown, limit?: number): FormattedValue;
+    /** Whether there is anything to show at all — `null` and `undefined` are absence, `0` and `''` are not. */
+    function hasValue(value: unknown): boolean;
+    /**
+     * A count with its thousands grouped, done here rather than with `toLocaleString`: the number lands in
+     * prerendered HTML, and a separator that differs between the server's locale and the reader's is a
+     * hydration mismatch nobody would look for.
+     */
+    function formatCount(value: number): string;
+    /**
+     * How long a thought took, in the units a reader thinks in: milliseconds under a second, then seconds,
+     * then minutes and seconds. Rounded down for the minutes so "1m 0s" is a minute rather than two.
+     */
+    function formatDuration(milliseconds: number): string;
+    /**
+     * One run of text that arrived together, and the identity React keys it by. Keys are never reused, so a
+     * run that is still fading is never handed a different run's text half way through its entrance.
+     */
+    interface StreamSegment {
+        key: number;
+        text: string;
+    }
+    /**
+     * A streaming message between two renders: the text that has settled, and the last few runs to arrive,
+     * which are the ones still fading in.
+     */
+    interface StreamState {
+        settled: string;
+        segments: readonly StreamSegment[];
+        /** Monotone, and carried across a reset — a key a fading run still holds is never handed out twice. */
+        nextKey: number;
+    }
+    /**
+     * How many runs stay animated at once. The rest settle, so a message of any length is one text node plus
+     * this many spans — the reason the entrance costs the same at the first token and the ten-thousandth.
+     */
+    const STREAM_WINDOW = 8;
+    /** A message that is already whole: all of it settled, none of it animating. */
+    function initialStream(text: string): StreamState;
+    /** Everything on the page, settled and still arriving. */
+    function streamText(state: StreamState): string;
+    /**
+     * The next state for the text as it now stands. Pure, and keyed on the text itself rather than on a
+     * counter, so advancing twice with the same message is the same as advancing once.
+     */
+    function advanceStream(state: StreamState, text: string, window?: number): StreamState;
+}
+export default AgentUtils;

package/utils/catalog/catalogContracts.d.ts

@@ -0,0 +1,19 @@
+import { CatalogContract } from '@box-kite/core';
+/**
+ * The props that are a *shape* rather than a value — a grid's columns, a dashboard's layout — as the JSON
+ * Schema a generated spec is judged against. Written here rather than extracted because the manifest maps
+ * types, and half of each of these shapes is React: a `Cell` renderer, an `onCellEdit`, a `ReactNode`. A
+ * mapping has to drop such a prop whole, which is what left the catalog able to place a dashboard and not
+ * to say what was in it — `<DataGrid>` arrived with no `def` at all, and `def` is required.
+ *
+ * Every key is typed against the interface it mirrors, so a prop renamed in the component is a compile
+ * error here rather than a constraint that silently stops matching anything.
+ */
+declare namespace CatalogContracts {
+    /**
+     * Component name → the props of it a manifest entry cannot describe. Merged over the generated entry, so
+     * a prop that appears in both is this one: the curated shape is the narrower of the two by construction.
+     */
+    const CONTRACTS: Record<string, CatalogContract>;
+}
+export default CatalogContracts;