@plitzi/sdk-server 0.32.4 → 0.32.6

package/dist/modules/mcp/tools/index.js

@@ -1,150 +1,22 @@
-import { __exportAll } from "../../../_virtual/_rolldown/runtime.js";
-import applyPreviewTool from "./space/schema/applyPreview.js";
-import getSpaceSettingsTool from "./space/schema/getSpaceSettings.js";
-import updateSpaceSettingsTool from "./space/schema/updateSpaceSettings.js";
-import cloneElementTool from "./space/schema/elements/cloneElement.js";
-import createElementTool from "./space/schema/elements/createElement.js";
-import deleteElementTool from "./space/schema/elements/deleteElement.js";
-import getElementTool from "./space/schema/elements/getElement.js";
-import getElementsTool from "./space/schema/elements/getElements.js";
-import listElementsTool from "./space/schema/elements/listElements.js";
-import moveElementTool from "./space/schema/elements/moveElement.js";
-import updateElementTool from "./space/schema/elements/updateElement.js";
-import createPageFolderTool from "./space/schema/pageFolders/createPageFolder.js";
-import deletePageFolderTool from "./space/schema/pageFolders/deletePageFolder.js";
-import getPageFolderTool from "./space/schema/pageFolders/getPageFolder.js";
-import getPageFoldersTool from "./space/schema/pageFolders/getPageFolders.js";
-import updatePageFolderTool from "./space/schema/pageFolders/updatePageFolder.js";
-import createPageTool from "./space/schema/pages/createPage.js";
-import deletePageTool from "./space/schema/pages/deletePage.js";
-import getPageTool from "./space/schema/pages/getPage.js";
-import getPageBySlugTool from "./space/schema/pages/getPageBySlug.js";
-import getPagesTool from "./space/schema/pages/getPages.js";
-import updatePageTool from "./space/schema/pages/updatePage.js";
-import createVariableTool from "./space/schema/variables/createVariable.js";
-import deleteVariableTool from "./space/schema/variables/deleteVariable.js";
-import getVariableTool from "./space/schema/variables/getVariable.js";
-import getVariablesTool from "./space/schema/variables/getVariables.js";
-import updateVariableTool from "./space/schema/variables/updateVariable.js";
-import createStyleSelectorTool from "./space/style/selectors/createStyleSelector.js";
-import deleteStyleSelectorTool from "./space/style/selectors/deleteStyleSelector.js";
-import getStyleSelectorsTool from "./space/style/selectors/getStyleSelectors.js";
-import updateStyleSelectorTool from "./space/style/selectors/updateStyleSelector.js";
-import createStyleVariableTool from "./space/style/variables/createStyleVariable.js";
-import deleteStyleVariableTool from "./space/style/variables/deleteStyleVariable.js";
-import getStyleVariableTool from "./space/style/variables/getStyleVariable.js";
-import getStyleVariablesTool from "./space/style/variables/getStyleVariables.js";
-import updateStyleVariableTool from "./space/style/variables/updateStyleVariable.js";
-import addResourceTool from "./resources/addResource.js";
-import getResourceTool from "./resources/getResource.js";
-import getResourcesTool from "./resources/getResources.js";
-import moveResourceTool from "./resources/moveResource.js";
-import removeResourceTool from "./resources/removeResource.js";
-import createSegmentTool from "./segment/createSegment.js";
-import deleteSegmentTool from "./segment/deleteSegment.js";
-import getSegmentTool from "./segment/getSegment.js";
-import getSegmentsTool from "./segment/getSegments.js";
-import updateSegmentTool from "./segment/updateSegment.js";
-import createSegmentElementTool from "./segment/schema/elements/createSegmentElement.js";
-import deleteSegmentElementTool from "./segment/schema/elements/deleteSegmentElement.js";
-import moveSegmentElementTool from "./segment/schema/elements/moveSegmentElement.js";
-import updateSegmentElementTool from "./segment/schema/elements/updateSegmentElement.js";
-import createSegmentVariableTool from "./segment/schema/variables/createSegmentVariable.js";
-import deleteSegmentVariableTool from "./segment/schema/variables/deleteSegmentVariable.js";
-import updateSegmentVariableTool from "./segment/schema/variables/updateSegmentVariable.js";
-import createSegmentStyleVariableTool from "./segment/style/variables/createSegmentStyleVariable.js";
-import deleteSegmentStyleVariableTool from "./segment/style/variables/deleteSegmentStyleVariable.js";
-import updateSegmentStyleVariableTool from "./segment/style/variables/updateSegmentStyleVariable.js";
-import addPluginTool from "./plugins/addPlugin.js";
-import listPluginsTool from "./plugins/listPlugins.js";
-import removePluginTool from "./plugins/removePlugin.js";
-import updatePluginTool from "./plugins/updatePlugin.js";
-import getCollectionsTool from "./collections/getCollections.js";
-import getCollectionTool from "./collections/getCollection.js";
-import createCollectionTool from "./collections/createCollection.js";
-import updateCollectionTool from "./collections/updateCollection.js";
-import deleteCollectionTool from "./collections/deleteCollection.js";
-import getCollectionRecordsTool from "./collections/getCollectionRecords.js";
-import getCollectionRecordTool from "./collections/getCollectionRecord.js";
-import createCollectionRecordTool from "./collections/createCollectionRecord.js";
-import updateCollectionRecordTool from "./collections/updateCollectionRecord.js";
-import deleteCollectionRecordTool from "./collections/deleteCollectionRecord.js";
-import listResourcesTool from "./docs/listResources.js";
-import readResourceTool from "./docs/readResource.js";
+import { operation } from "./operations/index.js";
+import { applyOperations } from "./apply/dispatch.js";
+import { validateOperations } from "./shared/validator/index.js";
+import { apply, applyShape, applyTool } from "./apply/index.js";
+import { previewTool } from "./preview.js";
+import { read, readShape, readTool } from "./read.js";
+import { screenshotTool } from "./screenshot.js";
+import { search, searchShape, searchTool } from "./search.js";
+import { validate, validateShape, validateTool } from "./validate.js";
 //#region src/modules/mcp/tools/index.ts
