@shop-on/theme-contract 0.5.0 → 0.7.0

package/dist/metafield-binding.js

@@ -1,5 +1,6 @@
 import { walkBlocks, walkSections } from "./resolvers.js";
 import { metaobjectIdFromGid } from "./metaobject-gid.js";
+import { stripInlineTokenSentinels } from "./richtext.js";
 //#region src/metafield-binding.ts
 const metafieldTypeToSettingTypes = {
 	SINGLE_LINE_TEXT: [
@@ -204,17 +205,47 @@ function applyWholeValueBindings(template, resolve, opts) {
 		}
 	}
 }
-/** Overlay resolved product-metafield values onto a template's settings — for
-* each `product_metafield` binding, `metafields["namespace.key"]`. PDP-only (the
-* route product context); other sources are skipped. See applyWholeValueBindings. */
+const ROUTE_METAFIELD_SOURCES = [
+	"collection_metafield",
+	"page_metafield",
+	"blog_metafield",
+	"article_metafield"
+];
+/** The route resource each source reads — the key of that resource on the
+* loader's request and the editor's template families. */
+const ROUTE_METAFIELD_RESOURCE = {
+	collection_metafield: "collection",
+	page_metafield: "page",
+	blog_metafield: "blog",
+	article_metafield: "article"
+};
+const RESOURCE_METAFIELD_SOURCES = ["product_metafield", ...ROUTE_METAFIELD_SOURCES];
+const RESOURCE_METAFIELD_SOURCE_SET = new Set(RESOURCE_METAFIELD_SOURCES);
+/** True for a binding/descriptor that reads a route resource's metafield. */
+function isResourceMetafieldSource(source) {
+	return RESOURCE_METAFIELD_SOURCE_SET.has(source);
+}
+/** True for a binding that reads a route resource's metafield. */
+function isResourceMetafieldBinding(binding) {
+	return isResourceMetafieldSource(binding.source);
+}
+/** A resource-metafield binding's `{type,value}`: the metafield itself, or —
+* with a `field` — one hop through its METAOBJECT_REFERENCE entry. */
+function resolveResourceMetafield(binding, metafields, metaobjectFields) {
+	const mf = metafields[`${binding.namespace}.${binding.key}`];
+	if (binding.field === void 0) return mf ?? null;
+	return traverseMetaobjectReference(mf, binding.field, metaobjectFields);
+}
+/** Overlay resolved resource-metafield values onto a template's settings — for
+* each binding of `opts.source` (default `product_metafield`),
+* `metafields["namespace.key"]`. The caller passes the route resource's map
+* (the PDP's product, or the collection, page, blog or article a template
+* renders); other sources are
+* skipped. See applyWholeValueBindings. */
 function applyMetafieldBindings(template, metafields, opts = {}) {
 	const metaobjectFields = opts.metaobjectFields ?? {};
-	applyWholeValueBindings(template, (binding) => {
-		if (binding.source !== "product_metafield") return null;
-		const mf = metafields[`${binding.namespace}.${binding.key}`];
-		if (binding.field === void 0) return mf ?? null;
-		return traverseMetaobjectReference(mf, binding.field, metaobjectFields);
-	}, opts);
+	const source = opts.source ?? "product_metafield";
+	applyWholeValueBindings(template, (binding) => binding.source === source ? resolveResourceMetafield(binding, metafields, metaobjectFields) : null, opts);
 }
 /** Whole-value sibling for `metaobject_field` bindings — `metaobjectFields[entry][key]`.
 * Runs on every template (the entry is pinned, not the route product). */
@@ -309,11 +340,6 @@ function resolveBoundValue(binding, mf, serializeRichText, sinkType) {
 }
 const TOKEN_OPEN = "";
 const TOKEN_CLOSE = "";
