@plitzi/sdk-mcp 0.37.8 → 0.37.10

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

@@ -0,0 +1,147 @@
+import { invalidateIndex } from "../../../../helpers/space.js";
+import { componentsUri, pageUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { ID_REF_HINT, guardNewRef } from "../write.js";
+import { addComponent, componentNamed, propNameProblem, treeOf, updateComponent } from "@plitzi/sdk-schema/helpers/components";
+import { descendants } from "@plitzi/sdk-schema/helpers/elementTree";
+import { z } from "zod";
+import { isValidElementId } from "@plitzi/sdk-schema/helpers/elementId";
+//#region src/modules/mcp/tools/operations/schema/components/upsertComponent.ts
+/**
+* A prop as a component declares it. Checked when the op runs rather than spelled out in the op's schema: the op union
+* rides on every request of every conversation, and the guide — read once — says what a prop is.
+*/
+var componentProp = z.object({
+	type: z.enum([
+		"text",
+		"textarea",
+		"number",
+		"boolean",
+		"select",
+		"scalar",
+		"json"
+	]),
+	description: z.string(),
+	required: z.boolean().optional(),
+	default: z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	]).optional(),
+	options: z.array(z.string()).optional(),
+	label: z.string().optional()
+});
+var upsertComponentOp = z.object({
+	type: z.literal("upsertComponent"),
+	ref: z.string(),
+	label: z.string().optional(),
+	props: z.record(z.string(), z.unknown()).optional().describe("{ name: { type, description, required?, default?, options? } }"),
+	slots: z.array(z.string()).optional(),
+	fromRef: z.string().optional().describe("New only: the element it is made of"),
+	instanceRef: z.string().optional().describe("With fromRef: the instance left in its place")
+}).describe("Declare or update a component; edit inside it with pageRef: \"<ref>\". See \"Components\" in plitzi://guide.");
+/** The declaration an op writes, with nothing it leaves out — an update keeps what it does not name. */
+var declarationOf = (op, props) => ({
+	...op.label === void 0 ? {} : { label: op.label },
+	...props === void 0 ? {} : { props },
+	...op.slots === void 0 ? {} : { slots: op.slots }
+});
+/** The props an op declares, each held to what a prop is — or why one is not, by name. */
+var parseProps = (props) => {
+	if (props === void 0) return {};
+	const parsed = {};
+	for (const [name, value] of Object.entries(props)) {
+		const result = componentProp.safeParse(value);
+		if (!result.success) return { error: `prop "${name}" is not a prop: ${result.error.issues.map((issue) => `${issue.path.join(".") || "it"} ${issue.message}`).join("; ")}` };
+		parsed[name] = result.data;
+	}
+	return { props: parsed };
+};
+/** Why a declaration cannot stand, in words, or undefined: the same two rules `sdk-schema` holds every writer to. */
+var declarationProblem = (declaration, flat) => {
+	for (const name of Object.keys(declaration.props ?? {})) {
+		const problem = propNameProblem(name);
+		if (problem) return problem;
+	}
+	const missing = (declaration.slots ?? []).find((slot) => !Object.hasOwn(flat, slot));
+	return missing ? `slot "${missing}" is not an element of the component` : void 0;
+};
+var upsertComponent = (space, env, op) => {
+	const { schema } = space;
+	const stale = [componentsUri(env), pageUri(env, op.ref)];
+	const props = parseProps(op.props);
+	if ("error" in props) return fail("props", props.error, "A prop is { type: \"text\" | \"textarea\" | \"number\" | \"boolean\" | \"select\" | \"scalar\" | \"json\", description, required?, default?, options? }");
+	const declaration = declarationOf(op, props.props);
+	const existing = componentNamed(schema, op.ref);
+	if (existing) {
+		if (op.fromRef) return fail("fromRef", `Component "${op.ref}" already exists`, "fromRef makes a NEW component; pick another ref");
+		const problem = declarationProblem({
+			...existing,
+			...declaration
+		}, existing.flat);
+		if (problem || !updateComponent(schema, op.ref, {
+			...existing,
+			...declaration
+		})) return fail("props", problem ?? `Component "${op.ref}" refused the declaration`, "Name props as {{ props.<name> }} reads them, and slots as elements of the tree");
+		return {
+			...empty(),
+			updated: 1,
+			staleResources: stale
+		};
+	}
+	if (!isValidElementId(op.ref)) return fail("ref", `"${op.ref}" is not a name a component can have`, ID_REF_HINT);
+	if (op.fromRef) {
+		const tree = treeOf(schema, op.fromRef);
+		const element = tree?.flat[op.fromRef];
+		if (!tree || !element?.definition.parentId) return fail("fromRef", `"${op.fromRef}" is not an element inside a page, a layout or a component`, "A page or a layout is a root, not a subtree — name an element inside one");
+		if (!op.instanceRef) return fail("instanceRef", "fromRef needs the name of the instance that takes the element’s place", "e.g. instanceRef: \"hero-card\"");
+		const guard = guardNewRef(space, op.instanceRef, "instanceRef");
+		if (guard) return guard;
+		const component = {
+			...declaration,
+			id: op.ref,
+			rootId: "",
+			flat: {}
+		};
+		const problem = declarationProblem(declaration, Object.fromEntries([op.fromRef, ...descendants(tree.flat, op.fromRef)].map((id) => [id, tree.flat[id]])));
+		if (problem || !addComponent(schema, component, {
+			elementId: op.fromRef,
+			instanceId: op.instanceRef
+		})) return fail("props", problem ?? `"${op.fromRef}" could not be made a component`, "Slots name elements inside fromRef");
+		invalidateIndex(schema);
+		return {
+			...empty(),
+			created: 1,
+			staleResources: stale,
+			elementRefs: [op.instanceRef]
+		};
+	}
+	const rootRef = `${op.ref}-root`;
+	const guard = guardNewRef(space, rootRef, "ref");
+	if (guard) return guard;
+	const component = {
+		...declaration,
+		id: op.ref,
+		rootId: rootRef,
+		flat: { [rootRef]: {
+			id: rootRef,
+			attributes: { subType: "div" },
+			definition: {
+				label: op.label ?? op.ref,
+				type: "container",
+				rootId: rootRef,
+				items: [],
+				styleSelectors: { base: "" }
+			}
+		} }
+	};
+	const problem = declarationProblem(declaration, component.flat);
+	if (problem || !addComponent(schema, component)) return fail("props", problem ?? `Component "${op.ref}" could not be declared`, "A new component has one element yet — its root; add the rest with upsertElement { pageRef: \"<ref>\" } first, then name slots");
+	return {
+		...empty(),
+		created: 1,
+		staleResources: stale
+	};
+};
+//#endregion
+export { upsertComponent, upsertComponentOp };

