@happyvertical/smrt-scanner 0.55.6 → 0.55.8

package/dist/chunks/{scanner-CeTWAIar.js → scanner-BbpPS8Aq.js}

@@ -78,7 +78,7 @@ var DATA_SURFACE_KINDS = /* @__PURE__ */ new Set([
 ]);
 var PLAYBOOK_PLANES = /* @__PURE__ */ new Set(["browser", "server"]);
 var FAILURE_POLICIES = /* @__PURE__ */ new Set(["abort", "continue"]);
-var QUALIFIED_MODEL_PATTERN = /^\S+:\S+$/;
+var QUALIFIED_MODEL_PATTERN$1 = /^\S+:\S+$/;
 function intentToolName(id) {
 	return id.replace(/[.-]/g, "_");
 }
@@ -424,7 +424,7 @@ function playbookDeclarationProblem(declaration, key, steps) {
 	if (enabled !== void 0 && typeof enabled !== "boolean") return `playbook '${key}' declares a non-boolean \`enabled\`, which \`definePlaybook\` rejects rather than coercing \u2014 a truthy '"false"' would otherwise read as enabled.`;
 	for (const step of declaration.steps ?? []) {
 		const record = step;
-		if (record.kind === "operation" && !QUALIFIED_MODEL_PATTERN.test(String(record.model))) return `playbook '${key}' has a step whose model '${String(record.model)}' is not a qualified pair such as '@happyvertical/smrt-commerce:Order'.`;
+		if (record.kind === "operation" && !QUALIFIED_MODEL_PATTERN$1.test(String(record.model))) return `playbook '${key}' has a step whose model '${String(record.model)}' is not a qualified pair such as '@happyvertical/smrt-commerce:Order'.`;
 	}
 }
 function intentIdentityProblem(id) {
@@ -1157,8 +1157,314 @@ var InheritanceResolver = class {
 	}
 };
 //#endregion
