@shop-on/theme-contract 0.4.0 → 0.6.0

package/dist/editor-tools/apply.js

@@ -0,0 +1,544 @@
+import { resolveContainerAtPath } from "../block-path.js";
+import { buildBlockInstance, buildSectionInstance } from "../document.js";
+import { parsePaletteRef } from "../color-palette.js";
+import { diffDocument } from "../ops.js";
+import { MAX_BLOCKS_PER_TEMPLATE, maxBlockDepth, templateCounts } from "../template-limits.js";
+import { isSectionAddableInGroup, isSectionEnabledOnTemplate } from "../section-scope.js";
+import { allowedChildBlockTypes } from "../block-allowlist.js";
+import { EDITOR_TOOL_SCHEMAS, MAX_TEXT_PARAM_BYTES, isEditorToolName } from "./args.js";
+import { checkRecipe, recipeSummary, substituteParams } from "./recipes.js";
+import { prepareSettingValue } from "./coerce.js";
+import { digestInstance, digestSchemas, digestSettings, digestTemplate } from "./digest.js";
+//#region src/editor-tools/apply.ts
+var Refusal = class {
+	reason;
+	constructor(reason) {
+		this.reason = reason;
+	}
+};
+function refuse(reason) {
+	throw new Refusal(reason);
+}
+const defaultIdFor = (type) => `${type}_${crypto.randomUUID().slice(0, 8)}`;
+function locate(doc, scope) {
+	if ("template_id" in scope) {
+		const entry = Object.hasOwn(doc.templates, scope.template_id) ? doc.templates[scope.template_id] : void 0;
+		return entry ? {
+			kind: "template",
+			id: scope.template_id,
+			entry
+		} : refuse("template not found");
+	}
+	const entry = Object.hasOwn(doc.groups, scope.group) ? doc.groups[scope.group] : void 0;
+	return entry ? {
+		kind: "group",
+		id: scope.group,
+		entry
+	} : refuse("group not found");
+}
+function withEntry(doc, loc, entry) {
+	return loc.kind === "template" ? {
+		...doc,
+		templates: {
+			...doc.templates,
+			[loc.id]: entry
+		}
+	} : {
+		...doc,
+		groups: {
+			...doc.groups,
+			[loc.id]: entry
+		}
+	};
+}
+function sectionAt(loc, sectionId) {
+	return Object.hasOwn(loc.entry.sections, sectionId) ? loc.entry.sections[sectionId] : refuse("section not found");
+}
+function sectionSchema(schemas, type) {
+	return schemas.sections.find((s) => s.type === type);
+}
+function blockSchema(schemas, type) {
+	return schemas.blocks.find((b) => b.type === type) ?? schemas.blocks.find((b) => b.type === type.replace(/^_/, ""));
+}
+function containerSchema(schemas, container, blockPath) {
+	return blockPath.length === 0 ? sectionSchema(schemas, container.type) : blockSchema(schemas, container.type);
+}
+function placeable(schema, loc) {
+	return loc.kind === "template" ? isSectionEnabledOnTemplate(schema, loc.id) : isSectionAddableInGroup(schema, loc.id);
+}
+function updateAt(node, path, fn) {
+	if (path.length === 0) return fn(node);
+	const [head, ...rest] = path;
+	const child = node.blocks[head];
+	return {
+		...node,
+		blocks: {
+			...node.blocks,
+			[head]: updateAt(child, rest, fn)
+		}
+	};
+}
+function stampApp(node, schema) {
+	if (schema?.source !== "app") return;
+	node.source = "app";
+	node.appId = schema.appId;
+	node.tag = schema.tag;
+	node.scriptUrl = schema.scriptUrl;
+}
+function stampAppBlocks(node, schemas) {
+	for (const child of Object.values(node.blocks ?? {})) {
+		stampApp(child, blockSchema(schemas, child.type));
+		stampAppBlocks(child, schemas);
+	}
+}
+function isPermutation(order, current) {
+	return order.length === current.length && [...order].sort().join("\n") === [...current].sort().join("\n");
+}
+/** The caps an add may not push an entry past. An entry already over one (a
+*  peer's edit) can still shrink. */
+function capRefusal(prev, next) {
+	const a = templateCounts(prev);
+	const b = templateCounts(next);
+	if (b.sections > 25 && b.sections > a.sections) return `a template holds at most 25 sections`;
+	if (b.blocks > 1250 && b.blocks > a.blocks) return `a template holds at most ${MAX_BLOCKS_PER_TEMPLATE} blocks`;
+	const depth = maxBlockDepth(next);
+	if (depth > 8 && depth > maxBlockDepth(prev)) return `blocks nest at most 8 deep`;
+	return null;
+}
+function insertAt(order, ids, index) {
+	const at = index === void 0 ? order.length : Math.min(index, order.length);
+	return [
+		...order.slice(0, at),
+		...ids,
+		...order.slice(at)
+	];
+}
+function getBlockSchemaFn(schemas) {
+	return (type) => blockSchema(schemas, type);
+}
+function buildSection(ctx, schema, preset) {
+	const section = buildSectionInstance({
+		type: schema.type,
+		sectionSchema: schema,
+		getBlockSchema: getBlockSchemaFn(ctx.schemas),
+		preset,
+		idFor: ctx.idFor ?? defaultIdFor
+	});
+	stampApp(section, schema);
+	stampAppBlocks(section, ctx.schemas);
+	return section;
+}
+function valueContext(ctx) {
+	return {
+		themeSettings: ctx.doc.settings,
+		sanitizeRichText: ctx.sanitizeRichText,
+		images: ctx.images,
+		fonts: ctx.fonts
+	};
+}
+function prepared(where, settings, schemaSettings, params, vctx) {
+	const out = {};
+	for (const [id, value] of Object.entries(settings ?? {})) {
+		const setting = schemaSettings.find((s) => s.id === id);
+		const raw = typeof value === "string" ? substituteParams(value, params) : value;
+		const res = prepareSettingValue(setting, raw, vctx);
+		if (!res.ok) refuse(`${where}.settings.${id}: ${res.reason}`);
+		out[id] = res.value;
+	}
+	return out;
+}
+function recipeBlockDefs(where, blocks, ctx, params, vctx) {
+	return blocks.map((block, i) => {
+		const at = `${where}.blocks[${i}]`;
+		const schema = blockSchema(ctx.schemas, block.type);
+		const preset = schema.presets?.[0];
+		return {
+			type: block.type,
+			settings: {
+				...preset?.settings,
+				...prepared(at, block.settings, schema.settings, params, vctx)
+			},
+			blocks: block.blocks ? recipeBlockDefs(at, block.blocks, ctx, params, vctx) : preset?.blocks
+		};
+	});
+}
+function recipeParams(recipe, given) {
+	const declared = recipe.params ?? {};
+	for (const name of Object.keys(given)) if (!Object.hasOwn(declared, name)) refuse(`unknown param ${name}`);
+	const out = {};
+	for (const [name, param] of Object.entries(declared)) {
+		const value = Object.hasOwn(given, name) ? given[name] : param.default;
+		if (value === void 0 || value === "") {
+			if (param.required) refuse(`missing required param ${name}`);
+			out[name] = "";
+			continue;
+		}
+		const str = String(value);
+		switch (param.type) {
+			case "text":
+				if (new TextEncoder().encode(str).length > 2048) refuse(`param ${name} is over ${MAX_TEXT_PARAM_BYTES} bytes`);
+				break;
+			case "number":
+				if (str.trim() === "" || !Number.isFinite(Number(str))) refuse(`param ${name} must be a number`);
+				break;
+			case "product":
+			case "collection": if (!/^[\p{L}\p{N}][\p{L}\p{N}_-]{0,254}$/u.test(str)) refuse(`param ${name} must be a ${param.type} handle`);
+		}
+		out[name] = str;
+	}
+	return out;
+}
+/**
+* A recipe's sections, built and coerced as `add_section` and
+* `update_*_setting` would build and coerce them, keyed by their new ids in
+* recipe order. Refuses the whole recipe at the first bad section, block,
+* setting or param.
+*/
+function expandRecipe(recipe, params, ctx, scope) {
+	try {
+		const bad = checkRecipe(recipe, ctx.schemas, scope);
+		if (bad) refuse(bad);
+		const values = recipeParams(recipe, params);
+		const vctx = valueContext(ctx);
+		const idFor = ctx.idFor ?? defaultIdFor;
+		return {
+			ok: true,
+			sections: recipe.sections.map((section, i) => {
+				const at = `sections[${i}]`;
+				const schema = sectionSchema(ctx.schemas, section.type);
+				const preset = schema.presets?.[0];
+				const settings = {
+					...preset?.settings,
+					...prepared(at, section.settings, schema.settings, values, vctx)
+				};
+				const blocks = section.blocks ? [...(schema.blocks ?? []).filter((b) => b.static), ...recipeBlockDefs(at, section.blocks, ctx, values, vctx)] : preset?.blocks;
+				return [idFor(section.type), buildSection(ctx, schema, {
+					settings,
+					blocks
+				})];
+			})
+		};
+	} catch (e) {
+		if (e instanceof Refusal) return {
+			ok: false,
+			reason: e.reason
+		};
+		throw e;
+	}
+}
+function settingWrite(ctx, loc, sectionId, blockPath, settingId, value) {
+	const section = sectionAt(loc, sectionId);
+	const node = resolveContainerAtPath(section, blockPath) ?? refuse("block not found");
+	const setting = (blockPath.length === 0 && node === section ? sectionSchema(ctx.schemas, node.type) : blockSchema(ctx.schemas, node.type))?.settings?.find((s) => s.id === settingId) ?? refuse(`unknown setting id ${settingId}`);
+	const res = prepareSettingValue(setting, value, valueContext(ctx));
+	if (!res.ok) refuse(res.reason);
+	if (Object.hasOwn(node.settings ?? {}, settingId) && node.settings[settingId] === res.value) return { result: { unchanged: true } };
+	const nextSection = updateAt(section, blockPath, (c) => ({
+		...c,
+		settings: {
+			...c.settings,
+			[settingId]: res.value
+		}
+	}));
+	const entry = {
+		...loc.entry,
+		sections: {
+			...loc.entry.sections,
+			[sectionId]: nextSection
+		}
+	};
+	return {
+		next: withEntry(ctx.doc, loc, entry),
+		result: {}
+	};
+}
+/** `block_path` + `block_id` → the path of the block itself. */
+const blockTarget = (path, id) => [...path ?? [], id];
+const HANDLERS = {
+	list_templates: (_args, ctx) => ({ result: { data: {
+		templates: Object.keys(ctx.doc.templates).sort(),
+		groups: Object.keys(ctx.doc.groups).sort()
+	} } }),
+	get_template: (args, ctx) => ({ result: digestTemplate(ctx.doc, args.scope) ?? refuse(notFound(args.scope)) }),
+	get_theme_settings: (_args, ctx) => ({ result: digestSettings(ctx.doc, ctx.schemas.settingsSchema) }),
+	list_section_types: (args, ctx) => {
+		const loc = locate(ctx.doc, args.scope);
+		return { result: { data: ctx.schemas.sections.filter((s) => placeable(s, loc)).map((s) => ({
+			type: s.type,
+			...s.name ? { name: s.name } : {},
+			...s.max_blocks !== void 0 ? { max_blocks: s.max_blocks } : {}
+		})) } };
+	},
+	get_schemas: (args, ctx) => {
+		const types = [...new Set(args.types)];
+		const digestCtx = {
+			kind: args.kind,
+			blockSchemas: ctx.schemas.blocks
+		};
+		const schemas = args.kind === "section" ? ctx.schemas.sections : ctx.schemas.blocks;
+		return { result: { data: digestSchemas(types, schemas, digestCtx) } };
+	},
+	get_theme_guide: (_args, ctx) => ({ result: { data: {
+		guide: ctx.guide ?? "",
+		recipes: ctx.recipes.map((r) => ({
+			handle: r.handle,
+			name: r.name,
+			...r.description ? { description: r.description } : {}
+		}))
+	} } }),
+	list_recipes: (_args, ctx) => ({ result: { data: ctx.recipes.map(recipeSummary) } }),
+	get_seq: () => ({ result: {} }),
+	add_section: (args, ctx) => {
+		const loc = locate(ctx.doc, args.scope);
+		const schema = sectionSchema(ctx.schemas, args.type) ?? refuse(`unknown section type ${args.type}`);
+		if (!placeable(schema, loc)) refuse(`section type ${args.type} is not allowed in this ${loc.kind}`);
+		const preset = args.preset === void 0 ? schema.presets?.[0] : schema.presets?.[args.preset] ?? refuse(`section type ${args.type} has no preset ${args.preset}`);
+		const id = (ctx.idFor ?? defaultIdFor)(args.type);
+		const section = buildSection(ctx, schema, preset);
+		const entry = {
+			...loc.entry,
+			sections: {
+				...loc.entry.sections,
+				[id]: section
+			},
+			order: insertAt(loc.entry.order, [id], args.index)
+		};
+		const cap = capRefusal(loc.entry, entry);
+		if (cap) refuse(cap);
+		return {
+			next: withEntry(ctx.doc, loc, entry),
+			result: {
+				id,
+				...digestInstance(id, section)
+			}
+		};
+	},
+	delete_section: (args, ctx) => {
+		const loc = locate(ctx.doc, args.scope);
+		sectionAt(loc, args.section_id);
+		const { [args.section_id]: _removed, ...sections } = loc.entry.sections;
+		const entry = {
+			...loc.entry,
+			sections,
+			order: loc.entry.order.filter((id) => id !== args.section_id)
+		};
+		return {
+			next: withEntry(ctx.doc, loc, entry),
+			result: {}
+		};
+	},
+	reorder_sections: (args, ctx) => {
+		const loc = locate(ctx.doc, args.scope);
+		if (!isPermutation(args.order, loc.entry.order)) refuse("order must be a permutation of the current section ids");
+		if (args.order.every((id, i) => id === loc.entry.order[i])) return { result: { unchanged: true } };
+		return {
+			next: withEntry(ctx.doc, loc, {
+				...loc.entry,
+				order: args.order
+			}),
+			result: {}
+		};
+	},
+	add_block: (args, ctx) => {
+		const loc = locate(ctx.doc, args.scope);
+		const path = args.block_path ?? [];
+		const section = sectionAt(loc, args.section_id);
+		const container = resolveContainerAtPath(section, path) ?? refuse("section or container block not found");
+		const schema = containerSchema(ctx.schemas, container, path);
+		const allowed = allowedChildBlockTypes(schema, ctx.schemas.blocks, { depth: path.length });
+		if (!allowed.includes(args.type)) refuse(`block type not allowed here; allowed: ${allowed.join(", ") || "none"}`);
+		const max = schema?.max_blocks;
+		if (typeof max === "number" && (container.block_order?.length ?? 0) >= max) refuse(`this container holds at most ${max} blocks`);
+		const typeSchema = blockSchema(ctx.schemas, args.type);
+		const idFor = ctx.idFor ?? defaultIdFor;
+		const id = idFor(args.type);
+		const block = buildBlockInstance({
+			type: args.type,
+			getBlockSchema: getBlockSchemaFn(ctx.schemas),
+			preset: typeSchema?.presets?.[0],
+			idFor
+		});
+		stampApp(block, typeSchema);
+		stampAppBlocks(block, ctx.schemas);
+		const nextSection = updateAt(section, path, (c) => ({
+			...c,
+			blocks: {
+				...c.blocks,
+				[id]: block
+			},
+			block_order: [...c.block_order ?? [], id]
+		}));
+		const entry = {
+			...loc.entry,
+			sections: {
+				...loc.entry.sections,
+				[args.section_id]: nextSection
+			}
+		};
+		const cap = capRefusal(loc.entry, entry);
+		if (cap) refuse(cap);
+		return {
+			next: withEntry(ctx.doc, loc, entry),
+			result: {
+				id,
+				...digestInstance(id, block)
+			}
+		};
+	},
+	delete_block: (args, ctx) => {
+		const loc = locate(ctx.doc, args.scope);
+		const path = args.block_path ?? [];
+		const section = sectionAt(loc, args.section_id);
+		const container = resolveContainerAtPath(section, path);
+		if ((container?.blocks && Object.hasOwn(container.blocks, args.block_id) ? container.blocks[args.block_id] : refuse("block not found"))?.static) refuse("a static block can't be deleted");
+		const nextSection = updateAt(section, path, (c) => {
+			const { [args.block_id]: _removed, ...blocks } = c.blocks ?? {};
+			return {
+				...c,
+				blocks,
+				block_order: (c.block_order ?? []).filter((id) => id !== args.block_id)
+			};
+		});
+		const entry = {
+			...loc.entry,
+			sections: {
+				...loc.entry.sections,
+				[args.section_id]: nextSection
+			}
+		};
+		return {
+			next: withEntry(ctx.doc, loc, entry),
+			result: {}
+		};
+	},
+	reorder_blocks: (args, ctx) => {
+		const loc = locate(ctx.doc, args.scope);
+		const path = args.block_path ?? [];
+		const section = sectionAt(loc, args.section_id);
+		const current = (resolveContainerAtPath(section, path) ?? refuse("section or container block not found")).block_order ?? [];
+		if (!isPermutation(args.order, current)) refuse("order must be a permutation of the container's block_order (static blocks never move)");
+		if (args.order.every((id, i) => id === current[i])) return { result: { unchanged: true } };
+		const nextSection = updateAt(section, path, (c) => ({
+			...c,
+			block_order: args.order
+		}));
+		const entry = {
+			...loc.entry,
+			sections: {
+				...loc.entry.sections,
+				[args.section_id]: nextSection
+			}
+		};
+		return {
+			next: withEntry(ctx.doc, loc, entry),
+			result: {}
+		};
+	},
+	update_section_setting: (args, ctx) => settingWrite(ctx, locate(ctx.doc, args.scope), args.section_id, [], args.setting_id, args.value),
+	update_block_setting: (args, ctx) => settingWrite(ctx, locate(ctx.doc, args.scope), args.section_id, blockTarget(args.block_path, args.block_id), args.setting_id, args.value),
+	update_theme_setting: (args, ctx) => {
+		const id = args.setting_id;
+		const settings = ctx.doc.settings;
+		const setting = ctx.schemas.settingsSchema.flatMap((panel) => panel.settings ?? []).find((s) => s.id === id);
+		if (!setting) {
+			if (!id.includes(".") || !Object.hasOwn(settings, id)) refuse(`unknown theme setting ${id}`);
+			if (id.endsWith(".label")) refuse(`theme setting ${id} is not editable`);
+			if (String(args.value).trim() === "") refuse(`theme setting ${id} can't be cleared`);
+			if (id.startsWith("color_palette.") && parsePaletteRef(args.value) !== null) refuse("a palette color must be a literal color, not a palette ref");
+		}
+		const res = prepareSettingValue(setting ?? { type: "color" }, args.value, valueContext(ctx));
+		if (!res.ok) refuse(res.reason);
+		if (Object.hasOwn(settings, id) && settings[id] === res.value) return { result: { unchanged: true } };
+		return {
+			next: {
+				...ctx.doc,
+				settings: {
+					...settings,
+					[id]: res.value
+				}
+			},
+			result: {}
+		};
+	},
+	apply_recipe: (args, ctx) => {
+		const loc = locate(ctx.doc, args.scope);
+		const recipe = ctx.recipes.find((r) => r.handle === args.handle) ?? refuse(`no recipe ${args.handle}`);
+		const position = args.position ?? recipe.position ?? "append";
+		if (position === "replace" && args.expected_seq === void 0) refuse("position replace needs expected_seq: read the template first");
+		const expanded = expandRecipe(recipe, Object.fromEntries((args.params ?? []).map((p) => [p.name, p.value])), ctx, args.scope);
+		if (!expanded.ok) refuse(expanded.reason);
+		const built = expanded.sections;
+		const ids = built.map(([id]) => id);
+		const added = Object.fromEntries(built);
+		let entry;
+		if (position === "replace") {
+			const kept = Object.fromEntries(Object.entries(loc.entry.sections).filter(([id]) => !loc.entry.order.includes(id)));
+			entry = {
+				...loc.entry,
+				sections: {
+					...kept,
+					...added
+				},
+				order: ids
+			};
+		} else entry = {
+			...loc.entry,
+			sections: {
+				...loc.entry.sections,
+				...added
+			},
+			order: insertAt(loc.entry.order, ids, position === "prepend" ? 0 : void 0)
+		};
+		const cap = capRefusal(loc.entry, entry);
+		if (cap) refuse(cap);
+		return {
+			next: withEntry(ctx.doc, loc, entry),
+			result: {
+				section_ids: ids,
+				position
+			}
+		};
+	}
+};
+function notFound(scope) {
+	return "template_id" in scope ? "template not found" : "group not found";
+}
+function argsRefusal(error) {
+	const issue = error.issues[0];
+	const path = issue.path.map(String).join(".");
+	return `invalid arguments${path ? ` at ${path}` : ""}: ${issue.message}`;
+}
+/**
+* Runs one editor tool against a document: the ops that make the edit (what
+* the admin would have sent for it, via `diffDocument`) and the result the
+* model sees, or a refusal. Pure: no I/O, and `ctx.doc` is never mutated.
+*/
+function applyEditorTool(name, args, ctx) {
+	if (!isEditorToolName(name)) return {
+		ok: false,
+		reason: `unknown tool ${name}`
+	};
+	const parsed = EDITOR_TOOL_SCHEMAS[name].safeParse(args ?? {});
+	if (!parsed.success) return {
+		ok: false,
+		reason: argsRefusal(parsed.error)
+	};
+	try {
+		const handler = HANDLERS[name];
+		const out = handler(parsed.data, ctx);
+		const ops = out.next ? diffDocument(ctx.doc, out.next) : [];
+		return {
+			ok: true,
+			ops,
+			result: out.next && ops.length === 0 ? { unchanged: true } : out.result ?? {}
+		};
+	} catch (e) {
+		if (e instanceof Refusal) return {
+			ok: false,
+			reason: e.reason
+		};
+		throw e;
+	}
+}
+//#endregion
+export { applyEditorTool, expandRecipe };