package/dist/modules/mcp/tools/operations/schema/elements/patchElement.d.ts

@@ -22,6 +22,8 @@ export declare const patchElementOp: z.ZodObject<{
         client: "client";
         shared: "shared";
     }>>;
+    flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type PatchElement = z.infer<typeof patchElementOp>;
 export declare const patchElement: (space: Space, env: Env, op: PatchElement) => OpResult;

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

@@ -1,8 +1,9 @@
 import { findRootByRef, invalidateIndex, resolveRef } from "../../../../helpers/space.js";
 import { pageUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
-import { elementRuntime, initialStateInput, styleRefs } from "../shared.js";
+import { elementAnchor, elementFlag, elementRuntime, initialStateInput, styleRefs } from "../shared.js";
 import { guardNewRef, writeInitialState } from "../write.js";
+import { flagGateOf } from "@plitzi/sdk-authoring";
 import { z } from "zod";
 import { repointIds } from "@plitzi/sdk-schema/helpers/elementId";
 //#region src/modules/mcp/tools/operations/schema/elements/patchElement.ts
@@ -16,7 +17,9 @@ var patchElementOp = z.object({
 	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"),
-	runtime: elementRuntime.optional()
+	runtime: elementRuntime.optional(),
+	flag: elementFlag.nullable().optional(),
+	anchor: elementAnchor.nullable().optional().describe("null removes it")
 }).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 = findRootByRef(space.schema, op.pageRef);
@@ -48,6 +51,10 @@ var patchElement = (space, env, op) => {
 	}
 	if (op.initialState !== void 0) writeInitialState(el, op.initialState, true);
 	if (op.runtime !== void 0) el.definition.runtime = op.runtime;
+	if (op.flag === null) Reflect.deleteProperty(el.definition, "flag");
+	else if (op.flag !== void 0) el.definition.flag = flagGateOf(op.flag, `Element "${op.ref}"`);
+	if (op.anchor === null) Reflect.deleteProperty(el.definition, "anchor");
+	else if (op.anchor !== void 0) el.definition.anchor = op.anchor;
 	return {
 		...empty(),
 		updated: 1,

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

@@ -3,6 +3,7 @@ import { pageUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
 import { elementInput, position } from "../shared.js";
 import { DROP_POSITION, collectInputRefs, createElement, guardNewRef, writeInitialState } from "../write.js";
+import { flagGateOf } from "@plitzi/sdk-authoring";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/schema/elements/upsertElement.ts
 var upsertElementOp = z.object({
@@ -32,6 +33,8 @@ var upsertElement = (space, env, op) => {
 		}
 		if (op.element.initialState !== void 0) writeInitialState(existing, op.element.initialState, false);
 		if (op.element.runtime !== void 0) existing.definition.runtime = op.element.runtime;
+		if (op.element.flag !== void 0) existing.definition.flag = flagGateOf(op.element.flag, `Element "${op.element.ref}"`);
+		if (op.element.anchor !== void 0) existing.definition.anchor = op.element.anchor;
 		return {
 			...empty(),
 			updated: 1,

package/dist/modules/mcp/tools/operations/schema/flags/deleteFlag.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { Space, OpResult } from '../../../../helpers';
+import { Env } from '../../../../types';
+export declare const deleteFlagOp: z.ZodObject<{
+    type: z.ZodLiteral<"deleteFlag">;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type DeleteFlag = z.infer<typeof deleteFlagOp>;
+export declare const deleteFlag: (space: Space, env: Env, op: DeleteFlag) => OpResult;

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

@@ -0,0 +1,21 @@
+import { flagsUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/flags/deleteFlag.ts
+var deleteFlagOp = z.object({
+	type: z.literal("deleteFlag"),
+	name: z.string()
+}).describe("Remove a feature flag.");
+var deleteFlag = (space, env, op) => {
+	const flags = space.schema.flags ?? {};
+	if (!Object.hasOwn(flags, op.name)) return fail("name", `The space declares no flag "${op.name}"`, `Read ${flagsUri(env)}`);
+	const { [op.name]: _removed, ...rest } = flags;
+	space.schema.flags = rest;
+	return {
+		...empty(),
+		deleted: 1,
+		staleResources: [flagsUri(env)]
+	};
+};
+//#endregion
+export { deleteFlag, deleteFlagOp };

package/dist/modules/mcp/tools/operations/schema/flags/upsertFlag.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { Space, OpResult } from '../../../../helpers';
+import { Env } from '../../../../types';
+export declare const upsertFlagOp: 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>;
+export type UpsertFlag = z.infer<typeof upsertFlagOp>;
+export declare const upsertFlag: (space: Space, env: Env, op: UpsertFlag) => OpResult;

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

@@ -0,0 +1,38 @@
+import { flagsUri } from "../../../../helpers/uris.js";
+import { empty, fail } from "../../../../helpers/opResult.js";
+import { ruleGroup } from "../shared.js";
+import { z } from "zod";
+import { isFlagName, isSchemaFlag } from "@plitzi/sdk-shared/flags";
+//#region src/modules/mcp/tools/operations/schema/flags/upsertFlag.ts
+var ruleInput = z.object({
+	when: ruleGroup,
+	value: z.boolean()
+});
+var upsertFlagOp = z.object({
+	type: z.literal("upsertFlag"),
+	name: z.string(),
+	description: z.string().optional(),
+	value: z.boolean().describe("When no rule matches"),
+	rules: z.array(ruleInput).optional()
+}).describe("Declare or replace a feature flag (guide: Feature flags).");
+var upsertFlag = (space, env, op) => {
+	if (!isFlagName(op.name)) return fail("name", `"${op.name}" is not a flag name`, "Letters, digits and \"_\", starting with a letter or \"_\"");
+	const flag = {
+		...op.description ? { description: op.description } : {},
+		value: op.value,
+		rules: op.rules ?? []
+	};
+	if (!isSchemaFlag(flag)) return fail("rules", "A rule is { when: { combinator, rules: [...] }, value: true | false }", "Fix the rule groups");
+	const existed = Object.hasOwn(space.schema.flags ?? {}, op.name);
+	space.schema.flags = {
+		...space.schema.flags,
+		[op.name]: flag
+	};
+	return {
+		...empty(),
+		...existed ? { updated: 1 } : { created: 1 },
+		staleResources: [flagsUri(env)]
+	};
+};
+//#endregion
+export { upsertFlag, upsertFlagOp };

package/dist/modules/mcp/tools/operations/schema/index.d.ts

@@ -14,6 +14,8 @@ export * from './folders/upsertFolder';
 export * from './folders/deleteFolder';
 export * from './variables/upsertVariable';
 export * from './variables/deleteVariable';
+export * from './flags/upsertFlag';
+export * from './flags/deleteFlag';
 export * from './bindings/upsertBinding';
 export * from './bindings/patchBinding';
 export * from './bindings/deleteBinding';
@@ -21,3 +23,4 @@ export * from './interactions/upsertInteractionFlow';
 export * from './interactions/patchInteractionNode';
 export * from './interactions/deleteInteraction';
 export * from './settings/patchSettings';
+export * from './components';

package/dist/modules/mcp/tools/operations/schema/operations.d.ts

@@ -50,6 +50,8 @@ export declare const elementOps: {
             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>;
     deleteElement: import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deleteElement">;
@@ -77,6 +79,7 @@ export declare const elementOps: {
         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>;
     deletePage: import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deletePage">;
@@ -129,6 +132,20 @@ export declare const elementOps: {
         type: import('zod').ZodLiteral<"deleteVariable">;
         name: import('zod').ZodString;
     }, import('zod/v4/core').$strip>;
+    upsertFlag: 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>;
+    deleteFlag: import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteFlag">;
+        name: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>;
     upsertBinding: import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"upsertBinding">;
         pageRef: import('zod').ZodString;
@@ -238,6 +255,7 @@ export declare const elementOps: {
     patchSettings: 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";
@@ -283,4 +301,17 @@ export declare const elementOps: {
             presence: import('zod').ZodOptional<import('zod').ZodBoolean>;
         }, import('zod/v4/core').$strip>>>>;
     }, import('zod/v4/core').$strip>;
+    upsertComponent: 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>;
+    deleteComponent: import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteComponent">;
+        ref: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>;
 };

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

@@ -1,11 +1,15 @@
 import { deleteBindingOp } from "./bindings/deleteBinding.js";
 import { patchBindingOp } from "./bindings/patchBinding.js";
 import { upsertBindingOp } from "./bindings/upsertBinding.js";
+import { deleteComponentOp } from "./components/deleteComponent.js";
+import { upsertComponentOp } from "./components/upsertComponent.js";
 import { deleteElementOp } from "./elements/deleteElement.js";
 import { moveElementOp } from "./elements/moveElement.js";
 import { patchElementOp } from "./elements/patchElement.js";
 import { repeatElementOp } from "./elements/repeatElement.js";
 import { upsertElementOp } from "./elements/upsertElement.js";
+import { deleteFlagOp } from "./flags/deleteFlag.js";
+import { upsertFlagOp } from "./flags/upsertFlag.js";
 import { deleteFolderOp } from "./folders/deleteFolder.js";
 import { upsertFolderOp } from "./folders/upsertFolder.js";
 import { deleteInteractionOp } from "./interactions/deleteInteraction.js";
@@ -33,13 +37,17 @@ var elementOps = {
 	deleteFolder: deleteFolderOp,
 	upsertVariable: upsertVariableOp,
 	deleteVariable: deleteVariableOp,
+	upsertFlag: upsertFlagOp,
+	deleteFlag: deleteFlagOp,
 	upsertBinding: upsertBindingOp,
 	patchBinding: patchBindingOp,
 	deleteBinding: deleteBindingOp,
 	upsertInteractionFlow: upsertInteractionFlowOp,
 	patchInteractionNode: patchInteractionNodeOp,
 	deleteInteraction: deleteInteractionOp,
-	patchSettings: patchSettingsOp
+	patchSettings: patchSettingsOp,
+	upsertComponent: upsertComponentOp,
+	deleteComponent: deleteComponentOp
 };
 //#endregion
 export { elementOps };

package/dist/modules/mcp/tools/operations/schema/pages/upsertPage.d.ts

@@ -11,6 +11,7 @@ export declare const upsertPageOp: z.ZodObject<{
     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>;
 export type UpsertPage = z.infer<typeof upsertPageOp>;
 export declare const upsertPage: (space: Space, env: Env, op: UpsertPage) => OpResult;

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

@@ -1,7 +1,9 @@
 import { findFolderByRef, findLayoutByRef, findPageByRef, indexAddPage, resolveRef } from "../../../../helpers/space.js";
 import { layoutsUri, pageUri, pagesUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
+import { elementFlag } from "../shared.js";
 import { guardNewRef } from "../write.js";
+import { flagGateOf } from "@plitzi/sdk-authoring";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/schema/pages/upsertPage.ts
 var upsertPageOp = z.object({
@@ -13,7 +15,8 @@ var upsertPageOp = z.object({
 	default: z.boolean().optional(),
 	layout: z.string().nullable().optional().describe("Ref of the layout shell this page renders inside; \"\" or null detaches it. See plitzi://schema/{env}/layouts."),
 	layoutContainer: z.string().nullable().optional().describe("Ref of the container INSIDE that shell where this page body goes — the slot. Must belong to it."),
-	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")
+	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"),
+	flag: elementFlag.nullable().optional()
 }).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(/^\/+/, "");
@@ -63,6 +66,8 @@ var upsertPage = (space, env, op) => {
 			...layoutValue !== void 0 ? { layout: layoutValue } : {},
 			...slotValue !== void 0 ? { layoutContainer: slotValue } : {}
 		};
+		if (op.flag === null) Reflect.deleteProperty(existing.definition, "flag");
+		else if (op.flag !== void 0) existing.definition.flag = flagGateOf(op.flag, `Page "${op.ref}"`);
 		return {
 			...empty(),
 			updated: 1,
@@ -92,7 +97,8 @@ var upsertPage = (space, env, op) => {
 			label: op.label ?? op.ref,
 			type: "page",
 			items: [],
-			styleSelectors: { base: "" }
+			styleSelectors: { base: "" },
+			...op.flag ? { flag: flagGateOf(op.flag, `Page "${op.ref}"`) } : {}
 		}
 	};
 	space.schema.flat[id] = page;

package/dist/modules/mcp/tools/operations/schema/settings/patchSettings.d.ts

@@ -4,6 +4,7 @@ import { Env } from '../../../../types';
 export declare const patchSettingsOp: 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";

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

@@ -1,5 +1,6 @@
 import { settingsUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
+import { NOTIFICATIONS_FIELDS, splitNotificationsCss, withNotificationsCss } from "@plitzi/sdk-authoring";
 import { z } from "zod";
 import { channelProblems } from "@plitzi/sdk-shared/realtime";
 //#region src/modules/mcp/tools/operations/schema/settings/patchSettings.ts
@@ -21,9 +22,11 @@ var channel = z.object({
 	publish: z.enum(["clients", "server"]).optional(),
 	presence: z.boolean().optional()
 });
+var notifications = z.record(z.string(), z.string().nullable());
 var patchSettingsOp = z.object({
 	type: z.literal("patchSettings"),
 	customCss: z.string().optional().describe("Raw global CSS for the whole space (keyframes, @font-face, resets)"),
+	notifications: notifications.optional().describe(`The toasts' look: ${NOTIFICATIONS_FIELDS.join(", ")} — CSS values; null removes one`),
 	keepState: z.boolean().optional().describe("Keep runtime state (setState keys) across reloads"),
 	stateStorage: z.enum(["localStorage", "sessionStorage"]).optional(),
 	transientState: z.array(z.string()).optional().describe("Top-level state keys never kept"),
@@ -44,7 +47,7 @@ var patchSettingsOp = z.object({
 	sessionGate: z.enum(["optimistic", "strict"]).optional().describe("Render from the stored session and confirm behind it (default), or wait for the confirmation"),
 	sessionRevalidateSeconds: z.number().optional(),
 	channels: z.record(z.string(), channel.nullable()).optional().describe("Realtime channels by topic pattern (`board:{id}`); null removes one. See the guide")
-}).describe("Merge space-level settings — global CSS, kept state, auth, realtime channels. Only the fields sent change. customCss is for site-wide CSS, never to style one element (attach a definition for that).");
+}).describe("Merge space-level settings — global CSS, notifications, kept state, auth, realtime channels. Only the fields sent change. customCss is for site-wide CSS, never to style one element (attach a definition for that).");
 /** The space's channels with the patch merged in, pattern by pattern — `null` takes one out. */
 var mergeChannels = (current, patch) => {
 	const merged = {
@@ -53,8 +56,23 @@ var mergeChannels = (current, patch) => {
 	};
 	return Object.fromEntries(Object.entries(merged).filter((entry) => entry[1] !== null));
 };
+/**
+* The space's `customCss` with the patch's own CSS and notifications in it. Both live in that one string — the
+* notifications as the rule authoring writes for them — so each is read out of it, changed apart, and written back
+* together: a new `customCss` keeps the notifications, and new notifications keep the space's CSS.
+*/
+var patchCustomCss = (current, customCss, patch) => {
+	const was = splitNotificationsCss(current);
+	const sent = customCss === void 0 ? void 0 : splitNotificationsCss(customCss);
+	const merged = {
+		...was.notifications,
+		...sent?.notifications,
+		...patch
+	};
+	return withNotificationsCss(sent?.customCss ?? was.customCss, Object.fromEntries(Object.entries(merged).filter((entry) => typeof entry[1] === "string")));
+};
 var patchSettings = (space, env, op) => {
-	const { type, channels, ...patch } = op;
+	const { type, channels, customCss, notifications: notificationsPatch, ...patch } = op;
 	for (const [pattern, declaration] of Object.entries(channels ?? {})) {
 		const [problem] = declaration === null ? [] : channelProblems(pattern, declaration);
 		if (problem) return fail(`channels["${pattern}"]`, `Channel "${pattern}": ${problem}.`, "Fix the pattern or declaration and send it again");
@@ -62,6 +80,14 @@ var patchSettings = (space, env, op) => {
 	const next = { ...space.schema.settings };
 	for (const [key, value] of Object.entries(patch)) next[key] = value;
 	if (channels) next.channels = mergeChannels(space.schema.settings.channels, channels);
+	if (customCss !== void 0 || notificationsPatch) {
+		const current = space.schema.settings.customCss;
+		try {
+			next.customCss = patchCustomCss(typeof current === "string" ? current : "", customCss, notificationsPatch);
+		} catch (error) {
+			return fail("notifications", error instanceof Error ? error.message : String(error), "Write one CSS value per field — a colour, a length or a token like var(--card)");
+		}
+	}
 	space.schema.settings = next;
 	return {
 		...empty(),

package/dist/modules/mcp/tools/operations/schema/shared.d.ts

@@ -18,6 +18,8 @@ export interface ElementInput {
     };
     initialState?: InitialStateInput;
     runtime?: ElementRuntime;
+    flag?: string;
+    anchor?: string;
     children?: ElementInput[];
 }
 export declare const styleRefs: z.ZodObject<{
@@ -33,6 +35,10 @@ export declare const elementRuntime: z.ZodEnum<{
     client: "client";
     shared: "shared";
 }>;
+/** The feature flag an element exists under — `'name'` while on, `'!name'` while off. Not a visibility. */
+export declare const elementFlag: z.ZodString;
+/** The element's `id` in the DOM, so `/page#anchor` lands on it — the one pattern every writer holds it to. */
+export declare const elementAnchor: z.ZodString;
 export declare const initialStateInput: z.ZodObject<{
     styleVariant: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>>;
     visibility: z.ZodOptional<z.ZodBoolean>;
@@ -56,6 +62,8 @@ export declare const elementShape: {
         client: "client";
         shared: "shared";
     }>>;
+    flag: z.ZodOptional<z.ZodString>;
+    anchor: z.ZodOptional<z.ZodString>;
 };
 export declare const elementInput: z.ZodType<ElementInput>;
 export declare const position: z.ZodEnum<{

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

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { FLAG_GATE_PATTERN } from "@plitzi/sdk-shared/flags";
+import { ANCHOR_PATTERN } from "@plitzi/sdk-shared/schema/anchor";
 //#region src/modules/mcp/tools/operations/schema/shared.ts
 var combinator = z.enum(["and", "or"]);
 var operator = z.enum([
@@ -64,6 +66,10 @@ var elementRuntime = z.enum([
 	"client",
 	"shared"
 ]).describe("Where this element renders: \"shared\" (default, both), \"client\" (browser only), or \"server\" (SSR only). An apiContainer MUST be \"server\" to read through a connector — a client one calls its own `query` URL instead.");
+/** The feature flag an element exists under — `'name'` while on, `'!name'` while off. Not a visibility. */
+var elementFlag = z.string().regex(FLAG_GATE_PATTERN).describe("Feature flag: `name` renders only while on, `!name` only while off");
+/** The element's `id` in the DOM, so `/page#anchor` lands on it — the one pattern every writer holds it to. */
+var elementAnchor = z.string().regex(ANCHOR_PATTERN).describe("Its DOM id, for `/page#anchor` and the `hash` of a link; one per page");
 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")
@@ -76,7 +82,9 @@ var elementShape = {
 	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)"),
-	runtime: elementRuntime.optional()
+	runtime: elementRuntime.optional(),
+	flag: elementFlag.optional(),
+	anchor: elementAnchor.optional()
 };
 var elementInput = z.lazy(() => z.object({
 	...elementShape,
@@ -133,4 +141,4 @@ var interactionNode = z.object({
 	preview: z.record(z.string(), z.unknown()).optional()
 });
 //#endregion
-export { bindingCategory, bindingInput, elementInput, elementRuntime, elementShape, initialStateInput, interactionNode, interactionNodeType, position, ruleGroup, scalar, styleRefs, styleVariantInput };
+export { bindingCategory, bindingInput, elementAnchor, elementFlag, elementInput, elementRuntime, elementShape, initialStateInput, interactionNode, interactionNodeType, position, ruleGroup, scalar, styleRefs, styleVariantInput };

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

@@ -2,6 +2,7 @@ import { computeVersion } from "../../../helpers/computeVersion.js";
 import { descendantCount, elementById, getLayoutElements, getPageElements, nameOf, orderedChildren, pageFoldersOf, pageRefOfElement, pagesUsingLayout, slugRouteParams, spaceIndex, strOr } from "../../../helpers/space.js";
 import { bindingsToAI, flowsFromInteractions } from "../../../helpers/interactions.js";
 import { definitionToAI, globalStylesForType, idStyleToAI } from "../style/translator.js";
+import { flagSpecOf, splitNotificationsCss } from "@plitzi/sdk-authoring";
 import { descendants } from "@plitzi/sdk-schema/helpers/elementTree";
 //#region src/modules/mcp/tools/operations/schema/translator.ts
 var splitClasses = (value) => value ? value.split(/\s+/).filter(Boolean) : [];
@@ -182,6 +183,7 @@ var elementDetailToAI = (schema, el, style) => {
 		childRefs: children.length > 0 ? children.map((child) => child.id) : void 0
 	};
 	if (el.definition.runtime) detail.runtime = el.definition.runtime;
+	if (el.definition.flag) detail.flag = flagSpecOf(el.definition.flag);
 	const initialState = initialStateToAI(el);
 	if (initialState) detail.initialState = initialState;
 	const bindings = bindingsToAI(el.definition.bindings);
@@ -223,6 +225,12 @@ var schemaVariablesToAI = (schema, includeSubValues = true) => {
 var settingsToAI = (schema) => {
 	const result = {};
 	for (const [key, value] of Object.entries(schema.settings)) result[key] = value;
+	if (typeof schema.settings.customCss === "string") {
+		const { notifications, customCss } = splitNotificationsCss(schema.settings.customCss);
+		if (customCss) result.customCss = customCss;
+		else delete result.customCss;
+		if (Object.keys(notifications).length > 0) result.notifications = notifications;
+	}
 	return result;
 };
 //#endregion