@plitzi/sdk-mcp 0.37.8 → 0.37.10

package/dist/modules/mcp/tools/operations/schema/write.js

@@ -1,6 +1,8 @@
 import { findRootByRef, indexAddElement, resolveRef } from "../../../helpers/space.js";
 import { folderUri, foldersUri, layoutsUri, pageUri, pagesUri, schemaVarsUri, settingsUri } from "../../../helpers/uris.js";
 import { fail } from "../../../helpers/opResult.js";
+import { flagGateOf } from "@plitzi/sdk-authoring";
+import { documentIds } from "@plitzi/sdk-schema/helpers/components";
 import { elementIdConflict, isValidElementId } from "@plitzi/sdk-schema/helpers/elementId";
 import FlatMap from "@plitzi/sdk-schema/helpers/FlatMap";
 //#region src/modules/mcp/tools/operations/schema/write.ts
@@ -12,7 +14,8 @@ var collectInputRefs = (input) => [input.ref, ...(input.children ?? []).flatMap(
 *  it. Both rules are sdk-schema's `elementIdConflict` — never restated here, so the MCP cannot drift from what
 *  the builder and the schema validator enforce. Null when the name is usable. */
 var guardNewRef = (space, ref, field) => {
-	const conflict = elementIdConflict(space.schema.flat, ref);
+	const elsewhere = documentIds(space.document ?? space.schema).has(ref) ? `"${ref}" is already used by another element here` : null;
+	const conflict = elementIdConflict(space.schema.flat, ref) ?? elsewhere;
 	if (!conflict) return null;
 	return isValidElementId(ref) ? fail(field, conflict, TAKEN_HINT) : fail(field, conflict, ID_REF_HINT);
 };
@@ -62,7 +65,9 @@ var createElement = (space, page, input, anchorId, drop) => {
 			type: input.type,
 			items: [],
 			styleSelectors,
-			...input.runtime === void 0 ? {} : { runtime: input.runtime }
+			...input.runtime === void 0 ? {} : { runtime: input.runtime },
+			...input.flag === void 0 ? {} : { flag: flagGateOf(input.flag, `Element "${input.ref}"`) },
+			...input.anchor === void 0 ? {} : { anchor: input.anchor }
 		}
 	};
 	if (!new FlatMap({ flat: space.schema.flat }).addElement(el, anchorId, drop)) return false;

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

@@ -1,6 +1,6 @@
 import { actionAccess, actionField, actionLimits, actionNode, actionTriggerParams } from "./actions/document.js";
 import { connectorConnection, readEndpoint, writeEndpoint } from "./connectors/manifest.js";
-import { bindingInput, elementInput, initialStateInput, interactionNode, position, ruleGroup, styleRefs, styleVariantInput } from "./schema/shared.js";
+import { bindingInput, elementAnchor, elementFlag, elementInput, initialStateInput, interactionNode, position, ruleGroup, styleRefs, styleVariantInput } from "./schema/shared.js";
 import { ancestors, ancestorsPatch, cssMap, cssPatchMap, definitionSlot, definitionSlotPatch, displayModeCss, displayModeCssPatch, themeValue } from "./style/shared.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/schemaIds.ts
@@ -23,6 +23,8 @@ import { z } from "zod";
 *  the co-worker's own tool-schema converter alike. */
 var SHARED_SCHEMAS = [
 	[elementInput, "Element"],
+	[elementFlag, "ElementFlag"],
+	[elementAnchor, "ElementAnchor"],
 	[ruleGroup, "RuleGroup"],
 	[styleRefs, "StyleRefs"],
 	[initialStateInput, "InitialState"],

package/dist/modules/mcp/tools/preview.d.ts

@@ -50,6 +50,8 @@ export declare const previewShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;
@@ -74,6 +76,7 @@ export declare const previewShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;
         ref: z.ZodString;
@@ -118,6 +121,18 @@ export declare const previewShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteVariable">;
         name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertFlag">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        value: z.ZodBoolean;
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            when: z.ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, z.core.$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: z.ZodBoolean;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteFlag">;
+        name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"upsertBinding">;
         pageRef: z.ZodString;
@@ -221,6 +236,7 @@ export declare const previewShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"patchSettings">;
         customCss: z.ZodOptional<z.ZodString>;
+        notifications: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
         keepState: z.ZodOptional<z.ZodBoolean>;
         stateStorage: z.ZodOptional<z.ZodEnum<{
             localStorage: "localStorage";
@@ -265,6 +281,17 @@ export declare const previewShape: {
             }>>;
             presence: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertComponent">;
+        ref: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        slots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fromRef: z.ZodOptional<z.ZodString>;
+        instanceRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteComponent">;
+        ref: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         desktop: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
         tablet: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;

package/dist/modules/mcp/tools/render.d.ts

@@ -52,6 +52,8 @@ export declare const renderShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;
@@ -76,6 +78,7 @@ export declare const renderShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;
         ref: z.ZodString;
@@ -120,6 +123,18 @@ export declare const renderShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteVariable">;
         name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertFlag">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        value: z.ZodBoolean;
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            when: z.ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, z.core.$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: z.ZodBoolean;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteFlag">;
+        name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"upsertBinding">;
         pageRef: z.ZodString;
@@ -223,6 +238,7 @@ export declare const renderShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"patchSettings">;
         customCss: z.ZodOptional<z.ZodString>;
+        notifications: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
         keepState: z.ZodOptional<z.ZodBoolean>;
         stateStorage: z.ZodOptional<z.ZodEnum<{
             localStorage: "localStorage";
@@ -267,6 +283,17 @@ export declare const renderShape: {
             }>>;
             presence: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertComponent">;
+        ref: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        slots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fromRef: z.ZodOptional<z.ZodString>;
+        instanceRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteComponent">;
+        ref: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         desktop: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
         tablet: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;

package/dist/modules/mcp/tools/screenshot.d.ts

@@ -50,6 +50,8 @@ export declare const screenshotShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;
@@ -74,6 +76,7 @@ export declare const screenshotShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;
         ref: z.ZodString;
@@ -118,6 +121,18 @@ export declare const screenshotShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteVariable">;
         name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertFlag">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        value: z.ZodBoolean;
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            when: z.ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, z.core.$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: z.ZodBoolean;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteFlag">;
+        name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"upsertBinding">;
         pageRef: z.ZodString;
@@ -221,6 +236,7 @@ export declare const screenshotShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"patchSettings">;
         customCss: z.ZodOptional<z.ZodString>;
+        notifications: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
         keepState: z.ZodOptional<z.ZodBoolean>;
         stateStorage: z.ZodOptional<z.ZodEnum<{
             localStorage: "localStorage";
@@ -265,6 +281,17 @@ export declare const screenshotShape: {
             }>>;
             presence: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertComponent">;
+        ref: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        slots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fromRef: z.ZodOptional<z.ZodString>;
+        instanceRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteComponent">;
+        ref: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         desktop: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
         tablet: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;

package/dist/modules/mcp/tools/shared/draftBatch.d.ts

@@ -12,6 +12,8 @@ export type DraftResult = {
     draft: Space;
     outcome: MutationOutcome;
     warnings: string[];
+    /** Shorter ways to the same page this batch opened up. Never a reason to refuse it. */
+    suggestions: string[];
 };
 /**
  * A batch run on a copy of the space and read back — the one way every tool that takes operations handles them, so

package/dist/modules/mcp/tools/shared/draftBatch.js

@@ -1,6 +1,7 @@
 import { cloneSpace } from "../../helpers/space.js";
 import { expandOperations } from "./expandOperations.js";
 import { fixTouched, lintDraft } from "./lintDraft.js";
+import { newSuggestions } from "./newSuggestions.js";
 import { validateOperations } from "./validator/index.js";
 import { applyOperations } from "../apply/dispatch.js";
 //#region src/modules/mcp/tools/shared/draftBatch.ts
@@ -51,7 +52,8 @@ var draftBatch = (space, env, operations, mode = "space") => {
 		ops,
 		draft,
 		outcome,
-		warnings
+		warnings,
+		suggestions: newSuggestions(prepared.space, draft)
 	};
 };
 //#endregion

package/dist/modules/mcp/tools/shared/lintDraft.js

@@ -1,5 +1,5 @@
 import { findElementByRef, findPageByRef } from "../../helpers/space.js";
-import { elementSourceTypes, fixSpace, lintSpace } from "@plitzi/sdk-authoring";
+import { authoringCodeEntry, elementSourceTypes, fixSpace, lintSpace } from "@plitzi/sdk-authoring";
 import { validateSchema } from "@plitzi/sdk-schema/helpers/schemaValidator";
 import { styleWithoutTag } from "@plitzi/sdk-schema/helpers/styleWithoutTag";
 //#region src/modules/mcp/tools/shared/lintDraft.ts
@@ -76,6 +76,15 @@ var readingOf = (space) => {
 		]
 	};
 };
+/**
+* An issue as the agent reads it: led by its code, which is how it is filed — the agent has no skill page to look a
+* code up in, so what to write instead comes with it, from the same table `authorSpace` raises it from.
+*/
+var said = (issue) => `[${issue.code}] ${issue.message}`;
+var fixOf = (issue) => {
+	const entry = authoringCodeEntry(issue.code);
+	return entry ? `Write instead: ${entry.fix}.` : "";
+};
 var keyOf = (issue) => JSON.stringify([
 	issue.code,
 	issue.elementId ?? "",
@@ -123,11 +132,14 @@ var lintDraft = (draft, ops, before) => {
 	const preExisting = before && (candidates.length > 0 || touchedWarnings.length > 0) ? preExistingIn(readingOf(before).all, all) : () => false;
 	const toError = (issue) => ({
 		path: issue.elementId ? `element "${issue.elementId}"` : "schema",
-		message: preExisting(issue) ? `Pre-existing malformation in element "${issue.elementId ?? ""}": ${issue.message}` : issue.message,
-		hint: preExisting(issue) ? "This issue already exists in the space (NOT caused by your change), but the save is blocked until you fix it too, in this same batch." : ""
+		message: preExisting(issue) ? `Pre-existing malformation in element "${issue.elementId ?? ""}": ${said(issue)}` : said(issue),
+		hint: [preExisting(issue) ? "This issue already exists in the space (NOT caused by your change), but the save is blocked until you fix it too, in this same batch." : "", fixOf(issue)].filter(Boolean).join(" ")
 	});
 	const errors = candidates.filter((issue) => onTouched(issue) || !preExisting(issue)).map(toError);
-	const warnings = touchedWarnings.map((issue) => preExisting(issue) ? `Pre-existing issue in element "${issue.elementId ?? ""}": ${issue.message}` : issue.message);
+	const warnings = touchedWarnings.map((issue) => {
+		const line = [said(issue), fixOf(issue)].filter(Boolean).join(" ");
+		return preExisting(issue) ? `Pre-existing issue in element "${issue.elementId ?? ""}": ${line}` : line;
+	});
 	for (const id of touched) {
 		const tagless = styleWithoutTag(draft.schema.flat[id], draft.style);
 		if (tagless) warnings.push(`element "${id}" ${tagless}`);

package/dist/modules/mcp/tools/shared/newSuggestions.d.ts

@@ -0,0 +1,7 @@
+import { Space } from '../../helpers';
+/**
+ * The shorter ways to the same page a batch opened up — a header the agent just copied onto a third page, a button it
+ * gave a text child — and none the space already had: those were said when they appeared, and saying them on every
+ * batch would bury the new ones. Not problems: nothing here blocks anything.
+ */
+export declare const newSuggestions: (before: Space, after: Space) => string[];

package/dist/modules/mcp/tools/shared/newSuggestions.js

@@ -0,0 +1,20 @@
+import { suggestSpace } from "@plitzi/sdk-authoring";
+//#region src/modules/mcp/tools/shared/newSuggestions.ts
+var keyOf = ({ code, elementIds }) => `${code}|${[...elementIds].sort().join(",")}`;
+/**
+* The shorter ways to the same page a batch opened up — a header the agent just copied onto a third page, a button it
+* gave a text child — and none the space already had: those were said when they appeared, and saying them on every
+* batch would bury the new ones. Not problems: nothing here blocks anything.
+*/
+var newSuggestions = (before, after) => {
+	const had = new Set(suggestSpace({
+		schema: before.schema,
+		style: before.style
+	}).map(keyOf));
+	return suggestSpace({
+		schema: after.schema,
+		style: after.style
+	}).filter((suggestion) => !had.has(keyOf(suggestion))).map(({ code, message, saves }) => `[${code}] ${message}${saves > 0 ? ` (saves ${String(saves)} element${saves === 1 ? "" : "s"})` : ""}`);
+};
+//#endregion
+export { newSuggestions };

package/dist/modules/mcp/tools/shared/validator/batch.js

@@ -8,7 +8,7 @@ var batchDeclaredVars = (ops) => {
 };
 var batchDeclaredPages = (ops) => {
 	const refs = /* @__PURE__ */ new Set();
-	for (const op of ops) if (op.type === "upsertPage" || op.type === "upsertLayout") refs.add(op.ref);
+	for (const op of ops) if (op.type === "upsertPage" || op.type === "upsertLayout" || op.type === "upsertComponent") refs.add(op.ref);
 	return refs;
 };
 var batchDeclaredFolders = (ops) => {

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

@@ -1,6 +1,7 @@
 import { observedDataSources, observedInteractionActions } from "../../../catalogs/observed.js";
 import { buildTypeRegistry } from "../../../catalogs/registry.js";
 import { elementTypeNames } from "../../../catalogs/index.js";
+import { componentView, findComponentByRef } from "../../../helpers/components.js";
 import { findElementByRef, findFolderByRef, findPageByRef, findRootByRef, folderAncestorIds, getLayoutElements, getPageElements, pageFoldersOf, resolveRef, routeParamNames } from "../../../helpers/space.js";
 import { MAX_OPS } from "../../operations/index.js";
 import { batchDeclaredElements, batchDeclaredFolders, batchDeclaredPages, batchDeclaredVariants, batchDeclaredVars } from "./batch.js";
@@ -11,6 +12,7 @@ import { checkSlotCss } from "./css.js";
 import { checkRef } from "./refs.js";
 import { checkElementInput, checkRawMarkup, checkTypeProps, checkVariantApplication } from "./elements.js";
 import { checkInteractionNode } from "./interactions.js";
+import { treeOf } from "@plitzi/sdk-schema/helpers/components";
 import { isValidElementId } from "@plitzi/sdk-schema/helpers/elementId";
 //#region src/modules/mcp/tools/shared/validator/index.ts
 var STYLE_CATEGORIES = [
@@ -50,8 +52,8 @@ var buildValidationCtx = (space, ops, mode = "space") => {
 		knownTypes: /* @__PURE__ */ new Set([...Object.keys(registry.types), ...elementTypeNames]),
 		typeProps: new Map(Object.entries(registry.types).map(([type, info]) => [type, new Set(Object.keys(info.props))])),
 		typeMeta: buildTypeMeta(space.catalog),
-		elementType: (ref) => (findElementByRef(space.schema, ref) ?? findPageByRef(space.schema, ref))?.definition.type,
-		elementExists: (ref) => batchElements.has(ref) || Boolean(findElementByRef(space.schema, ref) ?? findPageByRef(space.schema, ref)),
+		elementType: (ref) => treeOf(space.schema, ref)?.flat[ref]?.definition.type,
+		elementExists: (ref) => batchElements.has(ref) || treeOf(space.schema, ref) !== void 0,
 		schemaVars: /* @__PURE__ */ new Set([
 			...space.schema.variables.map((v) => v.name),
 			...routeParamNames(space.schema),
@@ -81,13 +83,19 @@ var validateOperations = (space, ops, mode = "space") => {
 	});
 	ops.forEach((op, i) => {
 		const base = `operations[${i}]`;
+		const component = "pageRef" in op ? findComponentByRef(space.schema, op.pageRef) : void 0;
+		const scoped = component ? componentView(space, component).schema : space.schema;
 		if ((op.type === "upsertElement" || op.type === "patchElement" || op.type === "deleteElement" || op.type === "moveElement" || op.type === "upsertBinding" || op.type === "patchBinding" || op.type === "deleteBinding" || op.type === "upsertInteractionFlow" || op.type === "patchInteractionNode" || op.type === "deleteInteraction") && op.pageRef) {
-			if (!findRootByRef(space.schema, op.pageRef) && !batchPages.has(op.pageRef)) {
-				const validRefs = [...getPageElements(space.schema).map((page) => page.id), ...getLayoutElements(space.schema).map((layout) => layout.id)];
+			if (!component && !findRootByRef(space.schema, op.pageRef) && !batchPages.has(op.pageRef)) {
+				const validRefs = [
+					...getPageElements(space.schema).map((page) => page.id),
+					...getLayoutElements(space.schema).map((layout) => layout.id),
+					...Object.keys(space.schema.components)
+				];
 				ctx.errors.push({
 					path: `${base}.pageRef`,
-					message: `Page or layout "${op.pageRef}" does not exist`,
-					hint: "Use an existing page or layout ref, or create the page with upsertPage earlier in the same batch",
+					message: `Page, layout or component "${op.pageRef}" does not exist`,
+					hint: "Use an existing page, layout or component ref, or create it earlier in the same batch",
 					validValues: validRefs
 				});
 			}
@@ -100,8 +108,8 @@ var validateOperations = (space, ops, mode = "space") => {
 				break;
 			case "patchElement": {
 				checkRef(op.ref, `${base}.ref`, ctx);
-				const page = findRootByRef(space.schema, op.pageRef);
-				const target = page ? resolveRef(space.schema, page, op.ref) : void 0;
+				const page = findRootByRef(scoped, component ? component.rootId : op.pageRef);
+				const target = page ? resolveRef(scoped, page, op.ref) : void 0;
 				if (op.props && target && target.id !== page?.id) {
 					checkRawMarkup(target.definition.type, op.props, base, ctx);
 					checkTypeProps(target.definition.type, op.props, base, ctx);
@@ -230,7 +238,7 @@ var validateOperations = (space, ops, mode = "space") => {
 				break;
 			case "patchInteractionNode": {
 				checkRef(op.ref, `${base}.ref`, ctx);
-				const existing = findElementByRef(space.schema, op.ref)?.definition.interactions?.[op.nodeId];
+				const existing = findElementByRef(scoped, op.ref)?.definition.interactions?.[op.nodeId];
 				if (existing) {
 					const merged = {
 						id: existing.id,

package/dist/modules/mcp/tools/validate.d.ts

@@ -51,6 +51,8 @@ export declare const validateShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+        anchor: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deleteElement">;
         pageRef: import('zod').ZodString;
@@ -75,6 +77,7 @@ export declare const validateShape: {
         layout: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         layoutContainer: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         enabled: import('zod').ZodOptional<import('zod').ZodBoolean>;
+        flag: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deletePage">;
         ref: import('zod').ZodString;
@@ -119,6 +122,18 @@ export declare const validateShape: {
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deleteVariable">;
         name: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"upsertFlag">;
+        name: import('zod').ZodString;
+        description: import('zod').ZodOptional<import('zod').ZodString>;
+        value: import('zod').ZodBoolean;
+        rules: import('zod').ZodOptional<import('zod').ZodArray<import('zod').ZodObject<{
+            when: import('zod').ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, import('zod/v4/core').$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: import('zod').ZodBoolean;
+        }, import('zod/v4/core').$strip>>>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteFlag">;
+        name: import('zod').ZodString;
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"upsertBinding">;
         pageRef: import('zod').ZodString;
@@ -222,6 +237,7 @@ export declare const validateShape: {
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"patchSettings">;
         customCss: import('zod').ZodOptional<import('zod').ZodString>;
+        notifications: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodNullable<import('zod').ZodString>>>;
         keepState: import('zod').ZodOptional<import('zod').ZodBoolean>;
         stateStorage: import('zod').ZodOptional<import('zod').ZodEnum<{
             localStorage: "localStorage";
@@ -266,6 +282,17 @@ export declare const validateShape: {
             }>>;
             presence: import('zod').ZodOptional<import('zod').ZodBoolean>;
         }, import('zod/v4/core').$strip>>>>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"upsertComponent">;
+        ref: import('zod').ZodString;
+        label: import('zod').ZodOptional<import('zod').ZodString>;
+        props: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnknown>>;
+        slots: import('zod').ZodOptional<import('zod').ZodArray<import('zod').ZodString>>;
+        fromRef: import('zod').ZodOptional<import('zod').ZodString>;
+        instanceRef: import('zod').ZodOptional<import('zod').ZodString>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteComponent">;
+        ref: import('zod').ZodString;
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
         tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;

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

@@ -8,20 +8,22 @@ var validateShape = {
 };
 var validate = (input, space) => {
 	const result = draftBatch(space, input.environment ?? "main", input.operations);
-	return result.ok ? {
-		valid: true,
-		errors: [],
-		warnings: result.warnings
-	} : {
+	if (!result.ok) return {
 		valid: false,
 		errors: result.errors,
 		warnings: result.warnings
 	};
+	return {
+		valid: true,
+		errors: [],
+		warnings: result.warnings,
+		...result.suggestions.length > 0 ? { suggestions: result.suggestions } : {}
+	};
 };
 var validateTool = defineTool({
 	name: "plitzi_validate",
 	title: "Validate",
-	description: "Check a batch of operations without executing them. Returns teachable errors and warnings — including any PRE-EXISTING malformation in a resource the batch touches (which blocks a save until fixed).",
+	description: "Check a batch of operations without executing them. Returns teachable errors and warnings — including any PRE-EXISTING malformation in a resource the batch touches (which blocks a save until fixed) — and suggestions: shorter ways to the same page the batch opens up (a layout, a component, an element’s own content).",
 	inputShape: validateShape,
 	access: "read",
 	run: (input, ctx) => validate(input, ctx.space)

package/dist/modules/mcp/types/aiSchema.d.ts

@@ -1,4 +1,4 @@
-import { CssProps } from '@plitzi/sdk-authoring';
+import { NotificationsSpec, CssProps } from '@plitzi/sdk-authoring';
 import { ElementRuntime, Environment, WhileRunning } from '@plitzi/sdk-shared';
 export type Env = Environment;
 /** CSS declarations for one selector state. Keys are kebab-case CSS properties (see plitzi://css-properties).
@@ -49,6 +49,26 @@ export interface AILayoutSummary {
     slots: string[];
     elementCount: number;
 }
+/** A component of the space: a reusable subtree, placed on a page as an instance and edited as a root of its own. */
+export interface AIComponentSummary {
+    ref: string;
+    label: string;
+    /** What an instance hands in, each an attribute of the instance and read inside as `{{ props.<name> }}`. */
+    props: Record<string, {
+        type: string;
+        description: string;
+        required?: boolean;
+        default?: unknown;
+        options?: string[];
+    }>;
+    /** Elements of its tree an instance fills with its children, each child naming the one it fills (`slot`). */
+    slots: string[];
+    /** The root of its tree: `pageRef` for every element op inside it is the component's ref. */
+    rootRef: string;
+    /** How many places render it. */
+    instances: number;
+    elementCount: number;
+}
 /** A page folder in the sidebar tree. `ref` is the folder's id; pages reference it
  *  by that id via their `folder`, and nested folders via `parentId`. */
 export interface AIFolder {
@@ -177,6 +197,8 @@ export interface AIElementDetail {
     /** Where this element renders, when it is not the default 'shared'. An apiContainer reading through a connector
      *  is 'server'; one showing 'client' (or nothing) fetches from the browser instead and ignores its connector. */
     runtime?: ElementRuntime;
+    /** The feature flag it exists under — 'name' while on, '!name' while off — when it is gated at all. */
+    flag?: string;
     /** Which variant/visibility this element applies today (element.definition.initialState). */
     initialState?: AIInitialState;
     /** Data bindings on this element, grouped by category. */
@@ -235,7 +257,10 @@ export interface AISchemaVariable {
 /** Space-level settings: the arbitrary global CSS (`customCss`), state persistence, and the user/auth provider
  *  configuration. Every field is optional — a patch changes only the keys it sends. */
 export interface AISettings {
+    /** The space's own global CSS — without the notifications' rule, which reads as `notifications`. */
     customCss?: string;
+    /** How the toasts an `addNotification` step shows look: colours and shape, any CSS value. */
+    notifications?: NotificationsSpec;
     /** Keep `runtime.state` — what `setState` writes — across reloads, filed under whoever is signed in. */
     keepState?: boolean;
     stateStorage?: 'localStorage' | 'sessionStorage';

package/dist/modules/mcp/types/toolTypes.d.ts

@@ -45,6 +45,8 @@ export interface WriteResponse {
     changed: ChangedResource[];
     elements?: WriteElement[];
     warnings?: string[];
+    /** Shorter ways to the same page the batch opened up. Never a reason it was refused. */
+    suggestions?: string[];
     errors?: ValidationError[];
     conflict?: {
         message: string;
@@ -85,6 +87,8 @@ export interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];
     warnings: string[];
+    /** Shorter ways to the same page the batch would open up — a layout, a component, an element's own content. */
+    suggestions?: string[];
 }
 export interface SearchInput {
     query: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-mcp",
-  "version": "0.37.8",
+  "version": "0.37.10",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -30,14 +30,14 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "@plitzi/plitzi-sdk": "0.37.8",
-    "@plitzi/sdk-authoring": "0.37.8",
-    "@plitzi/sdk-elements": "0.37.8",
-    "@plitzi/sdk-interactions": "0.37.8",
-    "@plitzi/sdk-schema": "0.37.8",
-    "@plitzi/sdk-server": "0.37.8",
-    "@plitzi/sdk-shared": "0.37.8",
-    "@plitzi/sdk-style": "0.37.8",
+    "@plitzi/plitzi-sdk": "0.37.10",
+    "@plitzi/sdk-authoring": "0.37.10",
+    "@plitzi/sdk-elements": "0.37.10",
+    "@plitzi/sdk-interactions": "0.37.10",
+    "@plitzi/sdk-schema": "0.37.10",
+    "@plitzi/sdk-server": "0.37.10",
+    "@plitzi/sdk-shared": "0.37.10",
+    "@plitzi/sdk-style": "0.37.10",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "zod": "^4.6.5"