+//#region src/recipe-widgets.ts
+var RECIPE_WIDGET_OPTION_TYPES = [
+	"text",
+	"markdown",
+	"identifier",
+	"model",
+	"integer",
+	"number",
+	"boolean",
+	"enum"
+];
+var RECIPE_WIDGET_KEYS = [
+	"kind",
+	"type",
+	"export",
+	"label",
+	"description",
+	"icon",
+	"version",
+	"migrate",
+	"options",
+	"data",
+	"allowedIn",
+	"defaultSpan",
+	"minSpan",
+	"maxSpan"
+];
+var WIDGET_TYPE_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+var OVERVIEW_PAGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,95}$/;
+var OPTION_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9]{0,31}$/;
+var IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
+var MODEL_PATTERN = /^(?:(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*:)?[A-Za-z][A-Za-z0-9_]{0,63}$/;
+var QUALIFIED_MODEL_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*:[A-Za-z][A-Za-z0-9_]{0,63}$/;
+var ICON_PATTERN$1 = /^[A-Za-z][A-Za-z0-9_-]*$/;
+var MARKDOWN_MAX = 1e4;
+var OPTION_KEYS = /* @__PURE__ */ new Set([
+	"key",
+	"type",
+	"label",
+	"help",
+	"required",
+	"default",
+	"min",
+	"max",
+	"maxLength",
+	"choices"
+]);
+function isRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmpty(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+function readOption(raw, at, fail) {
+	if (!isRecord(raw)) {
+		fail(`${at} must be an object literal`);
+		return;
+	}
+	let ok = true;
+	const bad = (message) => {
+		fail(`${at}${message}`);
+		ok = false;
+	};
+	for (const key2 of Object.keys(raw)) if (!OPTION_KEYS.has(key2)) bad(` does not accept \`${key2}\``);
+	const { key, type } = raw;
+	if (typeof key !== "string" || !OPTION_KEY_PATTERN.test(key)) bad(".key must be a camelCase name of at most 32 letters and digits");
+	if (typeof type !== "string" || !RECIPE_WIDGET_OPTION_TYPES.includes(type)) {
+		bad(`.type must be one of ${RECIPE_WIDGET_OPTION_TYPES.join(", ")} (got \`${String(type)}\`)`);
+		return;
+	}
+	if (!nonEmpty(raw.label)) bad(".label must be a non-empty string");
+	if (raw.help !== void 0 && !nonEmpty(raw.help)) bad(".help must be a non-empty string");
+	if (raw.required !== void 0 && typeof raw.required !== "boolean") bad(".required must be a boolean");
+	const numeric = type === "integer" || type === "number";
+	for (const bound of ["min", "max"]) {
+		const value2 = raw[bound];
+		if (value2 === void 0) continue;
+		if (!numeric) bad(`.${bound} applies only to integer and number options`);
+		else if (typeof value2 !== "number" || !Number.isFinite(value2)) bad(`.${bound} must be a finite number`);
+	}
+	if (typeof raw.min === "number" && typeof raw.max === "number" && raw.min > raw.max) bad(".min cannot exceed .max");
+	const textual = type === "text" || type === "markdown";
+	if (raw.maxLength !== void 0) {
+		if (!textual) bad(".maxLength applies only to text and markdown options");
+		else if (typeof raw.maxLength !== "number" || !Number.isSafeInteger(raw.maxLength) || raw.maxLength < 1) bad(".maxLength must be a positive integer");
+	}
+	let choiceValues;
+	if (type === "enum") {
+		const choices = raw.choices;
+		if (!Array.isArray(choices) || choices.length === 0) bad(".choices must be a non-empty list of { value, label }");
+		else {
+			choiceValues = [];
+			choices.forEach((choice, index) => {
+				const where = `.choices[${index}]`;
+				if (!isRecord(choice) || Object.keys(choice).some((k) => k !== "value" && k !== "label")) bad(`${where} must be { value, label } and nothing else`);
+				else if (!nonEmpty(choice.value) || !nonEmpty(choice.label)) bad(`${where} needs a non-empty value and label`);
+				else if (choiceValues?.includes(choice.value)) bad(`${where} repeats the value \`${choice.value}\``);
+				else choiceValues?.push(choice.value);
+			});
+		}
+	} else if (raw.choices !== void 0) bad(".choices applies only to enum options");
+	const value = raw.default;
+	if (value !== void 0) {
+		const mismatch = (what) => bad(`.default must be ${what}`);
+		switch (type) {
+			case "text":
+			case "markdown": {
+				const max = typeof raw.maxLength === "number" ? raw.maxLength : type === "markdown" ? MARKDOWN_MAX : 200;
+				if (typeof value !== "string") mismatch("a string");
+				else if (value.length > max) mismatch(`at most ${max} characters`);
+				break;
+			}
+			case "identifier":
+				if (typeof value !== "string" || !IDENTIFIER_PATTERN.test(value)) mismatch("an identifier (letters, digits, `_`, `.`, `-`)");
+				break;
+			case "model":
+				if (typeof value !== "string" || value.length > 160 || !MODEL_PATTERN.test(value)) mismatch("a model name (`Class`, `pkg:Class` or `@scope/pkg:Class`)");
+				break;
+			case "enum":
+				if (typeof value !== "string" || choiceValues && !choiceValues.includes(value)) mismatch("one of the choices");
+				break;
+			case "boolean":
+				if (typeof value !== "boolean") mismatch("a boolean");
+				break;
+			default: if (typeof value !== "number" || !Number.isFinite(value)) mismatch("a finite number");
+			else if (type === "integer" && !Number.isSafeInteger(value)) mismatch("a safe integer");
+			else if (typeof raw.min === "number" && value < raw.min || typeof raw.max === "number" && value > raw.max) mismatch("within min and max");
+		}
+	}
+	if (!ok) return void 0;
+	const out = {};
+	for (const name of [
+		"key",
+		"type",
+		"label",
+		"help",
+		"required",
+		"default",
+		"min",
+		"max",
+		"maxLength",
+		"choices"
+	]) if (raw[name] !== void 0) out[name] = raw[name];
+	if (type === "enum") out.choices = raw.choices.map((choice) => ({
+		value: choice.value,
+		label: choice.label
+	}));
+	return out;
+}
+function readOptions(raw, at, fail) {
+	if (!Array.isArray(raw) || raw.length === 0) {
+		fail(`${at}.options must be a non-empty list of option objects`);
+		return;
+	}
+	const out = [];
+	const keys = /* @__PURE__ */ new Set();
+	let ok = true;
+	raw.forEach((entry, index) => {
+		const option = readOption(entry, `${at}.options[${index}]`, fail);
+		if (!option) {
+			ok = false;
+			return;
+		}
+		if (keys.has(option.key)) {
+			fail(`${at}.options[${index}].key \`${option.key}\` is already declared`);
+			ok = false;
+			return;
+		}
+		keys.add(option.key);
+		out.push(option);
+	});
+	return ok ? out : void 0;
+}
+function readData(raw, at, fail, readRef) {
+	if (!isRecord(raw)) {
+		fail(`${at}.data must be an object literal`);
+		return;
+	}
+	let ok = true;
+	for (const key of Object.keys(raw)) if (key !== "load" && key !== "models") {
+		fail(`${at}.data does not accept \`${key}\``);
+		ok = false;
+	}
+	const out = {};
+	if (raw.load !== void 0) {
+		const ref = readRef(raw.load, `${at}.data`, "load");
+		if (ref === void 0) ok = false;
+		else out.load = ref;
+	}
+	if (raw.models !== void 0) {
+		const models = raw.models;
+		if (!Array.isArray(models) || models.length === 0) {
+			fail(`${at}.data.models must be a non-empty list of qualified models`);
+			ok = false;
+		} else {
+			const seen = /* @__PURE__ */ new Set();
+			for (const [index, model] of models.entries()) if (typeof model !== "string" || model.length > 160 || !QUALIFIED_MODEL_PATTERN.test(model)) {
+				fail(`${at}.data.models[${index}] must be a qualified class name like \`@scope/pkg:Class\``);
+				ok = false;
+			} else if (seen.has(model)) {
+				fail(`${at}.data.models[${index}] repeats \`${model}\``);
+				ok = false;
+			} else seen.add(model);
+			out.models = [...seen];
+		}
+	}
+	if (ok && !out.load && !out.models) {
+		fail(`${at}.data needs \`load\` or \`models\``);
+		ok = false;
+	}
+	return ok ? out : void 0;
+}
+function readWidgetSurface(entry, at, fail, readRef) {
+	let ok = true;
+	const bad = (message) => {
+		fail(`${at}${message}`);
+		ok = false;
+	};
+	const out = {};
+	const { type } = entry;
+	if (typeof type !== "string" || !WIDGET_TYPE_PATTERN.test(type)) bad(".type must be a lowercase kebab id of at most 32 characters");
+	else out.type = type;
+	if (entry.description !== void 0) if (nonEmpty(entry.description)) out.description = entry.description;
+	else bad(".description must be a non-empty string");
+	if (entry.icon !== void 0) if (typeof entry.icon === "string" && ICON_PATTERN$1.test(entry.icon)) out.icon = entry.icon;
+	else bad(".icon must be an icon name");
+	let version = 1;
+	if (entry.version !== void 0) if (typeof entry.version === "number" && Number.isSafeInteger(entry.version) && entry.version >= 1) {
+		version = entry.version;
+		out.version = entry.version;
+	} else bad(".version must be a positive integer");
+	if (entry.migrate !== void 0) {
+		const ref = readRef(entry.migrate, at, "migrate");
+		if (ref === void 0) ok = false;
+		else if (version < 2) bad(".migrate needs a `version` above 1");
+		else out.migrate = ref;
+	}
+	if (entry.options !== void 0) {
+		const options = readOptions(entry.options, at, fail);
+		if (options) out.options = options;
+		else ok = false;
+	}
+	if (entry.data !== void 0) {
+		const data = readData(entry.data, at, fail, readRef);
+		if (data) out.data = data;
+		else ok = false;
+	}
+	if (entry.allowedIn !== void 0) {
+		const placements = entry.allowedIn;
+		if (!Array.isArray(placements) || placements.length === 0) bad(".allowedIn must be a non-empty list of overview ids");
+		else {
+			const seen = /* @__PURE__ */ new Set();
+			placements.forEach((id, index) => {
+				if (typeof id !== "string" || !OVERVIEW_PAGE_ID_PATTERN.test(id)) bad(`.allowedIn[${index}] must be an overview id like \`events.home\``);
+				else if (seen.has(id)) bad(`.allowedIn[${index}] repeats \`${id}\``);
+				else seen.add(id);
+			});
+			out.allowedIn = [...seen];
+		}
+	}
+	const spans = {
+		minSpan: 1,
+		defaultSpan: 1,
+		maxSpan: 4
+	};
+	for (const name of [
+		"defaultSpan",
+		"minSpan",
+		"maxSpan"
+	]) {
+		const value = entry[name];
+		if (value === void 0) continue;
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 4) bad(`.${name} must be an integer from 1 to 4`);
+		else {
+			out[name] = value;
+			spans[name] = value;
+		}
+	}
+	if (ok && (spans.minSpan > spans.maxSpan || entry.defaultSpan !== void 0 && (spans.defaultSpan < spans.minSpan || spans.defaultSpan > spans.maxSpan))) bad(".minSpan <= .defaultSpan <= .maxSpan must hold");
+	return ok ? out : void 0;
+}
+//#endregion
 //#region src/recipes.ts
 var RECIPE_BASE = "SmrtRecipe";
+var RECIPE_SHELL_SLOTS = [
+	"header.start",
+	"header.center",
+	"header.end",
+	"footer.start",
+	"footer.center",
+	"footer.end",
+	"leftSidebar.header",
+	"leftSidebar.footer",
+	"rightSidebar.header",
+	"rightSidebar.footer"
+];
+var RECIPE_SURFACE_KINDS = [
+	"shell-widget",
+	"route",
+	"settings-panel",
+	"playground",
+	"widget"
+];
+var RECIPE_RUNTIMES = [
+	"browser",
+	"server",
+	"both"
+];
 var CORE_SPECIFIER = "@happyvertical/smrt-core";
 function isCoreSpecifier(source) {
 	return source === CORE_SPECIFIER || source.startsWith(`${CORE_SPECIFIER}/`);
@@ -1171,8 +1477,28 @@ var FIELD_OPTION_KEYS = /* @__PURE__ */ new Set([
 	"help",
 	"order",
 	"visibility",
-	"locked"
+	"locked",
+	"required"
+]);
+var NAV_EXTRA_KEYS = [
+	"icon",
+	"description",
+	"key",
+	"noun"
+];
+var GROUP_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"label",
+	"summary"
+]);
+var SECTION_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"label",
+	"icon",
+	"description"
 ]);