package/dist/editor-tools/args.d.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+//#region src/editor-tools/args.d.ts
+export declare const ScopeSchema: z.ZodUnion<readonly [z.ZodObject<{
+  template_id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  group: z.ZodString;
+}, z.core.$strict>]>;
+/** A recipe text param's cap, in bytes (the engine checks bytes). */
+export declare const MAX_TEXT_PARAM_BYTES: number;
+export declare const EDITOR_TOOL_SCHEMAS: {
+  readonly list_templates: z.ZodObject<{}, z.core.$strict>;
+  readonly get_template: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+  }, z.core.$strict>;
+  readonly get_theme_settings: z.ZodObject<{}, z.core.$strict>;
+  readonly list_section_types: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+  }, z.core.$strict>;
+  readonly get_schemas: z.ZodObject<{
+    kind: z.ZodEnum<{
+      block: "block";
+      section: "section";
+    }>;
+    types: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>;
+  readonly get_theme_guide: z.ZodObject<{}, z.core.$strict>;
+  readonly list_recipes: z.ZodObject<{}, z.core.$strict>;
+  readonly get_seq: z.ZodObject<{}, z.core.$strict>;
+  readonly add_section: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    type: z.ZodString;
+    index: z.ZodOptional<z.ZodNumber>;
+    preset: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>;
+  readonly delete_section: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    section_id: z.ZodString;
+  }, z.core.$strict>;
+  readonly reorder_sections: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    order: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>;
+  readonly add_block: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    section_id: z.ZodString;
+    block_path: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    type: z.ZodString;
+  }, z.core.$strict>;
+  readonly delete_block: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    section_id: z.ZodString;
+    block_path: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    block_id: z.ZodString;
+  }, z.core.$strict>;
+  readonly reorder_blocks: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    section_id: z.ZodString;
+    block_path: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    order: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>;
+  readonly update_section_setting: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    section_id: z.ZodString;
+    setting_id: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strict>;
+  readonly update_block_setting: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    section_id: z.ZodString;
+    block_path: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    block_id: z.ZodString;
+    setting_id: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strict>;
+  readonly update_theme_setting: z.ZodObject<{
+    setting_id: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strict>;
+  readonly apply_recipe: z.ZodObject<{
+    scope: z.ZodUnion<readonly [z.ZodObject<{
+      template_id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      group: z.ZodString;
+    }, z.core.$strict>]>;
+    handle: z.ZodString;
+    params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strict>>>;
+    position: z.ZodOptional<z.ZodEnum<{
+      append: "append";
+      prepend: "prepend";
+      replace: "replace";
+    }>>;
+    expected_seq: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>;
+};
+export type EditorToolName = keyof typeof EDITOR_TOOL_SCHEMAS;
+export type EditorToolArgs<N extends EditorToolName> = z.infer<(typeof EDITOR_TOOL_SCHEMAS)[N]>;
+export declare const EDITOR_TOOL_NAMES: EditorToolName[];
+export declare function isEditorToolName(name: string): name is EditorToolName;
+type ToolMeta = {
+  access: "read" | "write";
+  destructive: boolean;
+  idempotent: boolean;
+  description: string;
+  /** False for a tool that answers from the document alone: hosts skip
+   *  loading schemas (and the apps service) for it. Not in the listing. */
+  needsSchemas: boolean;
+};
+export declare const EDITOR_TOOL_META: Record<EditorToolName, ToolMeta>;
+//#endregion
+export {};