@plitzi/sdk-server 0.32.5 → 0.32.6

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

@@ -1,13 +1,20 @@
-import { deleteElementOp } from "./deleteElement.js";
-import { deleteFolderOp } from "./deleteFolder.js";
-import { deletePageOp } from "./deletePage.js";
-import { deleteVariableOp } from "./deleteVariable.js";
-import { moveElementOp } from "./moveElement.js";
-import { patchElementOp } from "./patchElement.js";
-import { upsertElementOp } from "./upsertElement.js";
-import { upsertFolderOp } from "./upsertFolder.js";
-import { upsertPageOp } from "./upsertPage.js";
-import { upsertVariableOp } from "./upsertVariable.js";
+import { deleteBindingOp } from "./bindings/deleteBinding.js";
+import { patchBindingOp } from "./bindings/patchBinding.js";
+import { upsertBindingOp } from "./bindings/upsertBinding.js";
+import { deleteElementOp } from "./elements/deleteElement.js";
+import { moveElementOp } from "./elements/moveElement.js";
+import { patchElementOp } from "./elements/patchElement.js";
+import { upsertElementOp } from "./elements/upsertElement.js";
+import { deleteFolderOp } from "./folders/deleteFolder.js";
+import { upsertFolderOp } from "./folders/upsertFolder.js";
+import { deleteInteractionOp } from "./interactions/deleteInteraction.js";
+import { patchInteractionNodeOp } from "./interactions/patchInteractionNode.js";
+import { upsertInteractionFlowOp } from "./interactions/upsertInteractionFlow.js";
+import { deletePageOp } from "./pages/deletePage.js";
+import { upsertPageOp } from "./pages/upsertPage.js";
+import { patchSettingsOp } from "./settings/patchSettings.js";
+import { deleteVariableOp } from "./variables/deleteVariable.js";
+import { upsertVariableOp } from "./variables/upsertVariable.js";
 //#region src/modules/mcp/tools/operations/schema/operations.ts
 var elementOps = {
 	upsertElement: upsertElementOp,
@@ -19,7 +26,14 @@ var elementOps = {
 	upsertFolder: upsertFolderOp,
 	deleteFolder: deleteFolderOp,
 	upsertVariable: upsertVariableOp,
-	deleteVariable: deleteVariableOp
+	deleteVariable: deleteVariableOp,
+	upsertBinding: upsertBindingOp,
+	patchBinding: patchBindingOp,
+	deleteBinding: deleteBindingOp,
+	upsertInteractionFlow: upsertInteractionFlowOp,
+	patchInteractionNode: patchInteractionNodeOp,
+	deleteInteraction: deleteInteractionOp,
+	patchSettings: patchSettingsOp
 };
 //#endregion
 export { elementOps };

package/dist/modules/mcp/tools/operations/schema/{deletePage.js → pages/deletePage.js}

@@ -1,8 +1,8 @@
-import { descendantIds, findPageByRef } from "../../../helpers/space.js";
-import { empty, fail } from "../../../helpers/opResult.js";
-import { pageUri, pagesUri } from "./write.js";
+import { descendantIds, findPageByRef, indexRemovePage } from "../../../../helpers/space.js";
+import { pageUri, pagesUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/schema/deletePage.ts
+//#region src/modules/mcp/tools/operations/schema/pages/deletePage.ts
 var deletePageOp = z.object({
 	type: z.literal("deletePage"),
 	ref: z.string().describe("Page ref or id")
@@ -10,8 +10,11 @@ var deletePageOp = z.object({
 var deletePage = (space, env, op) => {
 	const page = findPageByRef(space.schema, op.ref);
 	if (!page) return fail("ref", `Page "${op.ref}" not found`, "Read the pages resource for valid refs");
-	for (const id of [...descendantIds(space.schema, page.id), page.id]) Reflect.deleteProperty(space.schema.flat, id);
+	const descendantElementIds = descendantIds(space.schema, page.id);
+	const descendants = descendantElementIds.map((id) => space.schema.flat[id]);
+	for (const id of [...descendantElementIds, page.id]) Reflect.deleteProperty(space.schema.flat, id);
 	space.schema.pages = space.schema.pages.filter((id) => id !== page.id);
+	indexRemovePage(space.schema, page, descendants);
 	return {
 		...empty(),
 		deleted: 1,

package/dist/modules/mcp/tools/operations/schema/pages/upsertPage.js

@@ -0,0 +1,75 @@
+import { findFolderByRef, findPageByRef, generateObjectId, indexAddPage, indexReRefPage, pageRefOf } from "../../../../helpers/space.js";
+import { pageUri, pagesUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { guardNewRef } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/pages/upsertPage.ts
+var upsertPageOp = z.object({
+	type: z.literal("upsertPage"),
+	ref: z.string().describe("Page id/slug to update, or a new id you choose to create one. On a new page it is stored as its idRef: starts with a letter, then letters, numbers, hyphens and underscores (\"pricing\"), unique across the space."),
+	label: z.string().optional(),
+	slug: z.string().optional().describe("The page URL path, RELATIVE — do NOT start it with \"/\" (the runtime and any parent folder slugs prepend the path; a leading \"/\" is stripped). Good practice: always set one on create for a clean, stable route, e.g. \"pricing\" or \"posts/:postId\" (a \":name\" segment is a route param, readable as {{name}} and as the source navigation.routeParams.name). Omitted on create → the page ref is used as the slug."),
+	folder: z.string().nullable().optional().describe("Ref of an existing folder to place this page in; \"\" or null moves it to the root. Unknown → error"),
+	default: z.boolean().optional(),
+	enabled: z.boolean().optional().describe("false disables the page in the published SDK runtime (not routable/accessible to end users); it stays editable here. Defaults to true")
+}).describe("Create a page, or update it when ref already exists (only the fields you pass change).");
+var upsertPage = (space, env, op) => {
+	const slug = op.slug === void 0 ? void 0 : op.slug.replace(/^\/+/, "");
+	let folderValue;
+	if (op.folder !== void 0) if (op.folder === null || op.folder === "") folderValue = "";
+	else {
+		const resolved = findFolderByRef(space.schema, op.folder);
+		if (!resolved) return fail("folder", `Folder "${op.folder}" not found`, "Create it with upsertFolder, or read plitzi://folders");
+		folderValue = resolved.id;
+	}
+	const existing = findPageByRef(space.schema, op.ref);
+	if (existing) {
+		const oldRef = pageRefOf(existing);
+		existing.attributes = {
+			...existing.attributes,
+			...slug !== void 0 ? { slug } : {},
+			...op.label !== void 0 ? { name: op.label } : {},
+			...op.default !== void 0 ? { default: op.default } : {},
+			...op.enabled !== void 0 ? { enabled: op.enabled } : {},
+			...folderValue !== void 0 ? { folder: folderValue } : {}
+		};
+		indexReRefPage(space.schema, existing, oldRef);
+		return {
+			...empty(),
+			updated: 1,
+			staleResources: [pageUri(env, op.ref), pagesUri(env)]
+		};
+	}
+	const guard = guardNewRef(space, op.ref, "ref");
+	if (guard) return guard;
+	const id = generateObjectId();
+	const attributes = {
+		slug: slug ?? op.ref,
+		name: op.label ?? op.ref,
+		default: op.default ?? false,
+		enabled: op.enabled ?? true,
+		folder: folderValue ?? ""
+	};
+	const page = {
+		id,
+		idRef: op.ref,
+		attributes,
+		definition: {
+			rootId: id,
+			label: op.label ?? op.ref,
+			type: "page",
+			items: [],
+			styleSelectors: { base: "" }
+		}
+	};
+	space.schema.flat[id] = page;
+	space.schema.pages.push(id);
+	indexAddPage(space.schema, page);
+	return {
+		...empty(),
+		created: 1,
+		staleResources: [pageUri(env, op.ref), pagesUri(env)]
+	};
+};
+//#endregion
+export { upsertPage, upsertPageOp };

package/dist/modules/mcp/tools/operations/schema/settings/patchSettings.js

@@ -0,0 +1,45 @@
+import { settingsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/settings/patchSettings.ts
+var userProvider = z.enum([
+	"auth0",
+	"basic",
+	"custom",
+	""
+]);
+var storage = z.enum([
+	"localStorage",
+	"sessionStorage",
+	""
+]);
+var patchSettingsOp = z.object({
+	type: z.literal("patchSettings"),
+	customCss: z.string().optional().describe("Raw global CSS for the whole space (keyframes, @font-face, resets)"),
+	keepState: z.boolean().optional().describe("Persist element state across reloads"),
+	stateStorage: z.enum(["localStorage", "sessionStorage"]).optional(),
+	userProvider: userProvider.optional().describe("Auth provider; \"\" disables authentication"),
+	auth0Domain: z.string().optional(),
+	auth0ClientId: z.string().optional(),
+	tokenStorage: storage.optional(),
+	loginUrl: z.string().optional(),
+	userUrl: z.string().optional(),
+	refreshUrl: z.string().optional(),
+	logoutUrl: z.string().optional(),
+	detailsPath: z.string().optional(),
+	tokenPath: z.string().optional(),
+	expirationTimePath: z.string().optional()
+}).describe("Merge space-level settings: the global CSS (customCss) and the state/auth (user-provider) configuration. Only the fields you pass change; the rest are preserved. Use customCss for site-wide CSS, never to style one element (attach a definition for that).");
+var patchSettings = (space, env, op) => {
+	const { type, ...patch } = op;
+	const next = { ...space.schema.settings };
+	for (const [key, value] of Object.entries(patch)) next[key] = value;
+	space.schema.settings = next;
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [settingsUri(env)]
+	};
+};
+//#endregion
+export { patchSettings, patchSettingsOp };

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

@@ -1,16 +1,73 @@
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/schema/shared.ts
+var combinator = z.enum(["and", "or"]);
+var operator = z.enum([
+	"",
+	"=",
+	"!=",
+	"<",
+	">",
+	"<=",
+	">=",
+	"contains",
+	"doesNotContain",
+	"beginsWith",
+	"doesNotBeginWith",
+	"endsWith",
+	"doesNotEndWith",
+	"empty",
+	"notEmpty",
+	"in",
+	"notIn",
+	"between",
+	"notBetween"
+]);
+var ruleValue = z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.null(),
+	z.record(z.string(), z.unknown()),
+	z.array(z.unknown())
+]);
+var ruleBase = {
+	id: z.string().optional(),
+	field: z.string().describe("The data field the rule tests"),
+	operator,
+	enabled: z.boolean().optional()
+};
+var rule = z.union([z.object({
+	...ruleBase,
+	isBinding: z.literal(true),
+	value: z.string()
+}), z.object({
+	...ruleBase,
+	isBinding: z.literal(false).optional(),
+	value: ruleValue
+})]);
+var ruleGroup = z.lazy(() => z.object({
+	id: z.string().optional(),
+	combinator,
+	rules: z.array(z.union([rule, ruleGroup])),
+	enabled: z.boolean().optional()
+}));
 var styleRefs = z.object({
 	base: z.array(z.string()).optional(),
 	slots: z.record(z.string(), z.array(z.string())).optional()
 });
+var styleVariantInput = z.record(z.string(), z.record(z.string(), z.union([z.string(), z.array(z.string())])));
+var initialStateInput = z.object({
+	styleVariant: styleVariantInput.optional().describe("Variant each attached class uses: { className: { base|slot: variantName | [names] } }"),
+	visibility: z.boolean().optional().describe("Initial visibility of the element")
+});
 var elementInput = z.lazy(() => z.object({
-	ref: z.string().describe("Semantic id you choose, or an existing element ref/id"),
+	ref: z.string().describe("Semantic id you choose, or an existing element ref/id. On a new element this is stored as its idRef and becomes the key everything else addresses it by — its data source is named `<type>_<ref>`, and an interaction targets it by this ref. Start with a letter, then letters, numbers, hyphens and underscores (\"hero-cta\" or \"food_item\"): a dot would break the `<type>_<idRef>.<field>` grammar (an underscore is fine — the first `_` separates the type from the idRef). Must be unique across the space."),
 	type: z.string().describe("Type from plitzi://types"),
 	label: z.string().optional(),
 	subType: z.string().optional(),
 	props: z.record(z.string(), z.unknown()).optional().describe("Full replacement on update"),
 	style: styleRefs.optional().describe("Definition refs per slot; style the element by attaching a definition"),
+	initialState: initialStateInput.optional().describe("Applied style variant(s) and initial visibility (see plitzi://guide styling)"),
 	children: z.array(elementInput).optional()
 }));
 var position = z.enum([
@@ -23,5 +80,40 @@ var scalar = z.union([
 	z.number(),
 	z.boolean()
 ]);
+var bindingCategory = z.enum([
+	"attributes",
+	"style",
+	"initialState"
+]).describe("What the value feeds: a prop (attributes), a style value (style), or an initialState key");
+var bindingTransformer = z.object({
+	action: z.string().describe("Transformer action name"),
+	params: z.record(z.string(), z.string()),
+	enabled: z.boolean().optional().describe("Set false to keep the transformer in the chain but skip it at runtime (defaults to true)")
+});
+var bindingInput = z.object({
+	to: z.string().describe("Target field the value feeds (a prop key, style value, or initialState key)"),
+	source: z.string().describe("Data source path, e.g. \"apiContainer_x.data\" — see plitzi://data-sources"),
+	id: z.string().optional().describe("Stable binding id; generated when omitted"),
+	transformers: z.array(bindingTransformer).optional(),
+	when: ruleGroup.optional().describe("QueryBuilder RuleGroup gating the binding (validated structurally)"),
+	enabled: z.boolean().optional()
+});
+var interactionNodeType = z.enum([
+	"trigger",
+	"globalCallback",
+	"callback",
+	"utility"
+]).describe("trigger starts a flow (must be first); the rest run in order after it");
+var interactionNode = z.object({
+	id: z.string().optional().describe("Existing node id to preserve; generated when omitted"),
+	title: z.string().describe("Human label for the step"),
+	nodeType: interactionNodeType,
+	action: z.string().describe("Action name, e.g. \"onClick\", \"login\" — see plitzi://interactions"),
+	params: z.record(z.string(), z.unknown()).optional(),
+	enabled: z.boolean().optional(),
+	when: ruleGroup.optional().describe("QueryBuilder RuleGroup gating this step (validated structurally)"),
+	elementId: z.string().optional().describe("Element whose callback this step invokes; defaults to this element. Give its ref or its raw id — a raw id is normalised to the element idRef the runtime looks callbacks up by, and a target without an idRef is given one automatically."),
+	preview: z.record(z.string(), z.unknown()).optional()
+});
 //#endregion
-export { elementInput, position, scalar, styleRefs };
+export { bindingCategory, bindingInput, elementInput, initialStateInput, interactionNode, interactionNodeType, position, ruleGroup, scalar, styleRefs, styleVariantInput };

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

@@ -1,9 +1,9 @@
-import { descendantCount, descendantIds, elementById, elementRefOf, getPageElements, isPageElement, orderedChildren, pageFoldersOf, pageRefOf, pageRefOfElement, slugRouteParams } from "../../../helpers/space.js";
-import { definitionToAI, globalStylesForType } from "../style/translator.js";
+import { computeVersion } from "../../../helpers/computeVersion.js";
+import { descendantCount, descendantIds, elementById, elementRefOf, getPageElements, isPageElement, nameOf, orderedChildren, pageFoldersOf, pageRefOf, pageRefOfElement, slugRouteParams, spaceIndex, strOr } from "../../../helpers/space.js";
+import { bindingsToAI, flowsFromInteractions } from "../../../helpers/interactions.js";
+import { definitionToAI, globalStylesForType, idStyleToAI } from "../style/translator.js";
 //#region src/modules/mcp/tools/operations/schema/translator.ts
 var splitClasses = (value) => value ? value.split(/\s+/).filter(Boolean) : [];
-var strOr = (value) => typeof value === "string" ? value : void 0;
-var nameOf = (page) => strOr(page.attributes.name) ?? page.definition.label;
 var propsOf = (el) => {
 	const { subType, ...rest } = el.attributes;
 	return Object.keys(rest).length > 0 ? rest : void 0;
@@ -18,6 +18,7 @@ var pageSummariesToAI = (schema) => getPageElements(schema).map((page) => ({
 	label: nameOf(page),
 	slug: strOr(page.attributes.slug) ?? "",
 	default: page.attributes.default === true,
+	enabled: page.attributes.enabled !== false,
 	folder: strOr(page.attributes.folder) || void 0,
 	elementCount: descendantCount(schema, page.id)
 }));
@@ -32,7 +33,20 @@ var folderRefToAI = (schema, ref) => {
 	const folder = pageFoldersOf(schema).find((f) => f.id === ref);
 	return folder ? folderToAI(folder) : void 0;
 };
-var skeletonNode = (schema, el) => {
+var elementView = (schema, el, style) => {
+	const cache = spaceIndex(schema).detailCache;
+	const cached = cache.get(el.id);
+	if (cached && cached.style === style) return cached;
+	const detail = elementDetailToAI(schema, el, style);
+	const view = {
+		style,
+		detail,
+		version: computeVersion(detail)
+	};
+	cache.set(el.id, view);
+	return view;
+};
+var skeletonNode = (schema, el, style) => {
 	const children = orderedChildren(schema, el);
 	const base = splitClasses(el.definition.styleSelectors.base);
 	const slots = slotClasses(el.definition.styleSelectors);
@@ -41,21 +55,23 @@ var skeletonNode = (schema, el) => {
 		type: el.definition.type,
 		label: el.definition.label,
 		subType: strOr(el.attributes.subType),
+		stateVersion: style ? elementView(schema, el, style).version : void 0,
 		base: base.length > 0 ? base : void 0,
 		slots: Object.keys(slots).length > 0 ? slots : void 0,
 		childCount: children.length,
-		children: children.length > 0 ? children.map((child) => skeletonNode(schema, child)) : void 0
+		children: children.length > 0 ? children.map((child) => skeletonNode(schema, child, style)) : void 0
 	};
 };
-var pageSkeletonToAI = (schema, pageEl) => {
+var pageSkeletonToAI = (schema, pageEl, style) => {
 	const slug = strOr(pageEl.attributes.slug) ?? "";
 	return {
 		ref: pageRefOf(pageEl),
 		label: nameOf(pageEl),
 		slug,
 		default: pageEl.attributes.default === true,
+		enabled: pageEl.attributes.enabled !== false,
 		routeParams: slugRouteParams(slug),
-		tree: orderedChildren(schema, pageEl).map((child) => skeletonNode(schema, child))
+		tree: orderedChildren(schema, pageEl).map((child) => skeletonNode(schema, child, style))
 	};
 };
 var elementClassRefs = (el) => {
@@ -102,6 +118,37 @@ var resolveDefinitions = (style, base, slots) => {
 	}
 	return Object.keys(resolved).length > 0 ? resolved : void 0;
 };
+var variantNamesOf = (def) => {
+	const names = new Set(Object.keys(def.variants ?? {}));
+	for (const slot of Object.values(def.slots ?? {})) for (const name of Object.keys(slot.variants ?? {})) names.add(name);
+	return [...names].sort();
+};
+var availableVariantsFrom = (resolvedStyle) => {
+	if (!resolvedStyle) return;
+	const result = {};
+	for (const [ref, def] of Object.entries(resolvedStyle)) {
+		const names = variantNamesOf(def);
+		if (names.length > 0) result[ref] = names;
+	}
+	return Object.keys(result).length > 0 ? result : void 0;
+};
+var initialStateToAI = (el) => {
+	const initialState = el.definition.initialState;
+	if (!initialState) return;
+	const result = {};
+	if (initialState.styleVariant) {
+		const styleVariant = {};
+		for (const [cls, selectors] of Object.entries(initialState.styleVariant)) {
+			if (!selectors) continue;
+			const bySelector = {};
+			for (const [selector, variant] of Object.entries(selectors)) if (variant !== void 0) bySelector[selector] = variant;
+			if (Object.keys(bySelector).length > 0) styleVariant[cls] = bySelector;
+		}
+		if (Object.keys(styleVariant).length > 0) result.styleVariant = styleVariant;
+	}
+	if (typeof initialState.visibility === "boolean") result.visibility = initialState.visibility;
+	return Object.keys(result).length > 0 ? result : void 0;
+};
 var elementDetailToAI = (schema, el, style) => {
 	const children = orderedChildren(schema, el);
 	const parent = el.definition.parentId ? schema.flat[el.definition.parentId] : void 0;
@@ -121,11 +168,26 @@ var elementDetailToAI = (schema, el, style) => {
 		},
 		childRefs: children.length > 0 ? children.map(elementRefOf) : void 0
 	};
+	const initialState = initialStateToAI(el);
+	if (initialState) detail.initialState = initialState;
+	const bindings = bindingsToAI(el.definition.bindings);
+	if (bindings) detail.bindings = bindings;
+	const interactions = flowsFromInteractions(el.definition.interactions);
+	if (interactions.length > 0) detail.interactions = interactions;
 	if (style) {
 		const resolvedStyle = resolveDefinitions(style, base, slots);
-		if (resolvedStyle) detail.resolvedStyle = resolvedStyle;
+		if (resolvedStyle) {
+			detail.resolvedStyle = resolvedStyle;
+			const availableVariants = availableVariantsFrom(resolvedStyle);
+			if (availableVariants) detail.availableVariants = availableVariants;
+		}
 		const globalStyles = globalStylesForType(style, el.definition.type);
 		if (globalStyles.length > 0) detail.globalStyles = globalStyles;
+		const domId = strOr(el.attributes.id);
+		if (domId) {
+			const idStyle = idStyleToAI(style, domId);
+			if (idStyle) detail.idStyle = idStyle;
+		}
 	}
 	return detail;
 };
@@ -144,5 +206,10 @@ var schemaVariablesToAI = (schema, includeSubValues = true) => {
 	};
 	return data;
 };
+var settingsToAI = (schema) => {
+	const result = {};
+	for (const [key, value] of Object.entries(schema.settings)) result[key] = value;
+	return result;
+};
 //#endregion
-export { elementDetailToAI, folderRefToAI, foldersToAI, pageSkeletonToAI, pageStylesToAI, pageSummariesToAI, schemaVariablesToAI };
+export { elementDetailToAI, elementView, folderRefToAI, foldersToAI, pageSkeletonToAI, pageStylesToAI, pageSummariesToAI, schemaVariablesToAI, settingsToAI };

package/dist/modules/mcp/tools/operations/schema/{deleteVariable.js → variables/deleteVariable.js}

@@ -1,7 +1,7 @@
-import { empty } from "../../../helpers/opResult.js";
-import { schemaVarsUri } from "./write.js";
+import { schemaVarsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/schema/deleteVariable.ts
+//#region src/modules/mcp/tools/operations/schema/variables/deleteVariable.ts
 var deleteVariableOp = z.object({
 	type: z.literal("deleteVariable"),
 	name: z.string().describe("Name of the schema variable to delete")

package/dist/modules/mcp/tools/operations/schema/{upsertVariable.js → variables/upsertVariable.js}

@@ -1,8 +1,8 @@
-import { empty } from "../../../helpers/opResult.js";
-import { schemaVarsUri } from "./write.js";
-import { scalar } from "./shared.js";
+import { schemaVarsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { scalar } from "../shared.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/schema/upsertVariable.ts
+//#region src/modules/mcp/tools/operations/schema/variables/upsertVariable.ts
 var upsertVariableOp = z.object({
 	type: z.literal("upsertVariable"),
 	name: z.string().describe("Variable name; referenced in content as {{name}}"),

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

@@ -1,18 +1,51 @@
-import { generateObjectId } from "../../../helpers/space.js";
+import { findElementByRef, findPageByRef, generateObjectId, indexAddElement, indexReRefElement, resolveRef, spaceIndex } from "../../../helpers/space.js";
+import { folderUri, foldersUri, pageUri, pagesUri, schemaVarsUri, settingsUri } from "../../../helpers/uris.js";
+import { fail } from "../../../helpers/opResult.js";
+import { isValidIdRef, makeIdRef } from "@plitzi/sdk-schema/helpers/idRef";
 //#region src/modules/mcp/tools/operations/schema/write.ts
-var pageUri = (env, ref) => `plitzi://schema/${env}/pages/${ref}`;
-var pagesUri = (env) => `plitzi://schema/${env}/pages`;
-var foldersUri = (env) => `plitzi://folders/${env}`;
-var folderUri = (env, ref) => `plitzi://folders/${env}/${ref}`;
-var schemaVarsUri = (env) => `plitzi://schema-variables/${env}`;
-var removeFromParent = (space, childId) => {
-	for (const el of Object.values(space.schema.flat)) if (el.definition.items?.includes(childId)) el.definition.items = el.definition.items.filter((id) => id !== childId);
+var ID_REF_HINT = "Start with a letter, then letters, numbers, hyphens and underscores (e.g. \"hero-cta\" or \"food_item\"). The ref becomes the element idRef, which the runtime embeds in source names like `apiContainer_<idRef>.field` and in interaction targets — a dot would split those paths (an underscore is fine: the FIRST `_` separates the type from the idRef, and element types carry none, so extra underscores are unambiguous).";
+var TAKEN_HINT = "An idRef must be unique across the space — pick a different ref, or address the existing element by this ref.";
+/** Every ref in an element input tree (the element plus its nested children) — each becomes a new element's idRef. */
+var collectInputRefs = (input) => [input.ref, ...(input.children ?? []).flatMap(collectInputRefs)];
+/** Validate a ref that is about to become an element's idRef: the charset, then whether anything already answers
+*  to it. The charset rule is sdk-schema's `isValidIdRef` — never a regex restated here, so the MCP cannot drift
+*  from what the builder and the schema validator enforce.
+*
+*  Uniqueness is checked with the ref lookups rather than `FlatMap.idRefConflict`, and deliberately so: these are
+*  a superset of it. FlatMap asks whether another element holds this idRef; the MCP must also refuse a ref that
+*  shadows a raw id or a page slug, because its handlers resolve refs through those too — calling both would just
+*  run the same rule twice. Null when the ref is usable.
+*
+*  Enforced here, at every point a ref BECOMES an idRef — addressing an existing element by its raw id is not
+*  charset-checked, which is why the validator cannot simply tighten its own REF_RE for every ref it sees. */
+var guardNewRef = (space, ref, field) => {
+	if (!isValidIdRef(ref)) return fail(field, `"${ref}" is not a valid idRef`, ID_REF_HINT);
+	if (findElementByRef(space.schema, ref) || findPageByRef(space.schema, ref)) return fail(field, `"${ref}" is already used by another element in this space`, TAKEN_HINT);
+	return null;
+};
+var removeFromParent = (space, child) => {
+	const parent = child.definition.parentId ? space.schema.flat[child.definition.parentId] : void 0;
+	if (parent?.definition.items) parent.definition.items = parent.definition.items.filter((id) => id !== child.id);
 };
 var placeChild = (parent, childId, index) => {
 	const items = parent.definition.items ?? (parent.definition.items = []);
 	if (index === void 0 || index < 0 || index >= items.length) items.push(childId);
 	else items.splice(index, 0, childId);
 };
+var writeInitialState = (el, input, merge) => {
+	const current = el.definition.initialState ?? {};
+	const next = { ...current };
+	if (input.styleVariant !== void 0) if (merge) {
+		const merged = { ...current.styleVariant };
+		for (const [cls, selectors] of Object.entries(input.styleVariant)) merged[cls] = {
+			...merged[cls],
+			...selectors
+		};
+		next.styleVariant = merged;
+	} else next.styleVariant = input.styleVariant;
+	if (input.visibility !== void 0) next.visibility = input.visibility;
+	el.definition.initialState = next;
+};
 var createElement = (space, page, input, parent, index) => {
 	const id = generateObjectId();
 	const { subType, ...props } = {
@@ -21,8 +54,9 @@ var createElement = (space, page, input, parent, index) => {
 	};
 	const styleSelectors = { base: (input.style?.base ?? []).join(" ") };
 	for (const [slot, classes] of Object.entries(input.style?.slots ?? {})) styleSelectors[slot] = classes.join(" ");
-	space.schema.flat[id] = {
+	const el = {
 		id,
+		idRef: input.ref,
 		attributes: subType === void 0 ? props : {
 			subType,
 			...props
@@ -33,12 +67,43 @@ var createElement = (space, page, input, parent, index) => {
 			label: input.label ?? input.ref,
 			type: input.type,
 			items: [],
-			styleSelectors,
-			aiRef: input.ref
+			styleSelectors
 		}
 	};
+	space.schema.flat[id] = el;
 	placeChild(parent, id, index);
-	for (const child of input.children ?? []) createElement(space, page, child, space.schema.flat[id], void 0);
+	indexAddElement(space.schema, el, page.id);
+	if (input.initialState) writeInitialState(el, input.initialState, false);
+	for (const child of input.children ?? []) createElement(space, page, child, el, void 0);
+};
+/** The idRef an element is wired by, minting one when it has none. Interactions are keyed by idRef, so an element
+*  that is about to host or be targeted by a flow must have one — rather than make the agent assign it with a
+*  separate patchElement, the MCP gives it a free `<type>-<n>` ref (unique across the space) and proceeds. An
+*  element that already has an idRef keeps it. Mutates the element in place and returns the ref. */
+var ensureIdRef = (space, el) => {
+	if (el.idRef) return el.idRef;
+	const index = spaceIndex(space.schema);
+	el.idRef = makeIdRef(el.definition.type, (candidate) => index.elementByRef.has(candidate) || index.pageByRef.has(candidate));
+	indexReRefElement(space.schema, el);
+	return el.idRef;
+};
+/** The key an interaction node must store to reach a target element. Every ref field also accepts a raw id, so a
+*  target given as an id is resolved to the element's idRef — the key the runtime registers callbacks under. A
+*  target that has no idRef is given one (see `ensureIdRef`), since it must be reachable to be wired to. A target
+*  that resolves to no element is left as written — it is already a ref, or a key only a plugin knows. */
+var resolveTargetRef = (space, elementId) => {
+	const el = space.schema.flat[elementId] ?? findElementByRef(space.schema, elementId);
+	return el ? ensureIdRef(space, el) : elementId;
+};
+/** Resolve a non-page element within a page for the element-scoped ops (bindings, interactions). Returns the
+*  element, or a teachable OpResult when the page or element ref does not resolve — so each op reports the same
+*  errors as patchElement without repeating them. */
+var resolveElement = (space, env, pageRef, ref) => {
+	const page = findPageByRef(space.schema, pageRef);
+	if (!page) return { error: fail("pageRef", `Page "${pageRef}" not found`, `Read plitzi://schema/${env}/pages for valid refs`) };
+	const el = resolveRef(space.schema, page, ref);
+	if (!el || el.id === page.id) return { error: fail("ref", `Element "${ref}" not found in page "${pageRef}"`, "Use an existing element ref or id") };
+	return { el };
 };
 //#endregion
-export { createElement, folderUri, foldersUri, pageUri, pagesUri, placeChild, removeFromParent, schemaVarsUri };
+export { ID_REF_HINT, collectInputRefs, createElement, ensureIdRef, folderUri, foldersUri, guardNewRef, pageUri, pagesUri, placeChild, removeFromParent, resolveElement, resolveTargetRef, schemaVarsUri, settingsUri, writeInitialState };

package/dist/modules/mcp/tools/operations/style/{deleteDefinition.js → definitions/deleteDefinition.js}

@@ -1,7 +1,8 @@
-import { empty } from "../../../helpers/opResult.js";
-import { MODES, defUri, defsUri, guardKind } from "./write.js";
+import { defUri, defsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { MODES, guardKind } from "../write.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/deleteDefinition.ts
+//#region src/modules/mcp/tools/operations/style/definitions/deleteDefinition.ts
 var deleteDefinitionOp = z.object({
 	type: z.literal("deleteDefinition"),
 	ref: z.string().describe("Class ref of the definition to delete")

package/dist/modules/mcp/tools/operations/style/{patchDefinition.js → definitions/patchDefinition.js}

@@ -1,9 +1,10 @@
-import { empty, fail } from "../../../helpers/opResult.js";
-import { definitionToAI } from "./translator.js";
-import { defUri, defsUri, guardKind, mergePatch, writeStyleItem } from "./write.js";
-import { patchCssShape } from "./shared.js";
+import { defUri, defsUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { definitionToAI } from "../translator.js";
+import { guardKind, mergePatch, writeStyleItem } from "../write.js";
+import { patchCssShape } from "../shared.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/patchDefinition.ts
+//#region src/modules/mcp/tools/operations/style/definitions/patchDefinition.ts
 var patchDefinitionOp = z.object({
 	type: z.literal("patchDefinition"),
 	ref: z.string().describe("Existing class ref to patch"),