-var tools_exports = /* @__PURE__ */ __exportAll({
-	addPluginTool: () => addPluginTool,
-	addResourceTool: () => addResourceTool,
-	applyPreviewTool: () => applyPreviewTool,
-	cloneElementTool: () => cloneElementTool,
-	createCollectionRecordTool: () => createCollectionRecordTool,
-	createCollectionTool: () => createCollectionTool,
-	createElementTool: () => createElementTool,
-	createPageFolderTool: () => createPageFolderTool,
-	createPageTool: () => createPageTool,
-	createSegmentElementTool: () => createSegmentElementTool,
-	createSegmentStyleVariableTool: () => createSegmentStyleVariableTool,
-	createSegmentTool: () => createSegmentTool,
-	createSegmentVariableTool: () => createSegmentVariableTool,
-	createStyleSelectorTool: () => createStyleSelectorTool,
-	createStyleVariableTool: () => createStyleVariableTool,
-	createVariableTool: () => createVariableTool,
-	deleteCollectionRecordTool: () => deleteCollectionRecordTool,
-	deleteCollectionTool: () => deleteCollectionTool,
-	deleteElementTool: () => deleteElementTool,
-	deletePageFolderTool: () => deletePageFolderTool,
-	deletePageTool: () => deletePageTool,
-	deleteSegmentElementTool: () => deleteSegmentElementTool,
-	deleteSegmentStyleVariableTool: () => deleteSegmentStyleVariableTool,
-	deleteSegmentTool: () => deleteSegmentTool,
-	deleteSegmentVariableTool: () => deleteSegmentVariableTool,
-	deleteStyleSelectorTool: () => deleteStyleSelectorTool,
-	deleteStyleVariableTool: () => deleteStyleVariableTool,
-	deleteVariableTool: () => deleteVariableTool,
-	getCollectionRecordTool: () => getCollectionRecordTool,
-	getCollectionRecordsTool: () => getCollectionRecordsTool,
-	getCollectionTool: () => getCollectionTool,
-	getCollectionsTool: () => getCollectionsTool,
-	getElementTool: () => getElementTool,
-	getElementsTool: () => getElementsTool,
-	getPageBySlugTool: () => getPageBySlugTool,
-	getPageFolderTool: () => getPageFolderTool,
-	getPageFoldersTool: () => getPageFoldersTool,
-	getPageTool: () => getPageTool,
-	getPagesTool: () => getPagesTool,
-	getResourceTool: () => getResourceTool,
-	getResourcesTool: () => getResourcesTool,
-	getSegmentTool: () => getSegmentTool,
-	getSegmentsTool: () => getSegmentsTool,
-	getSpaceSettingsTool: () => getSpaceSettingsTool,
-	getStyleSelectorsTool: () => getStyleSelectorsTool,
-	getStyleVariableTool: () => getStyleVariableTool,
-	getStyleVariablesTool: () => getStyleVariablesTool,
-	getVariableTool: () => getVariableTool,
-	getVariablesTool: () => getVariablesTool,
-	listElementsTool: () => listElementsTool,
-	listPluginsTool: () => listPluginsTool,
-	listResourcesTool: () => listResourcesTool,
-	moveElementTool: () => moveElementTool,
-	moveResourceTool: () => moveResourceTool,
-	moveSegmentElementTool: () => moveSegmentElementTool,
-	readResourceTool: () => readResourceTool,
-	removePluginTool: () => removePluginTool,
-	removeResourceTool: () => removeResourceTool,
-	updateCollectionRecordTool: () => updateCollectionRecordTool,
-	updateCollectionTool: () => updateCollectionTool,
-	updateElementTool: () => updateElementTool,
-	updatePageFolderTool: () => updatePageFolderTool,
-	updatePageTool: () => updatePageTool,
-	updatePluginTool: () => updatePluginTool,
-	updateSegmentElementTool: () => updateSegmentElementTool,
-	updateSegmentStyleVariableTool: () => updateSegmentStyleVariableTool,
-	updateSegmentTool: () => updateSegmentTool,
-	updateSegmentVariableTool: () => updateSegmentVariableTool,
-	updateSpaceSettingsTool: () => updateSpaceSettingsTool,
-	updateStyleSelectorTool: () => updateStyleSelectorTool,
-	updateStyleVariableTool: () => updateStyleVariableTool,
-	updateVariableTool: () => updateVariableTool
-});
+/** The MCP tool registry — the single source both hosts (the standalone server and the in-process AI bridge)
+*  register from. Adding a tool is: create its file with a ToolDef descriptor and append it here. */
+var tools = [
+	applyTool,
+	validateTool,
+	searchTool,
+	readTool,
+	previewTool,
+	screenshotTool
+];
 //#endregion