-const INLINE_TOKEN_DELIMITERS = /[\uE000\uE001]/g;
-/** Strip inline-token sentinel delimiters from a string. */
-function stripInlineTokenSentinels(value) {
-	return value.replace(INLINE_TOKEN_DELIMITERS, "");
-}
 const PRODUCT_ATTRIBUTE_KEYS = [
 	"title",
 	"vendor",
@@ -345,30 +371,49 @@ function metafieldTypeSupportsInlineToken(defType) {
 /** Serialize a source descriptor to its token-payload string. */
 function serializeSourceDescriptor(binding) {
 	switch (binding.source) {
-		case "product_metafield": return binding.field ? `product_metafield:${binding.namespace}:${binding.key}:${binding.field}` : `product_metafield:${binding.namespace}:${binding.key}`;
+		case "product_metafield":
+		case "collection_metafield":
+		case "page_metafield":
+		case "blog_metafield":
+		case "article_metafield": return binding.field ? `${binding.source}:${binding.namespace}:${binding.key}:${binding.field}` : `${binding.source}:${binding.namespace}:${binding.key}`;
 		case "metaobject_field": return `metaobject_field:${binding.entry}:${binding.key}`;
 		case "product_attribute": return `product_attribute:${binding.attribute}`;
 		case "collection_attribute": return `collection_attribute:${binding.attribute}`;
 		case "page_attribute": return `page_attribute:${binding.attribute}`;
 		case "blog_attribute": return `blog_attribute:${binding.attribute}`;
 		case "article_attribute": return `article_attribute:${binding.attribute}`;
+		case "closest_product_metafield":
+		case "closest_product_attribute":
+		case "closest_collection_attribute":
+		case "closest_page_attribute":
+		case "closest_blog_attribute":
+		case "closest_article_attribute": return `${CLOSEST_PREFIX}${serializeSourceDescriptor(routeTwin(binding))}`;
 		default: throw new Error(`unknown source descriptor: ${JSON.stringify(binding)}`);
 	}
 }
 /** Parse a token-payload string back to a descriptor, or null if malformed /
 * unknown source. */
 function parseSourceDescriptor(payload) {
+	if (payload.startsWith(CLOSEST_PREFIX)) {
+		const twin = parseSourceDescriptor(payload.slice(CLOSEST_PREFIX.length));
+		if (!twin || !(twin.source in CLOSEST_SOURCE_OF_TWIN)) return null;
+		if (twin.source === "product_metafield" && twin.field !== void 0) return null;
+		return {
+			...twin,
+			source: CLOSEST_SOURCE_OF_TWIN[twin.source]
+		};
+	}
 	const i = payload.indexOf(":");
 	if (i === -1) return null;
 	const source = payload.slice(0, i);
 	const rest = payload.slice(i + 1);
-	if (source === "product_metafield") {
+	if (isResourceMetafieldSource(source)) {
 		const segments = rest.split(":");
 		if (segments.length === 2) {
 			const [namespace, key] = segments;
 			if (!namespace || !key) return null;
 			return {
-				source: "product_metafield",
+				source,
 				namespace,
 				key
 			};
@@ -377,7 +422,7 @@ function parseSourceDescriptor(payload) {
 			const [namespace, key, field] = segments;
 			if (!namespace || !key || !FIELD_KEY_RE.test(field)) return null;
 			return {
-				source: "product_metafield",
+				source,
 				namespace,
 				key,
 				field
@@ -456,11 +501,14 @@ function splitInlineTokens(value) {
 * empty / undecodable (caller drops the token to ""). All sources for a value
 * are resolved in a SINGLE pass (see applyInlineSources), so a resolved value is
 * never re-scanned. */
-function resolveSource(descriptor, sources) {
+function resolveSource(descriptor, sources, node) {
 	switch (descriptor.source) {
-		case "product_metafield": {
-			const mf = sources.metafields[`${descriptor.namespace}.${descriptor.key}`];
-			const field = descriptor.field === void 0 ? mf : traverseMetaobjectReference(mf, descriptor.field, sources.metaobjectFields ?? {});
+		case "product_metafield":
+		case "collection_metafield":
+		case "page_metafield":
+		case "blog_metafield":
+		case "article_metafield": {
+			const field = resolveResourceMetafield(descriptor, descriptor.source === "product_metafield" ? sources.metafields : sources.routeMetafields?.[descriptor.source] ?? {}, sources.metaobjectFields ?? {});
 			const decoded = field ? decodeStorefrontMetafield(field.type, field.value) : null;
 			return typeof decoded === "string" ? decoded : null;
 		}
@@ -482,6 +530,17 @@ function resolveSource(descriptor, sources) {
 		case "article_attribute":
 			if (!ARTICLE_INLINE_ATTRIBUTES.has(descriptor.attribute)) return null;
 			return trimmedOrNull(sources.articleAttributes?.[descriptor.attribute]);
+		case "closest_product_metafield":
+		case "closest_product_attribute":
+		case "closest_collection_attribute":
+		case "closest_page_attribute":
+		case "closest_blog_attribute":
+		case "closest_article_attribute": {
+			const resource = closestResourceOf(descriptor);
+			const item = sources.closest?.singleAt(node, resource);
+			if (!item) return null;
+			return resolveSource(routeTwin(descriptor), itemInlineSources(resource, item), node);
+		}
 		default: return null;
 	}
 }
@@ -504,16 +563,16 @@ function escapeInertHtmlText(value) {
 }
 const SENTINEL_RE = new RegExp(`${TOKEN_OPEN}([^${TOKEN_OPEN}${TOKEN_CLOSE}]*)${TOKEN_CLOSE}`, "g");
 const DYN_SPAN_RE = /<span\b[^>]*?\bdata-dyn="([^"]*)"[^>]*><\/span>/g;
-function substitute(payload, sources, escape) {
+function substitute(payload, sources, escape, node) {
 	const descriptor = parseSourceDescriptor(payload);
 	if (!descriptor) return "";
-	const resolved = resolveSource(descriptor, sources);
+	const resolved = resolveSource(descriptor, sources, node);
 	if (resolved === null) return "";
 	return escape ? escapeHtmlText(resolved) : resolved;
 }
-function interpolate(value, sources) {
-	if (value.includes(TOKEN_OPEN)) return value.replace(SENTINEL_RE, (_m, payload) => substitute(payload, sources, false));
-	if (value.includes("data-dyn=")) return value.replace(DYN_SPAN_RE, (_m, payload) => substitute(payload, sources, true));
+function interpolate(value, sources, node) {
+	if (value.includes(TOKEN_OPEN)) return value.replace(SENTINEL_RE, (_m, payload) => substitute(payload, sources, false, node));
+	if (value.includes("data-dyn=")) return value.replace(DYN_SPAN_RE, (_m, payload) => substitute(payload, sources, true, node));
 	return value;
 }
 /** Overlay inline source tokens in a template's string settings. Walks every
@@ -526,30 +585,174 @@ function applyInlineSources(template, sources) {
 	for (const node of iterNodes(template)) {
 		const settings = node.settings;
 		if (!settings) continue;
+		const each = sources.closest?.eachAt(node) ?? null;
 		for (const [id, val] of Object.entries(settings)) {
 			if (typeof val !== "string") continue;
-			const next = interpolate(val, sources);
+			const next = interpolate(val, sources, node);
 			if (next !== val) settings[id] = next;
+			if (!each || each.items.length === 0) continue;
+			if (!val.includes(`${CLOSEST_PREFIX}${each.resource}_`)) continue;
+			const overlay = node.closestSettings ??= {};
+			for (const item of each.items) {
+				const scoped = {
+					...sources,
+					closest: withSingleItem(sources.closest, each.resource, item.sources)
+				};
+				const into = Object.hasOwn(overlay, item.id) ? overlay[item.id] : overlay[item.id] = {};
+				into[id] = interpolate(val, scoped, node);
+			}
 		}
 	}
 }
+const CLOSEST_PREFIX = "closest_";
+const CLOSEST_SOURCE_OF_TWIN = {
+	product_metafield: "closest_product_metafield",
+	product_attribute: "closest_product_attribute",
+	collection_attribute: "closest_collection_attribute",
+	page_attribute: "closest_page_attribute",
+	blog_attribute: "closest_blog_attribute",
+	article_attribute: "closest_article_attribute"
+};
+const CLOSEST_ARMS = {
+	closest_product_metafield: {
+		twin: "product_metafield",
+		resource: "product"
+	},
+	closest_product_attribute: {
+		twin: "product_attribute",
+		resource: "product"
+	},
+	closest_collection_attribute: {
+		twin: "collection_attribute",
+		resource: "collection"
+	},
+	closest_page_attribute: {
+		twin: "page_attribute",
+		resource: "page"
+	},
+	closest_blog_attribute: {
+		twin: "blog_attribute",
+		resource: "blog"
+	},
+	closest_article_attribute: {
+		twin: "article_attribute",
+		resource: "article"
+	}
+};
+/** The route arm a closest arm mirrors (same payload, `source` swapped), or
+* null for a binding that is not a closest arm. */
+function routeTwin(binding) {
+	const arm = CLOSEST_ARMS[binding.source];
+	return arm ? {
+		...binding,
+		source: arm.twin
+	} : null;
+}
+/** The resource a closest arm resolves against, or null for any other arm. */
+function closestResourceOf(binding) {
+	return CLOSEST_ARMS[binding.source]?.resource ?? null;
+}
+/** The lookup with `resource` pinned to one item — the per-item overlay pass. */
+function withSingleItem(base, resource, item) {
+	return {
+		singleAt: (node, r) => r === resource ? item : base?.singleAt(node, r) ?? null,
+		eachAt: () => null
+	};
+}
+/** The item's maps in the twin resolver's `InlineSources` slots, so the twin
+* applies its own key gates (`COLLECTION_INLINE_ATTRIBUTES` and friends). */
+function itemInlineSources(resource, item) {
+	switch (resource) {
+		case "product": return {
+			metafields: item.metafields ?? {},
+			attributes: item.attributes
+		};
+		case "collection": return {
+			metafields: {},
+			attributes: {},
+			collectionAttributes: item.attributes
+		};
+		case "page": return {
+			metafields: {},
+			attributes: {},
+			pageAttributes: item.attributes
+		};
+		case "blog": return {
+			metafields: {},
+			attributes: {},
+			blogAttributes: item.attributes
+		};
+		case "article": return {
+			metafields: {},
+			attributes: {},
+			articleAttributes: item.attributes
+		};
+	}
+}
+const CLOSEST_SINKS = /* @__PURE__ */ new Set([
+	"text",
+	"textarea",
+	"inline_richtext",
+	"richtext",
+	"color",
+	"url"
+]);
+/** True when a setting of `settingType` may carry a closest binding. */
+function isClosestSink(settingType) {
+	return CLOSEST_SINKS.has(settingType);
+}
+/** Resolve every whole-value `closest_<resource>_*` binding on ONE node against
+* ONE item, writing into `into` (a per-item overlay) or, by default, the node's
+* own settings (a single scope). Other resources' arms and the route twins are
+* untouched. A known sink is required — the schema's (`sinkTypeAt`) or the
+* stamp's — and it must be one of the text / color / url sinks; the product
+* metafield then goes through `resolveBoundValue` exactly as its twin does,
+* and the collection description through the same inert-HTML path as
+* `applyCollectionAttributeBindings`. The attribute arms are inline-only. */
+function applyClosestBindings(node, resource, item, opts = {}, into) {
+	const n = node;
+	if (!n.bindings) return;
+	let target = into;
+	for (const [settingId, binding] of Object.entries(n.bindings)) {
+		if (closestResourceOf(binding) !== resource) continue;
+		const twin = routeTwin(binding);
+		const sink = opts.sinkTypeAt?.(node, settingId) ?? binding.settingType;
+		if (!sink || !CLOSEST_SINKS.has(sink)) continue;
+		let resolved = null;
+		if (twin.source === "product_metafield") {
+			const mf = item.metafields?.[`${twin.namespace}.${twin.key}`];
+			if (mf) resolved = resolveBoundValue(twin, mf, opts.serializeRichText, sink);
+		} else if (twin.source === "collection_attribute" && twin.attribute === "description") {
+			const html = item.descriptionHtml;
+			if (sink === "richtext" && html && html.trim() !== "") resolved = inertBoundHtml(html);
+		}
+		if (resolved === null) continue;
+		target ??= n.settings ??= {};
+		target[settingId] = resolved;
+	}
+}
 /** Every source descriptor referenced anywhere in the template — whole-value
 * `bindings` sidecars AND inline tokens (both the PUA-sentinel and the richtext
 * data-dyn span forms), yielded as parsed `SettingBinding`s. The single walk both
 * `collectMetaobjectEntryIds` and `collectTraversedEntryIds` share so they can't
 * drift on which nodes/token-forms count. A malformed inline payload is skipped. */
 function* iterSourceDescriptors(template) {
-	for (const node of iterNodes(template)) {
-		const n = node;
-		if (n.bindings) for (const b of Object.values(n.bindings)) yield b;
-		if (n.settings) for (const val of Object.values(n.settings)) {
-			if (typeof val !== "string") continue;
-			const forms = val.includes(TOKEN_OPEN) ? val.matchAll(SENTINEL_RE) : val.includes("data-dyn=") ? val.matchAll(DYN_SPAN_RE) : null;
-			if (!forms) continue;
-			for (const m of forms) {
-				const d = parseSourceDescriptor(m[1]);
-				if (d) yield d;
-			}
+	for (const node of iterNodes(template)) yield* nodeSourceDescriptors(node);
+}
+/** Every source descriptor ONE node references — its `bindings` sidecar and
+* the inline tokens in its string settings (both forms). The per-node half of
+* `iterSourceDescriptors`, exported for the loader's closest-needs walk, which
+* must attribute each descriptor to the node's own scope. */
+function* nodeSourceDescriptors(node) {
+	const n = node;
+	if (n.bindings) for (const b of Object.values(n.bindings)) yield b;
+	if (n.settings) for (const val of Object.values(n.settings)) {
+		if (typeof val !== "string") continue;
+		const forms = val.includes(TOKEN_OPEN) ? val.matchAll(SENTINEL_RE) : val.includes("data-dyn=") ? val.matchAll(DYN_SPAN_RE) : null;
+		if (!forms) continue;
+		for (const m of forms) {
+			const d = parseSourceDescriptor(m[1]);
+			if (d) yield d;
 		}
 	}
 }
@@ -561,6 +764,13 @@ function collectMetaobjectEntryIds(template) {
 	for (const d of iterSourceDescriptors(template)) if (d.source === "metaobject_field") ids.add(d.entry);
 	return [...ids];
 }
+/** True when the template references `source` anywhere — a `bindings` sidecar
+* or an inline token of either form. The loader asks this before fetching a
+* resource's metafields, so a template that binds none makes no request. */
+function templateReferencesSource(template, source) {
+	for (const d of iterSourceDescriptors(template)) if (d.source === source) return true;
+	return false;
+}
 /** Distinct numeric entry ids reached by field-bearing `product_metafield`
 * descriptors (bindings + both token forms). Unlike pinned entries these vary per
 * product, so the resolved `metafields` map (keyed `"ns.key"`, the shape
@@ -568,11 +778,12 @@ function collectMetaobjectEntryIds(template) {
 * dereference each METAOBJECT_REFERENCE value to its entry GID. Shares both
 * resolve-time gates (`FIELD_KEY_RE` + `metaobjectRefEntryId`) with
 * `traverseMetaobjectReference` so the fetched set is exactly the resolvable
-* set. Empty on non-PDP loads (no product). */
-function collectTraversedEntryIds(template, metafields) {
+* set. `source` names whose map `metafields` is (default the route product's);
+* empty when that resource is absent from the load. */
+function collectTraversedEntryIds(template, metafields, source = "product_metafield") {
 	const ids = /* @__PURE__ */ new Set();
 	for (const d of iterSourceDescriptors(template)) {
-		if (d.source !== "product_metafield" || d.field === void 0) continue;
+		if (d.source !== source || d.field === void 0) continue;
 		if (!FIELD_KEY_RE.test(d.field)) continue;
 		const entryId = metaobjectRefEntryId(metafields[`${d.namespace}.${d.key}`]);
 		if (entryId !== null) ids.add(entryId);
@@ -584,4 +795,4 @@ function* iterNodes(template) {
 	yield* walkBlocks(template);
 }
 //#endregion
-export { ARTICLE_ATTRIBUTE_KEYS, BLOG_ATTRIBUTE_KEYS, COLLECTION_ATTRIBUTE_KEYS, COLLECTION_INLINE_ATTRIBUTE_KEYS, PAGE_ATTRIBUTE_KEYS, PRODUCT_ATTRIBUTE_KEYS, applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, decodeStorefrontMetafield, encodeSourceToken, escapeInertHtmlText, metafieldDefinitionFitsSetting, metafieldTypeSupportsInlineToken, metafieldTypeToSettingTypes, parseSourceDescriptor, serializeSourceDescriptor, settingTypeSupportsBinding, splitInlineTokens, stripInlineTokenSentinels };
+export { ARTICLE_ATTRIBUTE_KEYS, BLOG_ATTRIBUTE_KEYS, COLLECTION_ATTRIBUTE_KEYS, COLLECTION_INLINE_ATTRIBUTE_KEYS, PAGE_ATTRIBUTE_KEYS, PRODUCT_ATTRIBUTE_KEYS, RESOURCE_METAFIELD_SOURCES, ROUTE_METAFIELD_RESOURCE, ROUTE_METAFIELD_SOURCES, applyClosestBindings, applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, closestResourceOf, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, decodeStorefrontMetafield, encodeSourceToken, escapeInertHtmlText, isClosestSink, isResourceMetafieldBinding, isResourceMetafieldSource, metafieldDefinitionFitsSetting, metafieldTypeSupportsInlineToken, metafieldTypeToSettingTypes, nodeSourceDescriptors, parseSourceDescriptor, routeTwin, serializeSourceDescriptor, settingTypeSupportsBinding, splitInlineTokens, templateReferencesSource };

package/dist/ops.d.ts

@@ -0,0 +1,126 @@
+import { TemplateSection } from "./schemas.js";
+import { z } from "zod";
+//#region src/ops.d.ts
+/** One template or section group as the server holds it. */
+export interface EntryDoc {
+  sections: Record<string, TemplateSection>;
+  order: string[];
+  [key: string]: unknown;
+}
+export interface ThemeDocument {
+  settings: Record<string, unknown>;
+  templates: Record<string, EntryDoc>;
+  groups: Record<string, EntryDoc>;
+}
+/**
+ * `["settings", id]`, or `["template" | "group", id, ...nodePath]` where the
+ * node path descends `sections` → `blocks` → `blocks`… An absent `v` deletes.
+ */
+export type Op = {
+  p: string[];
+  v?: unknown;
+};
+export type OpReset = "publish" | "discard" | "upgrade" | "reseed";
+/** One entry of the per-install op stream. */
+export interface OpBatch {
+  seq: number;
+  clientId: string;
+  batchId: string;
+  userId: string;
+  ops: Op[];
+  reset?: OpReset;
+}
+/** The client id an MCP editor tool call writes its batches under. */
+export declare const agentClientId: (sid: string, callId: string) => string;
+/** Whether a batch came from an MCP editor tool call, not an editor tab. */
+export declare const isAgentClientId: (clientId: string) => boolean;
+export declare const MAX_PATH_DEPTH = 24;
+export declare const MAX_SEGMENT_LENGTH = 64;
+export declare const MAX_BATCH_OPS = 200;
+export declare const MAX_BATCH_BYTES: number;
+/** A node that holds ordered children: an entry's sections, or a section's or block's blocks. */
+export type Container = {
+  path: string[];
+  childKey: "sections" | "blocks";
+  orderKey: "order" | "block_order";
+};
+export type PathShape = {
+  kind: "settings";
+} | {
+  kind: "entry";
+} | {
+  kind: "order";
+  container: Container;
+} | {
+  kind: "child";
+  container: Container;
+  childId: string;
+} | {
+  kind: "children";
+  container: Container;
+} | {
+  kind: "field";
+  container: Container;
+};
+/** Where an op lands relative to the order-bearing containers it passes. */
+export declare function shapeOf(p: string[]): PathShape;
+/**
+ * Applies a batch copy-on-write along each op's path, then normalises every
+ * container the batch touched: drops order ids with no node, strips static
+ * block ids, and re-appends ids that were in that order when the batch began,
+ * still have a node and were not deleted by the batch. Ids never in the prior
+ * order stay out: presets hide content by omitting it from `order`.
+ */
+export declare function applyOps<D extends ThemeDocument>(doc: D, ops: Op[]): D;
+/**
+ * The ops that turn `prev` into `next`. Setting values, `order` and
+ * `block_order` are leaves (set whole); an added node is set whole, a removed
+ * one is one delete, a changed one is recursed. Short-circuits on `===`.
+ */
+export declare function diffDocument(prev: ThemeDocument, next: ThemeDocument): Op[];
+/** The ops that restore `prev` at exactly the paths `ops` touched. */
+export declare function invertOps(prev: ThemeDocument, ops: Op[]): Op[];
+/** Room for `clientId`, `batchNo`, `batchId` and the envelope. */
+/** The entries a run of ops writes: each one a whole template or group. */
+export interface TouchedEntries {
+  settings: boolean;
+  templates: Set<string>;
+  groups: Set<string>;
+}
+/** The entries `ops` write, added to `into` when given (a log read batch by
+ *  batch). */
+export declare function touchedEntries(ops: readonly Op[], into?: TouchedEntries): TouchedEntries;
+/**
+ * Splits ops into batches within the op and byte caps, keeping their order:
+ * `diffDocument` emits a container's new nodes before its order, so an order
+ * op never lands in an earlier batch than its nodes. An op larger than the cap
+ * travels alone (and the server refuses it).
+ */
+export declare function chunkOps(ops: Op[], maxBytes?: number, maxOps?: number): Op[][];
+export declare const OpSchema: z.ZodObject<{
+  p: z.ZodArray<z.ZodString>;
+  v: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+/** The body of `POST /draft/ops`. The byte cap is the route's body limit. */
+export declare const OpBatchBodySchema: z.ZodObject<{
+  clientId: z.ZodString;
+  batchNo: z.ZodNumber;
+  batchId: z.ZodString;
+  ops: z.ZodArray<z.ZodObject<{
+    p: z.ZodArray<z.ZodString>;
+    v: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+export type OpBatchBody = z.infer<typeof OpBatchBodySchema>;
+/** A batch an editor tab sends: the `mcp:` client id prefix marks an editor
+ *  tool call's batches, and other tabs follow those, so a tab can't claim it. */
+export declare const TabOpBatchBodySchema: z.ZodObject<{
+  clientId: z.ZodString;
+  batchNo: z.ZodNumber;
+  batchId: z.ZodString;
+  ops: z.ZodArray<z.ZodObject<{
+    p: z.ZodArray<z.ZodString>;
+    v: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+//#endregion