@jigs.design/compiler 0.0.0-stage → 0.1.1

package/dist/compile.js

@@ -0,0 +1,950 @@
+import { analyze } from "./script.js";
+import { generateProgram, isBindingName } from "./codegen.js";
+import { columnAt, lineAt, sourceRange } from "./offsets.js";
+import { closest, nearest } from "./suggest.js";
+import { checkCode } from "./check-code.js";
+import { parsePickle } from "./parse.js";
+import { isValidValue } from "./spec.js";
+import { blockHoists } from "./block-hoist.js";
+//#region src/compile.ts
+const RESERVED_TAGS = /* @__PURE__ */ new Set([
+	"define",
+	"each",
+	"if",
+	"slot"
+]);
+const HOOK_MESSAGE = {
+	useMutation: {
+		each: "inside <each> is not supported; declare it at the top and compare its input to find the busy item",
+		if: "inside <if> is not supported; declare it at the top"
+	},
+	useQuery: {
+		each: "inside <each> is not supported; declare it at the top of the document or of a <define>",
+		if: "inside <if> is not supported; declare it at the top"
+	},
+	useState: {
+		each: "inside <each> is not supported; keep per-item state in one object at the top",
+		if: "inside <if> is not supported; declare state at the top"
+	}
+};
+/** How to write each hook, for a message that names the form to write. */
+const HOOK_FORM = {
+	useMutation: "const archive = useMutation(\"name\")",
+	useQuery: "const orders = useQuery(\"name\")",
+	useState: "const [open, setOpen] = useState(false)"
+};
+/**
+* A hook used as a value, written `Pickle.useX`, called inside a handler
+* or anywhere but as a top-level declaration's initializer, or declared
+* inside `<each>` or `<if>`. Null when the code parses and uses hooks only
+* as it may, or does not parse (the parse error is reported elsewhere).
+*/
+function hookMisuse(code, kind, block) {
+	const facts = analyze(code, kind);
+	if (!facts.ok) return null;
+	const message = (text) => ({
+		declared: facts.declared,
+		message: text
+	});
+	const [value] = facts.hookValues;
+	if (value !== void 0) return message(`\`${value.hook}\` is not a value: call it in a {@body} line at the top of the document or of a <define>, \`${HOOK_FORM[value.hook]}\``);
+	const [call] = facts.hookCalls;
+	if (call === void 0) return null;
+	const written = call.prefixed ? `Pickle.${call.hook}` : call.hook;
+	if (block === "each" || block === "if") return message(`${written} ${HOOK_MESSAGE[call.hook][block]}`);
+	if (call.prefixed) return message(`\`${written}\` is not supported: write \`${call.hook}\` without the prefix, \`${HOOK_FORM[call.hook]}\``);
+	if (call.place === "handler") return message(call.hook === "useMutation" ? `\`useMutation(...)\` inside a handler is not supported: declare \`${HOOK_FORM.useMutation}\` in a {@body} line at the top of the document or of a <define>, and call \`archive.mutate(input)\` from the handler` : `\`${call.hook}(...)\` inside a handler is not supported: declare it in a {@body} line at the top of the document or of a <define>, \`${HOOK_FORM[call.hook]}\`, and read it from the handler`);
+	if (call.place === "nested") return message(`\`${call.hook}(...)\` must be the whole initializer of a {@body} line at the top of the document or of a <define>, \`${HOOK_FORM[call.hook]}\`, not part of a condition, a call or another expression`);
+	return null;
+}
+const NO_LIBRARY = /* @__PURE__ */ new Map();
+/** Libraries by catalog, then by recipe list. */
+const libraryCache = /* @__PURE__ */ new WeakMap();
+function propSpec(spec, name) {
+	const props = spec.props;
+	return Object.hasOwn(props, name) ? props[name] : void 0;
+}
+function componentSpec(components, name) {
+	return Object.hasOwn(components, name) ? components[name] : void 0;
+}
+const controlProps = {
+	each: [
+		"of",
+		"as",
+		"index"
+	],
+	if: ["test"]
+};
+const asCode = (value) => value === void 0 ? null : value.kind === "expr" ? value.code : JSON.stringify(value.value);
+function literalKind(value) {
+	if (typeof value === "boolean") return "boolean";
+	if (typeof value === "number") return "number";
+	return "string";
+}
+function propSignature(prop) {
+	if (prop.shorthand === true) return {
+		defaultValue: null,
+		kind: null,
+		name: prop.name,
+		required: true
+	};
+	if (prop.value.kind === "literal") return {
+		defaultValue: prop.value,
+		kind: literalKind(prop.value.value),
+		name: prop.name,
+		required: false
+	};
+	return {
+		defaultValue: prop.value,
+		kind: null,
+		name: prop.name,
+		required: false
+	};
+}
+/** A `<slot/>` anywhere in the define's source, ignoring nested defines. */
+function treeHasSlot(nodes) {
+	for (const node of nodes) {
+		if (node.type !== "element" || node.name === "define") continue;
+		if (node.name === "slot" || treeHasSlot(node.children)) return true;
+	}
+	return false;
+}
+function readDefine(node, diagnostics, libraryNames, components) {
+	const nameProp = node.props.find((prop) => prop.name === "name");
+	const name = nameProp !== void 0 && nameProp.shorthand !== true && nameProp.value.kind === "literal" && typeof nameProp.value.value === "string" ? nameProp.value.value : null;
+	if (name === null) {
+		diagnostics.push({
+			code: "invalid_define",
+			...placeOf(node),
+			message: `<define> needs name="componentName"; it was removed`,
+			severity: "warning"
+		});
+		return null;
+	}
+	if (componentSpec(components, name) !== void 0 || RESERVED_TAGS.has(name)) {
+		diagnostics.push({
+			code: "invalid_define",
+			...placeOf(node),
+			message: `<define name="${name}"> clashes with <${name}>; it was removed`,
+			severity: "warning"
+		});
+		return null;
+	}
+	if (!isBindingName(name)) {
+		diagnostics.push({
+			code: "invalid_define",
+			...placeOf(node),
+			message: `<define name="${name}"> is not a usable component name; it was removed`,
+			severity: "warning"
+		});
+		return null;
+	}
+	if (libraryNames.has(name)) diagnostics.push({
+		code: "shadows_library",
+		...placeOf(node),
+		message: `<define name="${name}"> overrides the library component`,
+		severity: "info"
+	});
+	const props = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const prop of node.props) {
+		if (prop === nameProp) continue;
+		if (prop.name === "key") {
+			diagnostics.push({
+				code: "invalid_define",
+				...placeOf(node, prop),
+				message: `<define name="${name}"> prop "key" is reserved for the instance; it was removed`,
+				severity: "warning"
+			});
+			continue;
+		}
+		if (prop.name === "name") {
+			diagnostics.push({
+				code: "invalid_define",
+				...placeOf(node, prop),
+				message: `<define name="${name}"> cannot take a prop called "name", which names the define itself; call it "title" or "label". It was removed`,
+				severity: "warning"
+			});
+			continue;
+		}
+		if (prop.name === "children" || !isBindingName(prop.name)) {
+			diagnostics.push({
+				code: "invalid_define",
+				...placeOf(node, prop),
+				message: `<define name="${name}"> prop "${prop.name}" is not a usable name; it was removed`,
+				severity: "warning"
+			});
+			continue;
+		}
+		if (seen.has(prop.name)) {
+			diagnostics.push({
+				code: "invalid_define",
+				...placeOf(node, prop),
+				message: `<define name="${name}"> prop "${prop.name}" is duplicated; the later one was removed`,
+				severity: "warning"
+			});
+			continue;
+		}
+		seen.add(prop.name);
+		props.push(propSignature(prop));
+	}
+	return {
+		body: [],
+		hasSlot: treeHasSlot(node.children),
+		line: node.line,
+		name,
+		origin: "doc",
+		procedures: [],
+		props,
+		statements: []
+	};
+}
+function lookupHint(name, candidates) {
+	const lower = name.toLowerCase();
+	for (const candidate of candidates) if (candidate !== name && candidate.toLowerCase() === lower) return candidate;
+}
+/** HTML and other UI-library tags, and the catalog tag that does the job. */
+const TAG_ALIASES = /* @__PURE__ */ new Map([
+	["a", "link"],
+	["b", "bold"],
+	["div", "box"],
+	["em", "italic"],
+	["h1", "title"],
+	["h2", "title"],
+	["h3", "title"],
+	["h4", "title"],
+	["hr", "divider"],
+	["i", "italic"],
+	["img", "image"],
+	["li", "item"],
+	["ol", "list"],
+	["p", "text"],
+	["section", "box"],
+	["span", "text"],
+	["strong", "bold"],
+	["ul", "list"],
+	["view", "box"]
+]);
+/** Tags a model writes for control flow that Pickle spells differently. */
+const CONTROL_HINTS = /* @__PURE__ */ new Map([
+	["elif", "There is no <elif>: add another <if> with its own test"],
+	["else", "There is no <else>: add a second <if> with the opposite test"],
+	["elseif", "There is no <elseif>: add another <if> with its own test"],
+	["for", "There is no <for>: repeat children with <each of={list}>"],
+	["foreach", "There is no <foreach>: repeat children with <each of={list}>"],
+	["map", "There is no <map>: repeat children with <each of={list}>"],
+	["switch", "There is no <switch>: add one <if> per case"]
+]);
+function unknownComponentMessage(name, defines, components) {
+	const control = CONTROL_HINTS.get(name.toLowerCase());
+	if (control !== void 0) return `${control}. Rendering its children only`;
+	const known = [...Object.keys(components), ...defines.keys()];
+	const alias = TAG_ALIASES.get(name.toLowerCase());
+	const hint = lookupHint(name, known) ?? (alias !== void 0 && known.includes(alias) ? alias : void 0) ?? nearest(name, known, 1)[0];
+	return hint === void 0 ? `<${name}> is not in the catalog; rendering its children only` : `<${name}> is not in the catalog; did you mean <${hint}>? Rendering its children only`;
+}
+/** Props other UI libraries use, and the name Pickle uses for the same thing. */
+const PROP_ALIASES = /* @__PURE__ */ new Map([
+	["checked", "value"],
+	["onChangeText", "onChange"],
+	["onInput", "onChange"],
+	["onPress", "onClick"],
+	["onSelect", "onChange"],
+	["onTap", "onClick"],
+	["onValueChange", "onChange"],
+	["selected", "value"]
+]);
+const STYLE_PROPS = /* @__PURE__ */ new Set([
+	"class",
+	"className",
+	"style",
+	"sx"
+]);
+function unknownPropMessage(component, name, props) {
+	const base = `<${component}> has no prop "${name}"`;
+	if (STYLE_PROPS.has(name)) return `${base}; style only through the component's props`;
+	for (const [prop, spec] of Object.entries(props)) if (spec.kind === "enum" && spec.values.includes(name)) return `${base}; write ${prop}="${name}"`;
+	const alias = PROP_ALIASES.get(name);
+	const hint = lookupHint(name, Object.keys(props)) ?? (alias !== void 0 && Object.hasOwn(props, alias) ? alias : void 0) ?? nearest(name, Object.keys(props), 1)[0];
+	if (hint !== void 0) return `${base}; did you mean ${hint}?`;
+	const names = Object.keys(props);
+	return names.length > 0 && names.length <= 12 ? `${base}; it has ${names.join(", ")}` : base;
+}
+/**
+* `flex` on a component that has none, as `<text flex={1}>` in a row: the
+* element wrapped in a `<box>` that takes it, which is what makes it
+* stretch. Null when the catalog's `<box>` has no `flex`, or the parser
+* cannot place the element's closing tag.
+*/
+function flexWrap(node, prop, catalog) {
+	if (prop.name !== "flex" || prop.written === void 0 || prop.start === void 0 || prop.end === void 0 || node.closeEnd === void 0 || componentSpec(catalog, "box")?.props["flex"] === void 0) return null;
+	return {
+		fix: {
+			edits: [
+				{
+					end: node.start,
+					start: node.start,
+					text: `<box ${prop.written}>`
+				},
+				{
+					end: prop.end,
+					start: prop.start,
+					text: ""
+				},
+				{
+					end: node.closeEnd,
+					start: node.closeEnd,
+					text: "</box>"
+				}
+			],
+			title: `Wrap <${node.name}> in <box ${prop.written}>`
+		},
+		written: prop.written
+	};
+}
+/**
+* Deletes the element's prop at `index` with the whitespace in front of it,
+* which runs from the end of the prop or tag name before it. Null when the
+* parser made up either end.
+*/
+function dropAttribute(node, index) {
+	const prop = node.props[index];
+	const before = index === 0 ? node.start + 1 + node.name.length : node.props[index - 1]?.end;
+	if (prop?.end === void 0 || before === void 0) return null;
+	return {
+		edits: [{
+			end: prop.end,
+			start: before,
+			text: ""
+		}],
+		title: `Remove ${writtenProp(prop)}`
+	};
+}
+const NUMERIC = /^\s*-?\d+(?:\.\d+)?\s*$/;
+/** A quoted number on a number prop, such as `gap="3"`, read as the number. */
+function coerceNumber(spec, value) {
+	if (spec.kind !== "number" || value.kind !== "literal" || typeof value.value !== "string" || !NUMERIC.test(value.value)) return null;
+	const number = Number(value.value);
+	return isValidValue(spec, number) ? {
+		kind: "literal",
+		value: number
+	} : null;
+}
+/** The attribute as the source wrote it. */
+const writtenProp = (prop) => prop.written ?? (prop.value.kind === "literal" ? `${prop.name}={${JSON.stringify(prop.value.value)}}` : `${prop.name}={${prop.value.code}}`);
+/**
+* Where a diagnostic about `node` points: its line, and its range in the
+* source when it has one, or `prop`'s when the diagnostic is about one prop.
+*/
+function placeOf(node, prop) {
+	const range = prop?.start === void 0 ? node : prop;
+	return range.start === void 0 || range.end === void 0 ? { line: node.line } : {
+		end: range.end,
+		line: node.line,
+		start: range.start
+	};
+}
+/** Where a diagnostic about a piece of code points. */
+function placeOfCode(code) {
+	if (code.at === void 0) return { line: code.line };
+	const range = sourceRange(code.at, 0, code.code.length);
+	return {
+		end: range.end,
+		line: code.line,
+		start: range.start
+	};
+}
+const codeAt = (value) => value?.kind === "expr" ? value.at : void 0;
+function validateControl(node, name, children, statements, diagnostics) {
+	const warn = (code, message, prop) => {
+		diagnostics.push({
+			code,
+			...placeOf(node, prop),
+			message,
+			severity: "warning"
+		});
+	};
+	const props = new Map(node.props.map((prop) => [prop.name, prop.value]));
+	for (const [index, prop] of node.props.entries()) {
+		if (controlProps[name].some((allowed) => allowed === prop.name)) continue;
+		const fix = name === "each" && prop.name === "key" ? dropAttribute(node, index) : null;
+		if (fix === null) {
+			warn("unknown_prop", `<${name}> has no prop "${prop.name}"`, prop);
+			continue;
+		}
+		diagnostics.push({
+			code: "unknown_prop",
+			...placeOf(node, prop),
+			fix,
+			message: "<each> has no prop \"key\": items are keyed by their own `id` or `key`",
+			severity: "warning"
+		});
+	}
+	if (name === "if") {
+		const test = asCode(props.get("test"));
+		if (test === null) {
+			warn("invalid_control", "<if> needs test={condition}; it was removed");
+			return [];
+		}
+		const testAt = codeAt(props.get("test"));
+		return [{
+			children,
+			line: node.line,
+			statements,
+			test,
+			testAt,
+			type: "if"
+		}];
+	}
+	const items = asCode(props.get("of"));
+	const itemsAt = codeAt(props.get("of"));
+	if (items === null) {
+		warn("invalid_control", "<each> needs of={list}; it was removed");
+		return [];
+	}
+	const binding = (prop, fallback) => {
+		const value = props.get(prop);
+		if (value === void 0) return fallback;
+		if (value.kind === "literal" && isBindingName(String(value.value))) return String(value.value);
+		warn("invalid_control", `<each ${prop}> must be a plain variable name like "item"; using ${fallback === null ? "none" : `"${fallback}"`}`);
+		return fallback;
+	};
+	return [{
+		children,
+		index: binding("index", null),
+		item: binding("as", "item") ?? "item",
+		items,
+		itemsAt,
+		line: node.line,
+		statements,
+		type: "each"
+	}];
+}
+function validateSlot(node, state) {
+	if (!state.inDefine) {
+		state.diagnostics.push({
+			code: "invalid_define",
+			...placeOf(node),
+			message: "<slot> is only allowed inside <define>; it was removed",
+			severity: "warning"
+		});
+		return [];
+	}
+	for (const prop of node.props) state.diagnostics.push({
+		code: "unknown_prop",
+		...placeOf(node, prop),
+		message: `<slot> has no prop "${prop.name}"`,
+		severity: "warning"
+	});
+	if (node.children.length > 0) state.diagnostics.push({
+		code: "unexpected_children",
+		...placeOf(node),
+		message: "<slot> takes no children; they were dropped",
+		severity: "warning"
+	});
+	return [{
+		line: node.line,
+		type: "slot"
+	}];
+}
+/** Keeps the first `<slot/>` that survived validation and drops the rest. */
+function trimExtraSlots(nodes, defineName, diagnostics, seen) {
+	return nodes.flatMap((node) => {
+		if (node.type === "slot") {
+			if (seen.count > 0) {
+				diagnostics.push({
+					code: "invalid_define",
+					...placeOf(node),
+					message: `<${defineName}> already has a <slot>; this one was removed`,
+					severity: "warning"
+				});
+				return [];
+			}
+			seen.count++;
+			return [node];
+		}
+		if (node.type === "call" || node.type === "each" || node.type === "element" || node.type === "if") return [{
+			...node,
+			children: trimExtraSlots(node.children, defineName, diagnostics, seen)
+		}];
+		return [node];
+	});
+}
+function validateCall(node, def, state, scope) {
+	const ordinal = state.ordinals.get(def.name) ?? 0;
+	state.ordinals.set(def.name, ordinal + 1);
+	const children = validateNodes(node.children, state, scope);
+	const known = new Map(def.props.map((prop) => [prop.name, prop]));
+	const props = {};
+	let key = null;
+	for (const prop of node.props) {
+		if (prop.name === "key") {
+			if (prop.value.kind === "literal" && typeof prop.value.value !== "string" && typeof prop.value.value !== "number") {
+				state.diagnostics.push({
+					code: "invalid_literal",
+					...placeOf(node, prop),
+					message: `<${def.name} key={${JSON.stringify(prop.value.value)}}> must be a string or number`,
+					severity: "warning"
+				});
+				continue;
+			}
+			key = prop.value;
+			continue;
+		}
+		const spec = known.get(prop.name);
+		if (spec === void 0) {
+			const near = nearest(prop.name, known.keys(), 1)[0];
+			state.diagnostics.push({
+				code: "unknown_prop",
+				...placeOf(node, prop),
+				message: near === void 0 ? `<${def.name}> has no prop "${prop.name}"` : `<${def.name}> has no prop "${prop.name}"; did you mean ${near}?`,
+				severity: "warning"
+			});
+			continue;
+		}
+		if (spec.kind === "number" && prop.value.kind === "literal" && typeof prop.value.value === "string" && NUMERIC.test(prop.value.value)) {
+			const value = Number(prop.value.value);
+			state.diagnostics.push({
+				code: "coerced",
+				...placeOf(node, prop),
+				message: `<${def.name} ${writtenProp(prop)}> is text; it was read as ${prop.name}={${String(value)}}. Write numbers in braces`,
+				severity: "info"
+			});
+			props[prop.name] = {
+				kind: "literal",
+				value
+			};
+			continue;
+		}
+		if (prop.value.kind === "literal" && spec.kind !== null && typeof prop.value.value !== spec.kind) {
+			state.diagnostics.push({
+				code: "invalid_literal",
+				...placeOf(node, prop),
+				message: `<${def.name} ${writtenProp(prop)}> does not match a ${spec.kind} value`,
+				severity: "warning"
+			});
+			continue;
+		}
+		props[prop.name] = prop.value;
+	}
+	for (const spec of def.props) if (spec.required && !Object.hasOwn(props, spec.name)) state.diagnostics.push({
+		code: "missing_prop",
+		...placeOf(node),
+		message: `<${def.name}> is missing required prop "${spec.name}"`,
+		severity: "warning"
+	});
+	if (!def.hasSlot && def.incomplete !== true && children.length > 0) state.diagnostics.push({
+		code: "unexpected_children",
+		...placeOf(node),
+		message: `<${def.name}> has no <slot>, so its children were dropped`,
+		severity: "warning"
+	});
+	return [{
+		children: def.hasSlot ? children : [],
+		key,
+		line: node.line,
+		name: def.name,
+		ordinal,
+		origin: def.origin,
+		props,
+		type: "call"
+	}];
+}
+/**
+* Validates `nodes` against the catalog and in-scope defines. `{@body}` lines
+* move into `scope`: the statements of the nearest enclosing `<define>`,
+* `<each>` or `<if>`, or of the whole program.
+*/
+function validateNodes(nodes, state, scope) {
+	return nodes.flatMap((node) => {
+		if (node.type === "statement") {
+			const misuse = hookMisuse(node.code, "statement", scope.block);
+			if (misuse !== null) {
+				const inBlock = scope.block === "each" || scope.block === "if";
+				const hoist = inBlock ? state.hoists.byStart.get(node.start) : void 0;
+				const diagnostic = {
+					code: inBlock ? "invalid_statement" : "hook_placement",
+					...placeOfCode(node),
+					message: `${misuse.message}${hoist?.reason === null || hoist?.reason === void 0 ? "" : `; it can't move out by itself, as it ${hoist.reason}`}. The statement was removed`,
+					severity: "warning"
+				};
+				if (hoist?.fix) diagnostic.fix = hoist.fix;
+				state.diagnostics.push(diagnostic);
+				for (const name of misuse.declared) state.dropped.add(name);
+				return [];
+			}
+			scope.statements.push({
+				at: node.at,
+				code: node.code,
+				end: node.end,
+				line: node.line,
+				start: node.start
+			});
+			return [];
+		}
+		if (node.type === "expr") {
+			const misuse = hookMisuse(node.code, "expression", scope.block);
+			if (misuse !== null) {
+				state.diagnostics.push({
+					code: "hook_placement",
+					...placeOfCode(node),
+					message: `${misuse.message}. The expression was removed`,
+					severity: "warning"
+				});
+				return [];
+			}
+			return [node];
+		}
+		if (node.type !== "element") return [node];
+		if (node.name === "define") {
+			state.diagnostics.push({
+				code: "invalid_define",
+				...placeOf(node),
+				message: "<define> is only allowed at the top level; it was removed",
+				severity: "warning"
+			});
+			return [];
+		}
+		if (node.name === "slot") return validateSlot(node, state);
+		if (node.name === "each" || node.name === "if") {
+			const statements = [];
+			const children = validateNodes(node.children, state, {
+				block: node.name,
+				statements
+			});
+			return validateControl(node, node.name, children, statements, state.diagnostics);
+		}
+		const defined = state.defines.get(node.name);
+		if (defined !== void 0) return validateCall(node, defined, state, scope);
+		const children = validateNodes(node.children, state, scope);
+		const spec = componentSpec(state.catalog, node.name);
+		if (spec === void 0) {
+			state.diagnostics.push({
+				code: "unknown_component",
+				...placeOf(node),
+				message: unknownComponentMessage(node.name, state.defines, state.catalog),
+				severity: "warning"
+			});
+			return children;
+		}
+		const component = node.name;
+		const props = {};
+		for (const prop of node.props) {
+			if (prop.name === "key") continue;
+			const propDefinition = propSpec(spec, prop.name);
+			if (propDefinition === void 0) {
+				const wrap = flexWrap(node, prop, state.catalog);
+				const diagnostic = {
+					code: "unknown_prop",
+					...placeOf(node, prop),
+					message: wrap === null ? unknownPropMessage(component, prop.name, spec.props) : `<${component}> has no prop "flex"; wrap it in <box ${wrap.written}>`,
+					severity: "warning"
+				};
+				if (wrap !== null) diagnostic.fix = wrap.fix;
+				state.diagnostics.push(diagnostic);
+				continue;
+			}
+			const misuse = prop.value.kind === "expr" ? hookMisuse(prop.value.code, "expression", scope.block) : null;
+			if (misuse !== null) {
+				state.diagnostics.push({
+					code: "hook_placement",
+					...placeOf(node, prop),
+					message: `<${component} ${prop.name}={…}>: ${misuse.message}. The prop was removed`,
+					severity: "warning"
+				});
+				continue;
+			}
+			const coerced = coerceNumber(propDefinition, prop.value);
+			if (coerced !== null && coerced.kind === "literal") {
+				state.diagnostics.push({
+					code: "coerced",
+					...placeOf(node, prop),
+					message: `<${component} ${writtenProp(prop)}> is text; it was read as ${prop.name}={${String(coerced.value)}}. Write numbers in braces`,
+					severity: "info"
+				});
+				props[prop.name] = coerced;
+				continue;
+			}
+			if (prop.value.kind === "literal" && !isValidValue(propDefinition, prop.value.value)) {
+				state.diagnostics.push({
+					code: "invalid_literal",
+					...placeOf(node, prop),
+					message: `<${component} ${writtenProp(prop)}> does not match ${describe(propDefinition, prop.value.value)}`,
+					severity: "warning"
+				});
+				continue;
+			}
+			props[prop.name] = prop.value;
+		}
+		const allowsChildren = spec.children !== "none";
+		if (!allowsChildren && children.length > 0) state.diagnostics.push({
+			code: "unexpected_children",
+			...placeOf(node),
+			message: `<${component}> takes no children; they were dropped`,
+			severity: "warning"
+		});
+		return [{
+			children: allowsChildren ? children : [],
+			component,
+			line: node.line,
+			props,
+			type: "element"
+		}];
+	});
+}
+/** Enums longer than this list only the values nearest to what was written. */
+const MAX_LISTED_VALUES = 8;
+function describe(spec, written) {
+	if (spec.kind === "enum" && spec.values.length > MAX_LISTED_VALUES) {
+		const near = closest(String(written), spec.values, 5);
+		return `any of its ${spec.values.length} values; the closest are ${near.join(" | ")}. Use a name from the prompt's list`;
+	}
+	if (spec.kind === "enum") return `one of ${spec.values.join(" | ")}`;
+	if (spec.kind === "number" && typeof written === "string") return `${describeNumber(spec)}, and a number goes in braces: {3}, not "3"`;
+	return describeNumber(spec);
+}
+function describeNumber(spec) {
+	if (spec.kind === "number" && spec.min !== void 0 && spec.max !== void 0) return `a number from ${spec.min} to ${spec.max}`;
+	return `a ${spec.kind} value`;
+}
+function visitRender(nodes, visit) {
+	for (const node of nodes) if (node.type === "call") {
+		visit(node);
+		visitRender(node.children, visit);
+	} else if (node.type === "each" || node.type === "element" || node.type === "if") visitRender(node.children, visit);
+}
+/** Document defines, plus library defines reached from the tree or those defines. */
+function emittedDefines(tree, docDefines, available) {
+	const library = [];
+	const seen = new Set(docDefines.map((def) => def.name));
+	const consider = (name) => {
+		if (seen.has(name)) return;
+		const def = available.get(name);
+		if (def?.origin !== "library") return;
+		seen.add(def.name);
+		library.push(def);
+		visitRender(def.body, (call) => {
+			consider(call.name);
+		});
+	};
+	const walk = (nodes) => {
+		visitRender(nodes, (call) => {
+			consider(call.name);
+		});
+	};
+	walk(tree);
+	for (const def of docDefines) walk(def.body);
+	return [...docDefines, ...library.toSorted((a, b) => a.name.localeCompare(b.name))];
+}
+/**
+* Static call sites in the document tree and in document-local define bodies.
+* A tag inside a library recipe is not counted again.
+*/
+function countUses(tree, docDefines) {
+	const counts = /* @__PURE__ */ new Map();
+	const visit = (node) => {
+		const current = counts.get(node.name);
+		counts.set(node.name, {
+			instances: (current?.instances ?? 0) + 1,
+			name: node.name,
+			origin: node.origin
+		});
+	};
+	visitRender(tree, visit);
+	for (const def of docDefines) visitRender(def.body, visit);
+	return [...counts.values()].toSorted((a, b) => a.name.localeCompare(b.name));
+}
+function compileDocument(source, library, components) {
+	const document = parsePickle(source);
+	const diagnostics = [...document.repairs.map((repair) => ({
+		code: "repaired",
+		...placeOf(repair),
+		message: repair.message,
+		severity: "info"
+	})), ...document.errors.map((error) => ({
+		code: "unclosed",
+		...placeOf(error),
+		message: error.message,
+		severity: "warning"
+	}))];
+	const libraryNames = new Set(library.keys());
+	const docDefines = [];
+	const rawBodies = /* @__PURE__ */ new Map();
+	const topLevel = [];
+	const docNames = /* @__PURE__ */ new Set();
+	for (const node of document.children) {
+		if (node.type === "element" && node.name === "define") {
+			const def = readDefine(node, diagnostics, libraryNames, components);
+			if (def === null) continue;
+			if (docNames.has(def.name)) {
+				diagnostics.push({
+					code: "invalid_define",
+					...placeOf(node),
+					message: `<define name="${def.name}"> is already defined; this one was removed`,
+					severity: "warning"
+				});
+				continue;
+			}
+			docNames.add(def.name);
+			def.incomplete = document.repairs.some((repair) => repair.line === node.line && repair.message === "Closed unclosed <define>");
+			docDefines.push(def);
+			rawBodies.set(def.name, node.children);
+			continue;
+		}
+		topLevel.push(node);
+	}
+	const available = new Map(library);
+	for (const def of docDefines) available.set(def.name, def);
+	const dropped = /* @__PURE__ */ new Set();
+	const hoists = blockHoists(document);
+	const state = {
+		catalog: components,
+		defineName: null,
+		defines: available,
+		diagnostics,
+		dropped,
+		hoists,
+		inDefine: false,
+		ordinals: /* @__PURE__ */ new Map()
+	};
+	for (const def of docDefines) {
+		const statements = [];
+		def.body = trimExtraSlots(validateNodes(rawBodies.get(def.name) ?? [], {
+			catalog: components,
+			defineName: def.name,
+			defines: available,
+			diagnostics,
+			dropped,
+			hoists,
+			inDefine: true,
+			ordinals: /* @__PURE__ */ new Map()
+		}, {
+			block: "define",
+			statements
+		}), def.name, diagnostics, { count: 0 });
+		def.statements = statements;
+	}
+	const statements = [];
+	for (const statement of document.statements) {
+		const misuse = hookMisuse(statement.code, "statement", null);
+		if (misuse === null) {
+			statements.push(statement);
+			continue;
+		}
+		diagnostics.push({
+			code: "hook_placement",
+			...placeOfCode(statement),
+			message: `${misuse.message}. The statement was removed`,
+			severity: "warning"
+		});
+		for (const name of misuse.declared) dropped.add(name);
+	}
+	const tree = validateNodes(topLevel, state, {
+		block: null,
+		statements
+	});
+	const uses = checkCode(tree, docDefines, statements, diagnostics, hoists, dropped);
+	const generated = generateProgram(statements, tree, emittedDefines(tree, docDefines, available));
+	diagnostics.push(...generated.diagnostics);
+	for (const diagnostic of diagnostics) if (diagnostic.start !== void 0) {
+		diagnostic.line = lineAt(source, diagnostic.start);
+		diagnostic.column = columnAt(source, diagnostic.start);
+	}
+	diagnostics.sort((a, b) => a.line - b.line);
+	return {
+		defines: docDefines,
+		diagnostics,
+		library,
+		output: generated.output,
+		procedures: uses.procedures,
+		program: {
+			defines: countUses(tree, docDefines),
+			statements,
+			tree
+		},
+		reads: uses.reads,
+		source
+	};
+}
+function buildLibrary(list, components) {
+	const built = /* @__PURE__ */ new Map();
+	for (const recipe of list) {
+		if (built.has(recipe.name)) throw new Error(`Recipe name "${recipe.name}" is duplicated`);
+		const result = compileDocument(recipe.source, built, components);
+		const problem = result.diagnostics[0];
+		if (problem !== void 0) throw new Error(`Recipe "${recipe.name}" failed to compile: line ${problem.line}: ${problem.message}`);
+		const def = result.defines[0];
+		if (result.defines.length !== 1 || def === void 0) throw new Error(`Recipe "${recipe.name}" must contain exactly one <define>`);
+		if (def.name !== recipe.name) throw new Error(`Recipe "${recipe.name}" defines <${def.name}> instead`);
+		built.set(def.name, {
+			...def,
+			origin: "library",
+			procedures: result.procedures
+		});
+	}
+	return built;
+}
+/**
+* Compiles `recipes` against `catalog`, in order: a recipe may use the ones
+* before it. Throws when a recipe has any diagnostic. Cached per catalog and
+* recipe list.
+*/
+function compileLibrary(recipes, catalog) {
+	const byRecipes = libraryCache.get(catalog) ?? /* @__PURE__ */ new WeakMap();
+	libraryCache.set(catalog, byRecipes);
+	const existing = byRecipes.get(recipes);
+	if (existing !== void 0) return existing;
+	const built = buildLibrary(recipes, catalog);
+	byRecipes.set(recipes, built);
+	return built;
+}
+/** `source` with the fixes' edits applied. */
+function applyFixes(source, fixes) {
+	const applied = /* @__PURE__ */ new Set();
+	const taken = [];
+	for (const fix of fixes) if (!fix.edits.some((edit) => taken.some((other) => edit.start < other.end && other.start < edit.end))) {
+		applied.add(fix);
+		taken.push(...fix.edits);
+	}
+	let text = source;
+	const order = taken.map((edit, index) => ({
+		edit,
+		index
+	})).toSorted((a, b) => b.edit.start - a.edit.start || b.index - a.index);
+	for (const { edit } of order) text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+	return {
+		applied,
+		text
+	};
+}
+const problems = (diagnostics) => diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length;
+/**
+* Compiles a document. A warning that carries a fix is applied rather than
+* sent to the model: the fixed source is compiled again, and when it has
+* exactly the problems left that the fixes did not cover, its program is
+* used and those warnings become `info`, as a quoted number on a number prop
+* already is. Diagnostics, procedures and their spans stay those of `source`,
+* which is what the model wrote and what the session keeps.
+*/
+function compilePickle(source, options) {
+	const library = options.library ?? NO_LIBRARY;
+	const result = compileDocument(source, library, options.catalog);
+	const fixes = new Set(result.diagnostics.flatMap((diagnostic) => diagnostic.severity === "warning" && diagnostic.fix !== void 0 ? [diagnostic.fix] : []));
+	if (fixes.size === 0) return result;
+	const patched = applyFixes(source, [...fixes]);
+	const fixed = compileDocument(patched.text, library, options.catalog);
+	const covered = result.diagnostics.filter((diagnostic) => diagnostic.fix !== void 0 && patched.applied.has(diagnostic.fix)).length;
+	if (problems(fixed.diagnostics) !== problems(result.diagnostics) - covered) return result;
+	return {
+		...fixed,
+		diagnostics: result.diagnostics.map((diagnostic) => diagnostic.fix !== void 0 && patched.applied.has(diagnostic.fix) ? {
+			...diagnostic,
+			message: `${diagnostic.message}; the compiler made that change`,
+			severity: "info"
+		} : diagnostic),
+		procedures: result.procedures,
+		reads: result.reads
+	};
+}
+//#endregion
+export { compileLibrary, compilePickle };