-export { addPluginTool, addResourceTool, applyPreviewTool, cloneElementTool, createCollectionRecordTool, createCollectionTool, createElementTool, createPageFolderTool, createPageTool, createSegmentElementTool, createSegmentStyleVariableTool, createSegmentTool, createSegmentVariableTool, createStyleSelectorTool, createStyleVariableTool, createVariableTool, deleteCollectionRecordTool, deleteCollectionTool, deleteElementTool, deletePageFolderTool, deletePageTool, deleteSegmentElementTool, deleteSegmentStyleVariableTool, deleteSegmentTool, deleteSegmentVariableTool, deleteStyleSelectorTool, deleteStyleVariableTool, deleteVariableTool, getCollectionRecordTool, getCollectionRecordsTool, getCollectionTool, getCollectionsTool, getElementTool, getElementsTool, getPageBySlugTool, getPageFolderTool, getPageFoldersTool, getPageTool, getPagesTool, getResourceTool, getResourcesTool, getSegmentTool, getSegmentsTool, getSpaceSettingsTool, getStyleSelectorsTool, getStyleVariableTool, getStyleVariablesTool, getVariableTool, getVariablesTool, listElementsTool, listPluginsTool, listResourcesTool, moveElementTool, moveResourceTool, moveSegmentElementTool, readResourceTool, removePluginTool, removeResourceTool, tools_exports, updateCollectionRecordTool, updateCollectionTool, updateElementTool, updatePageFolderTool, updatePageTool, updatePluginTool, updateSegmentElementTool, updateSegmentStyleVariableTool, updateSegmentTool, updateSegmentVariableTool, updateSpaceSettingsTool, updateStyleSelectorTool, updateStyleVariableTool, updateVariableTool };
+export { apply, applyOperations, applyShape, operation, read, readShape, search, searchShape, tools, validate, validateOperations, validateShape };

package/dist/modules/mcp/tools/operations/index.js