+var SLUG_PATTERN = /^[a-z][a-z0-9_-]*$/;
+var ICON_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
 var VISIBILITIES = /* @__PURE__ */ new Set([
 	"basic",
 	"advanced",
@@ -1413,8 +1739,15 @@ function extractRecipes(input) {
 			models: [],
 			nav: [],
 			requires: [],
+			requiresAny: null,
+			group: null,
+			section: null,
 			options: [],
-			help: null
+			help: null,
+			surfaces: null,
+			providers: null,
+			runtime: null,
+			demoSeed: null
 		};
 		const seen = /* @__PURE__ */ new Set();
 		for (const member of node.body.body) {
@@ -1447,16 +1780,36 @@ function extractRecipes(input) {
 							const fields = objectEntries(entry, "static nav entries");
 							const label = fields.find((field) => field.key === "label");
 							const model = fields.find((field) => field.key === "model");
-							const extra = fields.find((field) => field.key !== "label" && field.key !== "model");
-							if (extra) throw new RecipeReadError(`static nav entries accept only \`label\` and \`model\`, not \`${extra.key}\``, extra.node);
+							const extra = fields.find((field) => field.key !== "label" && field.key !== "model" && field.key !== "filter" && !NAV_EXTRA_KEYS.includes(field.key));
+							if (extra) throw new RecipeReadError(`static nav entries accept only \`label\`, \`model\`, \`icon\`, \`description\`, \`key\`, \`noun\` and \`filter\`, not \`${extra.key}\``, extra.node);
+							const extras = {};
+							for (const name2 of NAV_EXTRA_KEYS) {
+								const found = fields.find((field) => field.key === name2);
+								if (found) extras[name2] = stringValue(found.value, `static nav ${name2}`);
+							}
+							const filter = fields.find((field) => field.key === "filter");
 							if (!label || !model) throw new RecipeReadError("static nav entries need both `label` and `model`", entry);
 							return {
 								label: stringValue(label.value, "static nav label"),
 								model: modelRef(model.value, imports, declaredHere, "static nav model", input.sourceText),
-								line: lineOf(input.sourceText, entry)
+								line: lineOf(input.sourceText, entry),
+								...extras,
+								...filter ? { filter: literalValue(filter.value, "static nav filter") } : {}
 							};
 						});
 						break;
+					case "requiresAny":
+					case "group":
+					case "section":
+					case "surfaces":
+					case "providers":
+					case "runtime":
+					case "demoSeed":
+						recipe[name] = {
+							value: literalValue(value, `static ${name}`),
+							line: lineOf(input.sourceText, member)
+						};
+						break;
 					case "options":
 						recipe.options = objectEntries(value, "static options").map((entry) => ({
 							key: entry.key,
@@ -1616,10 +1969,10 @@ function readModelOptions(raw, model, classes, where, bad) {
 			const entry = {};
 			for (const [hint, hintValue] of Object.entries(hints)) {
 				const at = `${where}.fields.${field}.${hint}`;
-				if (!FIELD_OPTION_KEYS.has(hint)) fail(`${at} is not a field option; use default, label, help, order, visibility, or locked`);
+				if (!FIELD_OPTION_KEYS.has(hint)) fail(`${at} is not a field option; use default, label, help, order, visibility, locked, or required`);
 				else if ((hint === "label" || hint === "help") && typeof hintValue !== "string") fail(`${at} must be a string`);
 				else if (hint === "order" && (typeof hintValue !== "number" || !Number.isFinite(hintValue))) fail(`${at} must be a finite number`);
-				else if (hint === "locked" && typeof hintValue !== "boolean") fail(`${at} must be a boolean`);
+				else if ((hint === "locked" || hint === "required") && typeof hintValue !== "boolean") fail(`${at} must be a boolean`);
 				else if (hint === "visibility" && !(typeof hintValue === "string" && VISIBILITIES.has(hintValue))) fail(`${at} must be one of basic, advanced, hidden`);
 				else entry[hint] = hintValue;
 			}
@@ -1639,6 +1992,298 @@ function readModelOptions(raw, model, classes, where, bad) {
 	} else fail(`${where}.${key} is not a model option; use \`fields\` or \`exposure\``);
 	return ok ? out : void 0;
 }
+function readNavFilter(value, fail) {
+	if (value === void 0) return void 0;
+	if (!isPlainObject(value)) {
+		fail("filter must be an object `{ field, value }`");
+		return;
+	}
+	const extra = Object.keys(value).find((k) => k !== "field" && k !== "value");
+	if (extra) {
+		fail(`filter accepts only \`field\` and \`value\`, not \`${extra}\``);
+		return;
+	}
+	if (typeof value.field !== "string" || typeof value.value !== "string") {
+		fail("filter needs a string `field` and a string `value`");
+		return;
+	}
+	return {
+		field: value.field,
+		value: value.value
+	};
+}
+function readRequiresAny(raw, id, report) {
+	if (!raw.requiresAny) return void 0;
+	const { value, line } = raw.requiresAny;
+	if (!Array.isArray(value) || value.length === 0 || !value.every((alt) => Array.isArray(alt) && alt.length > 0)) {
+		report("requiresAny must be a non-empty list of non-empty id lists, e.g. [['a.b', 'c.d']]", line);
+		return;
+	}
+	const out = [];
+	for (const alt of value) {
+		const ids = [];
+		for (const entry of alt) if (typeof entry !== "string" || entry.length > RECIPE_ID_MAX_LENGTH || !RECIPE_ID_PATTERN.test(entry)) report(`requiresAny entry \`${String(entry)}\` is not a recipe id`, line);
+		else if (entry === id) report("a recipe cannot require itself", line);
+		else if (ids.includes(entry)) report(`requiresAny lists \`${entry}\` more than once`, line);
+		else ids.push(entry);
+		out.push(ids);
+	}
+	return out;
+}
+function readLabelled(raw, name, allowed, report) {
+	if (!raw) return void 0;
+	const { value, line } = raw;
+	if (!isPlainObject(value)) {
+		report(`${name} must be an object literal`, line);
+		return;
+	}
+	const out = {};
+	let ok = true;
+	for (const [key, entry] of Object.entries(value)) if (!allowed.has(key)) {
+		report(`${name} accepts only ${[...allowed].join(", ")}, not \`${key}\``, line);
+		ok = false;
+	} else if (typeof entry !== "string" || entry.trim() === "") {
+		report(`${name}.${key} must be a non-empty string`, line);
+		ok = false;
+	} else out[key] = entry;
+	if (!out.id || !out.label) {
+		if (ok) report(`${name} needs both \`id\` and \`label\``, line);
+		return;
+	}
+	if (!SLUG_PATTERN.test(out.id)) {
+		report(`${name}.id \`${out.id}\` must be lowercase letters, digits, \`-\` or \`_\``, line);
+		return;
+	}
+	if (out.icon !== void 0 && !ICON_PATTERN.test(out.icon)) {
+		report(`${name}.icon \`${out.icon}\` must be an icon name`, line);
+		return;
+	}
+	return ok ? out : void 0;
+}
+var EXPORT_REF_PATTERN = /^((?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:\/[A-Za-z0-9._-]+)*)#([A-Za-z_$][A-Za-z0-9_$]*)$/;
+var ROUTE_PATH_PATTERN = /^\/(?![/\\])[^\s?#\\]*$/;
+var PROVIDER_SLUG_PATTERN = /^[a-z][a-z0-9_-]*$/;
+var SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+var DEMO_SEED_MAX_BYTES = 8192;
+function readExportRef(value, at, report, line, field = "export") {
+	if (typeof value !== "string") {
+		report(`${at}.${field} must be a string like \`pkg/svelte#Component\``, line);
+		return;
+	}
+	const match = EXPORT_REF_PATTERN.exec(value);
+	if (!match || match[1].split("/").some((part) => part === "." || part === ".." || part.endsWith("."))) {
+		report(`${at}.${field} \`${value}\` must be \`<package specifier>#<ExportName>\` (a package specifier, not a relative path)`, line);
+		return;
+	}
+	return value;
+}
+function readNonEmpty(value, at, report, line) {
+	if (typeof value !== "string" || value.trim() === "") {
+		report(`${at} must be a non-empty string`, line);
+		return;
+	}
+	return value;
+}
+function readSurfaces(raw, report) {
+	if (!raw) return void 0;
+	const { value, line } = raw;
+	if (!Array.isArray(value) || value.length === 0) {
+		report("surfaces must be a non-empty array of surface objects", line);
+		return;
+	}
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	let ok = true;
+	value.forEach((entry, index) => {
+		const at = `surfaces[${index}]`;
+		if (!isPlainObject(entry)) {
+			report(`${at} must be an object literal`, line);
+			ok = false;
+			return;
+		}
+		const kind = entry.kind;
+		if (typeof kind !== "string" || !RECIPE_SURFACE_KINDS.includes(kind)) {
+			report(`${at}.kind must be one of ${RECIPE_SURFACE_KINDS.join(", ")} (got \`${String(kind)}\`)`, line);
+			ok = false;
+			return;
+		}
+		const allowed = {
+			"shell-widget": [
+				"kind",
+				"slot",
+				"export",
+				"label",
+				"icon"
+			],
+			route: [
+				"kind",
+				"path",
+				"export",
+				"label"
+			],
+			"settings-panel": [
+				"kind",
+				"export",
+				"label"
+			],
+			playground: [
+				"kind",
+				"export",
+				"label"
+			],
+			widget: [...RECIPE_WIDGET_KEYS]
+		};
+		for (const key of Object.keys(entry)) if (!allowed[kind].includes(key)) {
+			report(`${at} (${kind}) does not accept \`${key}\``, line);
+			ok = false;
+		}
+		const before = ok;
+		const ref = readExportRef(entry.export, at, (m, l) => {
+			report(m, l);
+			ok = false;
+		}, line);
+		const fail = (message) => {
+			report(message, line);
+			ok = false;
+		};
+		let label;
+		if (kind === "playground" && entry.label === void 0) label = void 0;
+		else label = readNonEmpty(entry.label, `${at}.label`, fail, line);
+		let identity = `${kind}:${ref}`;
+		const surface = { kind };
+		if (kind === "shell-widget") {
+			const slot = entry.slot;
+			if (typeof slot !== "string" || !RECIPE_SHELL_SLOTS.includes(slot)) fail(`${at}.slot \`${String(slot)}\` is not a shell slot (${RECIPE_SHELL_SLOTS.join(", ")})`);
+			surface.slot = slot;
+			if (entry.icon !== void 0) if (typeof entry.icon !== "string" || !ICON_PATTERN.test(entry.icon)) fail(`${at}.icon must be an icon name`);
+			else surface.icon = entry.icon;
+			identity = `${identity}@${String(slot)}`;
+		} else if (kind === "route") {
+			const path = entry.path;
+			if (typeof path !== "string" || !ROUTE_PATH_PATTERN.test(path)) fail(`${at}.path must start with \`/\` and contain no whitespace, \`?\` or \`#\``);
+			else if (/%2e|%2f|%5c/i.test(path) || path.slice(1).split("/").some((part, i, parts) => part === "." || part === ".." || part === "" && i < parts.length - 1)) fail(`${at}.path cannot contain \`.\`/\`..\` or empty segments, or encoded separators`);
+			else {
+				surface.path = path;
+				identity = `route-path:${path}`;
+			}
+		} else if (kind === "widget") {
+			const extras = readWidgetSurface(entry, at, fail, (value2, where, field) => readExportRef(value2, where, (m, l) => {
+				report(m, l);
+				ok = false;
+			}, line, field));
+			if (extras) Object.assign(surface, extras);
+			if (typeof entry.type === "string") identity = `widget-type:${entry.type}`;
+		}
+		if (ref !== void 0) {
+			if (seen.has(identity)) fail(`${at} repeats an earlier surface`);
+			seen.add(identity);
+		}
+		if (ok === before && ref !== void 0) {
+			surface.export = ref;
+			if (label !== void 0) surface.label = label;
+			const ordered = { kind };
+			const keyOrder = kind === "widget" ? RECIPE_WIDGET_KEYS : [
+				"slot",
+				"path",
+				"export",
+				"label",
+				"icon"
+			];
+			for (const key of keyOrder) if (surface[key] !== void 0) ordered[key] = surface[key];
+			out.push(ordered);
+		}
+	});
+	return ok ? out : void 0;
+}
+function readProviders(raw, report) {
+	if (!raw) return void 0;
+	const { value, line } = raw;
+	if (!Array.isArray(value) || value.length === 0) {
+		report("providers must be a non-empty array of provider objects", line);
+		return;
+	}
+	const out = [];
+	const ids = /* @__PURE__ */ new Set();
+	let ok = true;
+	const fail = (message) => {
+		report(message, line);
+		ok = false;
+	};
+	value.forEach((entry, index) => {
+		const at = `providers[${index}]`;
+		if (!isPlainObject(entry)) {
+			fail(`${at} must be an object literal`);
+			return;
+		}
+		for (const key of Object.keys(entry)) if (![
+			"id",
+			"kind",
+			"options",
+			"required",
+			"secrets",
+			"browserOptions"
+		].includes(key)) fail(`${at} does not accept \`${key}\``);
+		const { id, kind, options, required, secrets, browserOptions } = entry;
+		if (typeof id !== "string" || !PROVIDER_SLUG_PATTERN.test(id)) fail(`${at}.id must be a lowercase slug`);
+		else if (ids.has(id)) fail(`${at}.id \`${id}\` is declared more than once`);
+		else ids.add(id);
+		if (typeof kind !== "string" || !PROVIDER_SLUG_PATTERN.test(kind)) fail(`${at}.kind must be a lowercase slug such as email, oauth, storage`);
+		if (!Array.isArray(options) || options.length === 0 || !options.every((o) => typeof o === "string" && PROVIDER_SLUG_PATTERN.test(o)) || new Set(options).size !== options.length) fail(`${at}.options must be a non-empty list of distinct lowercase slugs`);
+		if (typeof required !== "boolean") fail(`${at}.required must be written as true or false`);
+		if (secrets !== void 0 && (!Array.isArray(secrets) || !secrets.every((n) => typeof n === "string" && SECRET_NAME_PATTERN.test(n)) || new Set(secrets).size !== secrets.length)) fail(`${at}.secrets must be distinct UPPER_SNAKE names (names, not values)`);
+		if (browserOptions !== void 0 && (!Array.isArray(browserOptions) || browserOptions.length === 0 || new Set(browserOptions).size !== browserOptions.length || !browserOptions.every((o) => typeof o === "string" && Array.isArray(options) && options.includes(o)))) fail(`${at}.browserOptions must be a non-empty list of distinct entries of options`);
+		if (ok) out.push({
+			id,
+			kind,
+			options,
+			required,
+			...secrets ? { secrets } : {},
+			...browserOptions ? { browserOptions } : {}
+		});
+	});
+	return ok ? out : void 0;
+}
+function readRuntime(raw, report) {
+	if (!raw) return void 0;
+	const { value, line } = raw;
+	if (typeof value !== "string" || !RECIPE_RUNTIMES.includes(value)) {
+		report(`runtime must be one of ${RECIPE_RUNTIMES.join(", ")}`, line);
+		return;
+	}
+	return value;
+}
+function readDemoSeed(raw, report) {
+	if (!raw) return void 0;
+	const { value, line } = raw;
+	if (!isPlainObject(value)) {
+		report("demoSeed must be { export } or { data }", line);
+		return;
+	}
+	const keys = Object.keys(value);
+	if (keys.length !== 1 || keys[0] !== "export" && keys[0] !== "data") {
+		report("demoSeed must have exactly one of `export` or `data`", line);
+		return;
+	}
+	if (keys[0] === "export") {
+		const ref = readExportRef(value.export, "demoSeed", report, line);
+		return ref ? { export: ref } : void 0;
+	}
+	const finite = (node) => typeof node === "number" ? Number.isFinite(node) : Array.isArray(node) ? node.every(finite) : isPlainObject(node) ? Object.values(node).every(finite) : true;
+	if (!finite(value.data)) {
+		report("demoSeed.data cannot contain non-finite numbers", line);
+		return;
+	}
+	const size = Buffer.byteLength(JSON.stringify(value.data ?? null));
+	if (value.data === void 0 || value.data === null) {
+		report("demoSeed.data must be JSON data", line);
+		return;
+	}
+	if (size > DEMO_SEED_MAX_BYTES) {
+		report(`demoSeed.data is ${size} bytes; inline seeds are limited to ${DEMO_SEED_MAX_BYTES}, reference a fixture export instead`, line);
+		return;
+	}
+	return { data: value.data };
+}
 function resolveRecipes(raws, classes) {
 	const errors = [];
 	const recipes = [];
@@ -1688,16 +2333,35 @@ function resolveRecipes(raws, classes) {
 				report(`nav entry \`${entry.label}\` points at \`${model.className}\`, which is not listed in models`, entry.line);
 				continue;
 			}
+			const filter = readNavFilter(entry.filter, (message) => report(`nav entry \`${entry.label}\`: ${message}`, entry.line));
+			if (entry.key !== void 0 && !SLUG_PATTERN.test(entry.key)) report(`nav entry \`${entry.label}\`: key \`${entry.key}\` must be lowercase letters, digits, \`-\` or \`_\``, entry.line);
+			if (entry.icon !== void 0 && !ICON_PATTERN.test(entry.icon)) report(`nav entry \`${entry.label}\`: icon \`${entry.icon}\` must be an icon name`, entry.line);
+			for (const text of ["description", "noun"]) if (entry[text] !== void 0 && entry[text]?.trim() === "") report(`nav entry \`${entry.label}\`: ${text} must not be empty`, entry.line);
+			if (filter && entry.key === void 0) report(`nav entry \`${entry.label}\`: a filter needs a key, which names its view`, entry.line);
 			nav.push({
 				label: entry.label,
-				model: model.className
+				model: model.className,
+				...entry.icon !== void 0 ? { icon: entry.icon } : {},
+				...entry.description !== void 0 ? { description: entry.description } : {},
+				...entry.key !== void 0 ? { key: entry.key } : {},
+				...entry.noun !== void 0 ? { noun: entry.noun } : {},
+				...filter ? { filter } : {}
 			});
 		}
+		const viewKeys = /* @__PURE__ */ new Set();
+		for (const entry of nav) {
+			const view = `${entry.model}:${entry.key ?? ""}`;
+			if (viewKeys.has(view)) report(`nav entry \`${entry.label}\` repeats the view of ${entry.model}${entry.key ? ` key \`${entry.key}\`` : ""}; give each extra entry over a model its own key`);
+			viewKeys.add(view);
+		}
 		const requires = [];
 		for (const required of raw.requires) if (required.length > RECIPE_ID_MAX_LENGTH || !RECIPE_ID_PATTERN.test(required)) report(`requires \`${required}\` is not a recipe id`);
 		else if (required === id) report("a recipe cannot require itself");
 		else if (requires.includes(required)) report(`requires lists \`${required}\` more than once`);
 		else requires.push(required);
+		const requiresAny = readRequiresAny(raw, id, report);
+		const group = readLabelled(raw.group, "group", GROUP_KEYS, report);
+		const section = readLabelled(raw.section, "section", SECTION_KEYS, report);
 		let options;
 		for (const entry of raw.options) {
 			const model = byLocal.get(entry.key);
@@ -1712,6 +2376,10 @@ function resolveRecipes(raws, classes) {
 				else options[model.className] = read;
 			}
 		}
+		const surfaces = readSurfaces(raw.surfaces, report);
+		const providers = readProviders(raw.providers, report);
+		const runtime = readRuntime(raw.runtime, report);
+		const demoSeed = readDemoSeed(raw.demoSeed, report);
 		const help = raw.help ? attempt(() => readHelp(raw.help, raw), raw.help.line) : void 0;
 		recipes.push({
 			id,
@@ -1722,9 +2390,52 @@ function resolveRecipes(raws, classes) {
 			models: models.map((model) => model.className),
 			nav,
 			requires,
+			...requiresAny ? { requiresAny } : {},
+			...group ? { group } : {},
+			...section ? { section } : {},
 			...options && Object.keys(options).length > 0 ? { options } : {},
-			...help ? { help } : {}
+			...help ? { help } : {},
+			...surfaces ? { surfaces } : {},
+			...providers ? { providers } : {},
+			...runtime ? { runtime } : {},
+			...demoSeed ? { demoSeed } : {}
+		});
+	}
+	recipes.sort((a, b) => a.id.localeCompare(b.id));
+	const navKeys = /* @__PURE__ */ new Map();
+	const widgetTypes = /* @__PURE__ */ new Map();
+	const labelled = /* @__PURE__ */ new Map();
+	for (const recipe of recipes) {
+		const raw = ids.get(recipe.id);
+		const note = (message) => errors.push({
+			message: `Recipe ${recipe.className}: ${message}`,
+			filePath: raw?.filePath ?? "",
+			line: raw?.line,
+			severity: "error"
 		});
+		for (const entry of recipe.nav) {
+			if (!entry.key) continue;
+			const slot = `${entry.model}:${entry.key}`;
+			const owner = navKeys.get(slot);
+			if (owner && owner !== recipe.id) note(`nav key \`${entry.key}\` over ${entry.model} is already used by recipe ${owner}; layout ids must be unique`);
+			navKeys.set(slot, owner ?? recipe.id);
+		}
+		for (const surface of recipe.surfaces ?? []) {
+			if (surface.kind !== "widget") continue;
+			const owner = widgetTypes.get(surface.type);
+			if (owner && owner !== recipe.id) note(`widget type \`${surface.type}\` is already used by recipe ${owner}; widget types must be unique`);
+			widgetTypes.set(surface.type, owner ?? recipe.id);
+		}
+		for (const [kind, value] of [["group", recipe.group], ["section", recipe.section]]) {
+			if (!value) continue;
+			const slot = `${kind}:${value.id}`;
+			const first = labelled.get(slot);
+			if (first && first.label !== value.label) note(`${kind} \`${value.id}\` is labelled "${value.label}" here but "${first.label}" in recipe ${first.recipe}`);
+			else if (!first) labelled.set(slot, {
+				label: value.label,
+				recipe: recipe.id
+			});
+		}
 	}
 	const byId = new Map(recipes.map((recipe) => [recipe.id, recipe]));
 	const reported = /* @__PURE__ */ new Set();
@@ -2306,13 +3017,13 @@ function reportUnresolvedSpreads(unresolved, filePath, sourceText, errors) {
 		});
 	}
 }
-function extractClassFromNode(node, filePath, sourceText, importAliases, ctx) {
-	if (node.type === "ExportNamedDeclaration" && node.declaration) return extractClassFromNode(node.declaration, filePath, sourceText, importAliases, ctx);
-	if (node.type === "ExportDefaultDeclaration" && node.declaration) return extractClassFromNode(node.declaration, filePath, sourceText, importAliases, ctx);
-	if (node.type === "ClassDeclaration") return extractClassDeclaration(node, filePath, sourceText, importAliases, ctx);
+function extractClassFromNode(node, filePath, sourceText, importAliases, ctx, outerStart) {
+	if (node.type === "ExportNamedDeclaration" && node.declaration) return extractClassFromNode(node.declaration, filePath, sourceText, importAliases, ctx, node.start ?? outerStart);
+	if (node.type === "ExportDefaultDeclaration" && node.declaration) return extractClassFromNode(node.declaration, filePath, sourceText, importAliases, ctx, node.start ?? outerStart);
+	if (node.type === "ClassDeclaration") return extractClassDeclaration(node, filePath, sourceText, importAliases, ctx, outerStart);
 	return null;
 }
-function extractClassDeclaration(node, filePath, sourceText, importAliases, ctx) {
+function extractClassDeclaration(node, filePath, sourceText, importAliases, ctx, outerStart) {
 	const className = node.id?.name || "AnonymousClass";
 	const decorators = node.decorators || [];
 	const smrtDecorator = decorators.find((d) => isSmrtDecorator(d, importAliases));
@@ -2338,6 +3049,11 @@ function extractClassDeclaration(node, filePath, sourceText, importAliases, ctx)
 		const method = extractMethodDefinition(member, sourceText, ctx);
 		if (method) methods.push(method);
 	}
+	const description = (typeof smrtConfig?.description === "string" ? normalizeModelDescription(smrtConfig.description) : void 0) ?? extractClassJsDocDescription(sourceText, className, [
+		node.start,
+		outerStart,
+		...decorators.map((d) => d.start)
+	].filter((n) => typeof n === "number"));
 	return {
 		className,
 		filePath,
@@ -2345,6 +3061,7 @@ function extractClassDeclaration(node, filePath, sourceText, importAliases, ctx)
 		extendsTypeArg,
 		decoratorConfig,
 		hasSmartDecorator,
+		...description ? { description } : {},
 		fields,
 		methods,
 		startLine: node.loc?.start.line || 1,
@@ -2352,6 +3069,59 @@ function extractClassDeclaration(node, filePath, sourceText, importAliases, ctx)
 		...typeof node.body?.start === "number" ? { bodyStart: node.body.start } : {}
 	};
 }
+var MODEL_DESCRIPTION_MAX = 200;
+function normalizeModelDescription(raw) {
+	const text = raw.replace(/\s+/g, " ").trim();
+	if (!text) return void 0;
+	if (text.length <= MODEL_DESCRIPTION_MAX) return text;
+	const head = text.slice(0, MODEL_DESCRIPTION_MAX);
+	const sentenceEnd = Math.max(head.lastIndexOf(". "), head.lastIndexOf("! "), head.lastIndexOf("? "));
+	if (sentenceEnd > 0) return head.slice(0, sentenceEnd + 1);
+	const wordEnd = head.lastIndexOf(" ");
+	return `${(wordEnd > 0 ? head.slice(0, wordEnd) : head).replace(/[,;:\s]+$/, "")}\u2026`;
+}
+function extractClassJsDocDescription(sourceText, className, anchors) {
+	if (anchors.length === 0) return void 0;
+	const before = sourceText.slice(0, Math.min(...anchors)).trimEnd();
+	if (!before.endsWith("*/")) return void 0;
+	const open = before.lastIndexOf("/**");
+	if (open < 0 || before.indexOf("*/", open) !== before.length - 2) return;
+	return summarizeJsDoc(before.slice(open, before.length), className);
+}
+function summarizeJsDoc(block, className) {
+	const lines = block.replace(/^\/\*\*/, "").replace(/\*\/$/, "").split("\n").map((line) => line.replace(/^\s*\*\s?/, "").trimEnd());
+	const summary = [];
+	let internal = false;
+	let inFence = false;
+	for (const line of lines) {
+		if (/^\s*@internal\b/.test(line)) internal = true;
+		if (/^\s*```/.test(line)) {
+			inFence = !inFence;
+			continue;
+		}
+		if (inFence) continue;
+		if (/^\s*@\w+/.test(line)) {
+			summary.push("\0");
+			continue;
+		}
+		summary.push(line);
+	}
+	if (internal) return void 0;
+	const paragraph = [];
+	for (const line of summary) {
+		if (line === "\0") break;
+		if (line.trim() === "") {
+			if (paragraph.length > 0) break;
+			continue;
+		}
+		paragraph.push(line.trim());
+	}
+	let text = paragraph.join(" ");
+	const escaped = className.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	text = text.replace(new RegExp(`^${escaped}\\s*(?:[-\u2013\u2014:]+)\\s*`), "").replace(/\{@(?:link|linkcode|linkplain)\s+([^}|\s]+)(?:[|\s]+([^}]*))?\}/g, (_m, target, label) => label?.trim() ? label.trim() : target).replace(/\{@\w+\s*([^}]*)\}/g, "$1").replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/`([^`]*)`/g, "$1").replace(/<\/?[a-zA-Z][^>]*>/g, "").replace(/(\*\*|__)(.+?)\1/g, "$2");
+	if (text.length > 0) text = text[0].toUpperCase() + text.slice(1);
+	return normalizeModelDescription(text);
+}
 function isSmrtDecorator(decorator, importAliases) {
 	return isNamedDecorator(decorator, "smrt", importAliases);
 }
@@ -2959,7 +3729,7 @@ var ManifestAdapter = class ManifestAdapter {
 			...recipe,
 			models: recipe.models.map(qualify),
 			nav: recipe.nav.map((entry) => ({
-				label: entry.label,
+				...entry,
 				model: qualify(entry.model)
 			})),
 			...recipe.options ? { options: Object.fromEntries(Object.entries(recipe.options).map(([model, value]) => [qualify(model), value])) } : {}
@@ -3023,7 +3793,7 @@ var ManifestAdapter = class ManifestAdapter {
 			const converted = this.convertMethod(method);
 			if (converted) methods[method.name] = converted;
 		}
-		const collection = this.pluralize(classDef.className);
+		const collection = typeof classDef.decoratorConfig?.collection === "string" ? classDef.decoratorConfig.collection : this.pluralize(classDef.className);
 		const packageName = options.packageName || classDef.packageName;
 		const qualifiedName = packageName ? createQualifiedName(packageName, classDef.className) : void 0;
 		return {
@@ -3031,6 +3801,7 @@ var ManifestAdapter = class ManifestAdapter {
 			className: classDef.className,
 			qualifiedName,
 			collection,
+			...classDef.description ? { description: classDef.description } : {},
 			filePath: classDef.filePath,
 			packageName: packageName || void 0,
 			fields,
@@ -3234,7 +4005,8 @@ var ManifestAdapter = class ManifestAdapter {
 				"description",
 				"default",
 				"constraint",
-				"onDelete"
+				"onDelete",
+				"onUpdate"
 			];
 			if (parsedOptions) {
 				for (const key of META_KEYS) if (parsedOptions[key] !== void 0) meta[key] = parsedOptions[key];
@@ -3283,7 +4055,8 @@ var ManifestAdapter = class ManifestAdapter {
 				"default",
 				"indexed",
 				"idType",
-				"onDelete"
+				"onDelete",
+				"onUpdate"
 			];
 			if (parsedOptions) {
 				for (const key of META_KEYS) if (parsedOptions[key] !== void 0) meta[key] = parsedOptions[key];
@@ -4138,4 +4911,4 @@ var OxcScanner = class {
 //#endregion
 export { mergeAgentSurfaces as C, isPrunedAgentSurfacePath as S, sourceMayDeclareAgentSurface as T, relativeGlobToCwd as _, parseAgentSurfaceFile as a, extractAgentSurface as b, parseSource as c, resolveRecipes as d, sourceMayDeclareRecipe as f, normalizeGlobSeparators as g, discoverSourceFiles as h, extractSmrtImports as i, deriveHelpFieldRefs as l, resolveEnumValues as m, parseUiSelectorsFile as n, parseFile as o, InheritanceResolver as p, ManifestAdapter as r, parseRecipeFile as s, OxcScanner as t, extractRecipes as u, checkAgentSurfaceToolNames as v, scanSvelteAgentSurface as w, isAgentSurfaceSourcePath as x, emptyAgentSurface as y };
 
-//# sourceMappingURL=scanner-CeTWAIar.js.map
+//# sourceMappingURL=scanner-BbpPS8Aq.js.map