@@ -0,0 +1,41 @@
+import { elementOps } from "./schema/operations.js";
+import { styleOps } from "./style/operations.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/index.ts
+var operation = z.discriminatedUnion("type", [
+	elementOps.upsertElement,
+	elementOps.patchElement,
+	elementOps.deleteElement,
+	elementOps.moveElement,
+	elementOps.upsertPage,
+	elementOps.deletePage,
+	elementOps.upsertFolder,
+	elementOps.deleteFolder,
+	elementOps.upsertVariable,
+	elementOps.deleteVariable,
+	elementOps.upsertBinding,
+	elementOps.patchBinding,
+	elementOps.deleteBinding,
+	elementOps.upsertInteractionFlow,
+	elementOps.patchInteractionNode,
+	elementOps.deleteInteraction,
+	elementOps.patchSettings,
+	styleOps.upsertDefinition,
+	styleOps.patchDefinition,
+	styleOps.deleteDefinition,
+	styleOps.upsertGlobalStyle,
+	styleOps.patchGlobalStyle,
+	styleOps.deleteGlobalStyle,
+	styleOps.upsertIdStyle,
+	styleOps.patchIdStyle,
+	styleOps.deleteIdStyle,
+	styleOps.upsertStyleVariable,
+	styleOps.deleteStyleVariable
+]);
+var STYLE_OP_TYPES = new Set(Object.keys(styleOps));
+var isStyleOp = (type) => STYLE_OP_TYPES.has(type);
+var MAX_OPS = 1e3;
+var environment = z.string().optional().describe("Environment; default main");
+var operations = z.array(operation).max(MAX_OPS).describe(`Operations applied atomically, in order (max ${MAX_OPS})`);
+//#endregion
+export { MAX_OPS, environment, isStyleOp, operation, operations };

package/dist/modules/mcp/tools/operations/schema/bindings/deleteBinding.js

@@ -0,0 +1,32 @@
+import { pageUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { bindingCategory } from "../shared.js";
+import { resolveElement } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/bindings/deleteBinding.ts
+var deleteBindingOp = z.object({
+	type: z.literal("deleteBinding"),
+	pageRef: z.string().describe("Page ref or id"),
+	ref: z.string().describe("Element ref or id"),
+	category: bindingCategory,
+	to: z.string().describe("Target of the binding to remove"),
+	id: z.string().optional().describe("Match by id instead of to")
+}).describe("Remove a data binding from an element (matched by id when given, else by to). Fails if none matches.");
+var deleteBinding = (space, env, op) => {
+	const found = resolveElement(space, env, op.pageRef, op.ref);
+	if ("error" in found) return found.error;
+	const bindings = found.el.definition.bindings;
+	const list = bindings?.[op.category];
+	const index = list ? list.findIndex((b) => op.id ? b.id === op.id : b.to === op.to) : -1;
+	if (!bindings || !list || index < 0) return fail("to", `No ${op.category} binding matching "${op.id ?? op.to}" on "${op.ref}"`, "Nothing to delete");
+	list.splice(index, 1);
+	if (list.length === 0) Reflect.deleteProperty(bindings, op.category);
+	return {
+		...empty(),
+		deleted: 1,
+		staleResources: [pageUri(env, op.pageRef)],
+		elementRefs: [op.ref]
+	};
+};
+//#endregion
+export { deleteBinding, deleteBindingOp };

package/dist/modules/mcp/tools/operations/schema/bindings/patchBinding.js

@@ -0,0 +1,36 @@
+import { pageUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { bindingCategory, bindingInput } from "../shared.js";
+import { resolveElement } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/bindings/patchBinding.ts
+var patchBindingOp = z.object({
+	type: z.literal("patchBinding"),
+	pageRef: z.string().describe("Page ref or id"),
+	ref: z.string().describe("Element ref or id"),
+	category: bindingCategory,
+	to: z.string().describe("Target of the binding to patch"),
+	id: z.string().optional().describe("Match by id instead of to"),
+	source: bindingInput.shape.source.optional(),
+	transformers: bindingInput.shape.transformers,
+	when: bindingInput.shape.when,
+	enabled: bindingInput.shape.enabled
+}).describe("Partially update an EXISTING binding (matched by id when given, else by to): only the fields you pass change. Never creates — fails if no binding matches.");
+var patchBinding = (space, env, op) => {
+	const found = resolveElement(space, env, op.pageRef, op.ref);
+	if ("error" in found) return found.error;
+	const binding = (found.el.definition.bindings?.[op.category])?.find((b) => op.id ? b.id === op.id : b.to === op.to);
+	if (!binding) return fail("to", `No ${op.category} binding matching "${op.id ?? op.to}" on "${op.ref}"`, "Use upsertBinding to add it");
+	if (op.source !== void 0) binding.source = op.source;
+	if (op.transformers !== void 0) binding.transformers = op.transformers;
+	if (op.when !== void 0) binding.when = op.when;
+	if (op.enabled !== void 0) binding.enabled = op.enabled;
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [pageUri(env, op.pageRef)],
+		elementRefs: [op.ref]
+	};
+};
+//#endregion
+export { patchBinding, patchBindingOp };

package/dist/modules/mcp/tools/operations/schema/bindings/upsertBinding.js

@@ -0,0 +1,47 @@
+import { generateObjectId } from "../../../../helpers/space.js";
+import { pageUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { bindingCategory, bindingInput } from "../shared.js";
+import { resolveElement } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/bindings/upsertBinding.ts
+var upsertBindingOp = z.object({
+	type: z.literal("upsertBinding"),
+	pageRef: z.string().describe("Page ref or id"),
+	ref: z.string().describe("Element ref or id"),
+	category: bindingCategory,
+	binding: bindingInput
+}).describe("Add a data binding to an element, or replace the one already feeding the same target (matched by binding.id when given, else by binding.to). Connects a data source to a prop, style value, or initialState key.");
+var upsertBinding = (space, env, op) => {
+	const found = resolveElement(space, env, op.pageRef, op.ref);
+	if ("error" in found) return found.error;
+	const bindings = found.el.definition.bindings ??= {};
+	const list = bindings[op.category] ??= [];
+	const index = list.findIndex((b) => op.binding.id ? b.id === op.binding.id : b.to === op.binding.to);
+	const binding = {
+		id: op.binding.id ?? (index >= 0 ? list[index].id : generateObjectId()),
+		to: op.binding.to,
+		source: op.binding.source
+	};
+	if (op.binding.transformers) binding.transformers = op.binding.transformers;
+	if (op.binding.when !== void 0) binding.when = op.binding.when;
+	if (op.binding.enabled !== void 0) binding.enabled = op.binding.enabled;
+	if (index >= 0) {
+		list[index] = binding;
+		return {
+			...empty(),
+			updated: 1,
+			staleResources: [pageUri(env, op.pageRef)],
+			elementRefs: [op.ref]
+		};
+	}
+	list.push(binding);
+	return {
+		...empty(),
+		created: 1,
+		staleResources: [pageUri(env, op.pageRef)],
+		elementRefs: [op.ref]
+	};
+};
+//#endregion
+export { upsertBinding, upsertBindingOp };

package/dist/modules/mcp/tools/operations/schema/elements/deleteElement.js

@@ -0,0 +1,29 @@
+import { descendantIds, findPageByRef, indexRemoveElements, resolveRef } from "../../../../helpers/space.js";
+import { pageUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { removeFromParent } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/elements/deleteElement.ts
+var deleteElementOp = z.object({
+	type: z.literal("deleteElement"),
+	pageRef: z.string().describe("Page ref or id"),
+	ref: z.string().describe("Ref or id of the element to delete")
+}).describe("Delete an element and all of its descendants from a page.");
+var deleteElement = (space, env, op) => {
+	const page = findPageByRef(space.schema, op.pageRef);
+	if (!page) return fail("pageRef", `Page "${op.pageRef}" not found`, "Read the pages resource for valid refs");
+	const el = resolveRef(space.schema, page, op.ref);
+	if (!el || el.id === page.id) return fail("ref", `Element "${op.ref}" not found in page "${op.pageRef}"`, "Read the page resource for valid refs");
+	const ids = [...descendantIds(space.schema, el.id), el.id];
+	const removed = ids.map((id) => space.schema.flat[id]);
+	for (const id of ids) Reflect.deleteProperty(space.schema.flat, id);
+	removeFromParent(space, el);
+	indexRemoveElements(space.schema, removed);
+	return {
+		...empty(),
+		deleted: 1,
+		staleResources: [pageUri(env, op.pageRef)]
+	};
+};
+//#endregion
+export { deleteElement, deleteElementOp };

package/dist/modules/mcp/tools/operations/schema/elements/moveElement.js

@@ -0,0 +1,41 @@
+import { findPageByRef, indexInvalidateDetails, resolveRef } from "../../../../helpers/space.js";
+import { pageUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { position } from "../shared.js";
+import { placeChild, removeFromParent } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/elements/moveElement.ts
+var moveElementOp = z.object({
+	type: z.literal("moveElement"),
+	pageRef: z.string().describe("Page ref or id"),
+	ref: z.string().describe("Ref or id of the element to move"),
+	toParentRef: z.string().describe("Ref or id of the anchor the element moves relative to (see position)"),
+	position
+}).describe("Move an existing element to a new parent, or reorder it — its placement is set by position.");
+var moveElement = (space, env, op) => {
+	const page = findPageByRef(space.schema, op.pageRef);
+	if (!page) return fail("pageRef", `Page "${op.pageRef}" not found`, "Read the pages resource for valid refs");
+	const el = resolveRef(space.schema, page, op.ref);
+	const anchor = resolveRef(space.schema, page, op.toParentRef);
+	if (!el || el.id === page.id) return fail("ref", `Element "${op.ref}" not found`, "Read the page resource for valid refs");
+	if (!anchor) return fail("toParentRef", `Target "${op.toParentRef}" not found`, "Read the page resource for valid refs");
+	removeFromParent(space, el);
+	let parent = anchor;
+	let index;
+	if (op.position === "before" || op.position === "after") {
+		parent = anchor.definition.parentId ? space.schema.flat[anchor.definition.parentId] ?? page : page;
+		const at = (parent.definition.items ?? []).indexOf(anchor.id);
+		index = at < 0 ? void 0 : op.position === "after" ? at + 1 : at;
+	}
+	el.definition.parentId = parent.id;
+	placeChild(parent, el.id, index);
+	indexInvalidateDetails(space.schema);
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [pageUri(env, op.pageRef)],
+		elementRefs: [op.ref]
+	};
+};
+//#endregion
+export { moveElement, moveElementOp };

package/dist/modules/mcp/tools/operations/schema/elements/patchElement.js

@@ -0,0 +1,58 @@
+import { findPageByRef, resolveRef } from "../../../../helpers/space.js";
+import { pageUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { initialStateInput, styleRefs } from "../shared.js";
+import { guardNewRef, writeInitialState } from "../write.js";
+import { z } from "zod";
+import { repointIdRefs } from "@plitzi/sdk-schema/helpers/idRef";
+//#region src/modules/mcp/tools/operations/schema/elements/patchElement.ts
+var patchElementOp = z.object({
+	type: z.literal("patchElement"),
+	pageRef: z.string().describe("Page ref or id"),
+	ref: z.string().describe("Existing element ref or id"),
+	idRef: z.string().optional().describe("Assign or rename the idRef of this element ([A-Za-z0-9_-], starting with a letter, unique in the space). Give an element one to make it bindable: without an idRef it publishes no data source. Renaming one moves its source name with it — every binding and interaction across the space that targeted the old name is repointed for you, so the wiring survives the rename."),
+	label: z.string().optional(),
+	subType: z.string().optional(),
+	props: z.record(z.string(), z.unknown()).optional().describe("Merged onto existing props: listed keys change, null unsets a key, others are preserved"),
+	style: styleRefs.optional().describe("Merged onto existing style: base replaces base, listed slots replace slots"),
+	initialState: initialStateInput.optional().describe("Merged onto existing initialState: styleVariant overlays per class/selector, visibility overrides")
+}).describe("Partially update an EXISTING element: only the fields you pass change (props/style/initialState are merged, not replaced). Never creates — fails if ref does not resolve. Use upsertElement to create or fully replace.");
+var patchElement = (space, env, op) => {
+	const page = findPageByRef(space.schema, op.pageRef);
+	if (!page) return fail("pageRef", `Page "${op.pageRef}" not found`, "Read plitzi://schema/" + env + "/pages for valid refs");
+	const el = resolveRef(space.schema, page, op.ref);
+	if (!el || el.id === page.id) return fail("ref", `Element "${op.ref}" not found in page "${op.pageRef}"`, "patchElement only updates an existing element; use upsertElement to create one");
+	if (op.idRef !== void 0 && op.idRef !== el.idRef) {
+		const guard = guardNewRef(space, op.idRef, "idRef");
+		if (guard) return guard;
+		const previous = el.idRef;
+		el.idRef = op.idRef;
+		if (previous) repointIdRefs(space.schema.flat, { [previous]: op.idRef });
+	}
+	if (op.label !== void 0) el.definition.label = op.label;
+	if (op.subType !== void 0) el.attributes = {
+		...el.attributes,
+		subType: op.subType
+	};
+	if (op.props !== void 0) {
+		const merged = { ...el.attributes };
+		for (const [key, value] of Object.entries(op.props)) if (value === null) Reflect.deleteProperty(merged, key);
+		else merged[key] = value;
+		el.attributes = merged;
+	}
+	if (op.style !== void 0) {
+		const selectors = { ...el.definition.styleSelectors };
+		if (op.style.base !== void 0) selectors.base = op.style.base.join(" ");
+		for (const [slot, classes] of Object.entries(op.style.slots ?? {})) selectors[slot] = classes.join(" ");
+		el.definition.styleSelectors = selectors;
+	}
+	if (op.initialState !== void 0) writeInitialState(el, op.initialState, true);
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [pageUri(env, op.pageRef)],
+		elementRefs: [op.ref]
+	};
+};
+//#endregion
+export { patchElement, patchElementOp };

package/dist/modules/mcp/tools/operations/schema/elements/upsertElement.js

@@ -0,0 +1,65 @@
+import { findPageByRef, resolveRef } from "../../../../helpers/space.js";
+import { pageUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { elementInput, position } from "../shared.js";
+import { collectInputRefs, createElement, guardNewRef, writeInitialState } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/elements/upsertElement.ts
+var upsertElementOp = z.object({
+	type: z.literal("upsertElement"),
+	pageRef: z.string().describe("Page ref or id"),
+	element: elementInput,
+	parentRef: z.string().optional().describe("Anchor ref/id; defaults to page root"),
+	position: position.optional()
+}).describe("Add an element to a page, or fully update it when element.ref already exists (props and style are REPLACED, not merged). To change only some fields of an existing element, use patchElement instead.");
+var upsertElement = (space, env, op) => {
+	const page = findPageByRef(space.schema, op.pageRef);
+	if (!page) return fail("pageRef", `Page "${op.pageRef}" not found`, "Read plitzi://schema/" + env + "/pages for valid refs");
+	const existing = resolveRef(space.schema, page, op.element.ref);
+	if (existing && existing.id !== page.id) {
+		if (op.element.label !== void 0) existing.definition.label = op.element.label;
+		if (op.element.props !== void 0 || op.element.subType !== void 0) {
+			const subType = op.element.subType ?? existing.attributes.subType;
+			existing.attributes = subType === void 0 ? { ...op.element.props } : {
+				subType,
+				...op.element.props
+			};
+		}
+		if (op.element.style !== void 0) {
+			const selectors = { base: (op.element.style.base ?? []).join(" ") };
+			for (const [slot, classes] of Object.entries(op.element.style.slots ?? {})) selectors[slot] = classes.join(" ");
+			existing.definition.styleSelectors = selectors;
+		}
+		if (op.element.initialState !== void 0) writeInitialState(existing, op.element.initialState, false);
+		return {
+			...empty(),
+			updated: 1,
+			staleResources: [pageUri(env, op.pageRef)],
+			elementRefs: [op.element.ref]
+		};
+	}
+	for (const ref of collectInputRefs(op.element)) {
+		const guard = guardNewRef(space, ref, "element.ref");
+		if (guard) return guard;
+	}
+	let parent = page;
+	let index;
+	if (op.parentRef) {
+		const anchor = resolveRef(space.schema, page, op.parentRef);
+		if (!anchor) return fail("parentRef", `Parent "${op.parentRef}" not found in page "${op.pageRef}"`, "Use an existing ref");
+		if (op.position === "before" || op.position === "after") {
+			parent = anchor.definition.parentId ? space.schema.flat[anchor.definition.parentId] : page;
+			const at = (parent.definition.items ?? []).indexOf(anchor.id);
+			index = at < 0 ? void 0 : op.position === "after" ? at + 1 : at;
+		} else parent = anchor;
+	}
+	createElement(space, page, op.element, parent, index);
+	return {
+		...empty(),
+		created: 1,
+		staleResources: [pageUri(env, op.pageRef)],
+		elementRefs: [op.element.ref]
+	};
+};
+//#endregion
+export { upsertElement, upsertElementOp };

package/dist/modules/mcp/tools/operations/schema/folders/deleteFolder.js

@@ -0,0 +1,30 @@
+import { findFolderByRef, isPageElement, pageFoldersOf, sortFolders } from "../../../../helpers/space.js";
+import { folderUri, foldersUri, pagesUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/folders/deleteFolder.ts
+var deleteFolderOp = z.object({
+	type: z.literal("deleteFolder"),
+	ref: z.string()
+}).describe("Delete a folder; its child folders and pages move up to its parent (or the root)");
+var deleteFolder = (space, env, op) => {
+	const folders = pageFoldersOf(space.schema);
+	const folder = findFolderByRef(space.schema, op.ref);
+	if (!folder) return fail("ref", `Folder "${op.ref}" not found`, "Read plitzi://folders for valid refs");
+	const newParent = folder.parentId;
+	for (const child of folders) if (child.parentId === folder.id) if (newParent === void 0) Reflect.deleteProperty(child, "parentId");
+	else child.parentId = newParent;
+	for (const el of Object.values(space.schema.flat)) if (isPageElement(space.schema, el) && el.attributes.folder === folder.id) el.attributes.folder = newParent ?? "";
+	space.schema.pageFolders = sortFolders(folders.filter((f) => f.id !== folder.id));
+	return {
+		...empty(),
+		deleted: 1,
+		staleResources: [
+			folderUri(env, folder.id),
+			foldersUri(env),
+			pagesUri(env)
+		]
+	};
+};
+//#endregion
+export { deleteFolder, deleteFolderOp };

package/dist/modules/mcp/tools/operations/schema/folders/upsertFolder.js

@@ -0,0 +1,49 @@
+import { findFolderByRef, pageFoldersOf, slugify, sortFolders } from "../../../../helpers/space.js";
+import { folderUri, foldersUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/folders/upsertFolder.ts
+var upsertFolderOp = z.object({
+	type: z.literal("upsertFolder"),
+	ref: z.string().describe("Folder ref: an existing folder id/name/slug to update, or a new id you choose"),
+	name: z.string().optional(),
+	slug: z.string().optional(),
+	parentId: z.string().nullable().optional().describe("Ref of the parent folder for nesting; null keeps it at root")
+}).describe("Create a sidebar page-folder, or update it when ref already exists. Nest it under another via parentId.");
+var upsertFolder = (space, env, op) => {
+	const folders = pageFoldersOf(space.schema);
+	let parentId;
+	if (op.parentId !== void 0 && op.parentId !== null) {
+		const parent = findFolderByRef(space.schema, op.parentId);
+		if (!parent) return fail("parentId", `Parent folder "${op.parentId}" not found`, "Create it with upsertFolder first");
+		parentId = parent.id;
+	}
+	const existing = findFolderByRef(space.schema, op.ref);
+	if (existing) {
+		if (op.name !== void 0) existing.name = op.name;
+		if (op.slug !== void 0) existing.slug = op.slug;
+		if (op.parentId === null) Reflect.deleteProperty(existing, "parentId");
+		else if (op.parentId !== void 0) existing.parentId = parentId;
+		space.schema.pageFolders = sortFolders(folders);
+		return {
+			...empty(),
+			updated: 1,
+			staleResources: [folderUri(env, existing.id), foldersUri(env)]
+		};
+	}
+	const folder = {
+		id: op.ref,
+		name: op.name ?? op.ref,
+		slug: op.slug ?? slugify(op.ref)
+	};
+	if (parentId !== void 0) folder.parentId = parentId;
+	folders.push(folder);
+	space.schema.pageFolders = sortFolders(folders);
+	return {
+		...empty(),
+		created: 1,
+		staleResources: [folderUri(env, folder.id), foldersUri(env)]
+	};
+};
+//#endregion
+export { upsertFolder, upsertFolderOp };