@plitzi/sdk-server 0.32.15 → 0.32.17

package/dist/modules/mcp/catalogs/cssCatalog/layout.js

@@ -0,0 +1,98 @@
+import { FLEX_DIRECTIONS, FLEX_WRAPS, LENGTH_RE, NUMBER_RE, QUOTE_RE, splitOn, splitPair, splitTokens } from "./helpers.js";
+//#region src/modules/mcp/catalogs/cssCatalog/layout.ts
+var expandOverflow = (value, out) => {
+	const [x, y = x] = splitTokens(value);
+	out["overflow-x"] = x;
+	out["overflow-y"] = y;
+};
+var FLEX_KEYWORDS = /* @__PURE__ */ new Map([
+	["none", [
+		"0",
+		"0",
+		"auto"
+	]],
+	["auto", [
+		"1",
+		"1",
+		"auto"
+	]],
+	["initial", [
+		"0",
+		"1",
+		"auto"
+	]]
+]);
+var writeFlex = (out, grow, shrink, basis) => {
+	out["flex-grow"] = grow;
+	out["flex-shrink"] = shrink;
+	out["flex-basis"] = basis;
+};
+var expandFlex = (value, out) => {
+	const tokens = splitTokens(value);
+	if (tokens.length === 1) {
+		const [only] = tokens;
+		const keyword = FLEX_KEYWORDS.get(only);
+		if (keyword) writeFlex(out, ...keyword);
+		else if (NUMBER_RE.test(only)) writeFlex(out, only, "1", "0%");
+		else writeFlex(out, "1", "1", only);
+		return;
+	}
+	const [grow, second, third] = tokens;
+	if (!NUMBER_RE.test(grow)) return;
+	if (tokens.length === 2) if (NUMBER_RE.test(second)) writeFlex(out, grow, second, "0%");
+	else writeFlex(out, grow, "1", second);
+	else writeFlex(out, grow, second, third);
+};
+var expandFlexFlow = (value, out) => {
+	for (const token of splitTokens(value)) if (FLEX_DIRECTIONS.has(token)) out["flex-direction"] = token;
+	else if (FLEX_WRAPS.has(token)) out["flex-wrap"] = token;
+};
+var expandPlacePair = (prefix, value, out) => {
+	const [align, justify = align] = splitTokens(value);
+	const prop = prefix.slice(6);
+	out[`align-${prop}`] = align;
+	out[`justify-${prop}`] = justify;
+};
+var expandGridLine = (key, value, out) => {
+	const axis = key.slice(5);
+	const [start, end = "auto"] = splitOn(value, "/");
+	out[`grid-${axis}-start`] = start;
+	out[`grid-${axis}-end`] = end;
+};
+var expandGridArea = (value, out) => {
+	const [rowStart, colStart = rowStart, rowEnd = colStart, colEnd = rowEnd] = splitOn(value, "/");
+	out["grid-row-start"] = rowStart;
+	out["grid-column-start"] = colStart;
+	out["grid-row-end"] = rowEnd;
+	out["grid-column-end"] = colEnd;
+};
+var expandColumns = (value, out) => {
+	const tokens = splitTokens(value);
+	if (tokens.length === 1) {
+		const [only] = tokens;
+		if (NUMBER_RE.test(only)) out["column-count"] = only;
+		else out["column-width"] = only;
+	} else if (tokens.length >= 2) {
+		const [first, second] = tokens;
+		const [width, count] = NUMBER_RE.test(first) ? [second, first] : [first, second];
+		out["column-width"] = width;
+		out["column-count"] = count;
+	}
+};
+var isTrackList = (tokens) => tokens.some((token) => token === "none" || token === "auto" || token === "min-content" || token === "max-content" || token.startsWith("[") || token.startsWith("minmax(") || token.startsWith("repeat(") || token.startsWith("fit-content(") || LENGTH_RE.test(token) || /^-?[\d.]+fr$/.test(token));
+var expandGridTemplate = (value, out) => {
+	const [first, second] = splitPair(value, "/");
+	const rowTokens = splitTokens(first);
+	const areas = rowTokens.filter((token) => QUOTE_RE.test(token));
+	const sizes = rowTokens.filter((token) => !QUOTE_RE.test(token));
+	if (second !== void 0) {
+		if (second !== "") out["grid-template-columns"] = second;
+	} else if (areas.length === 0) {
+		if (isTrackList(rowTokens)) out["grid-template-columns"] = first;
+		return;
+	}
+	if (areas.length > 0) out["grid-template-areas"] = areas.join(" ");
+	if (sizes.length > 0) out["grid-template-rows"] = sizes.join(" ");
+};
+//#endregion
+export { expandColumns, expandFlex, expandFlexFlow, expandGridArea, expandGridLine, expandGridTemplate, expandOverflow, expandPlacePair };

package/dist/modules/mcp/catalogs/cssCatalog/visual.js

@@ -0,0 +1,144 @@
+import { ANIMATION_DIRECTIONS, ANIMATION_FILL_MODES, ANIMATION_PLAY_STATES, FONT_STYLE_KEYWORDS, FONT_VARIANT_KEYWORDS, FONT_WEIGHT_KEYWORDS, LENGTH_RE, LIST_STYLE_POSITIONS, LIST_STYLE_TYPES, NUMBER_RE, TEXT_DECORATION_LINES, TEXT_DECORATION_STYLES, TIME_RE, isTimingFunction, splitOn, splitPair, splitTokens } from "./helpers.js";
+import { classifyBorderTokens } from "./border.js";
+//#region src/modules/mcp/catalogs/cssCatalog/visual.ts
+var expandLayers = (value, out, expandLayer) => {
+	const layers = splitOn(value, ",");
+	if (layers.length === 1) {
+		expandLayer(layers[0], out);
+		return;
+	}
+	const perLayer = layers.map((layer) => {
+		const layerOut = {};
+		expandLayer(layer, layerOut);
+		return layerOut;
+	});
+	const keys = new Set(perLayer.flatMap((layer) => Object.keys(layer)));
+	for (const key of keys) out[key] = perLayer.map((layer) => String(layer[key] ?? "initial")).join(", ");
+};
+var expandOutline = (value, out) => {
+	for (const [kind, token] of Object.entries(classifyBorderTokens(value))) out[`outline-${kind}`] = token;
+};
+var expandListStyle = (value, out) => {
+	for (const token of splitTokens(value)) if (token.startsWith("url(")) out["list-style-image"] = token;
+	else if (LIST_STYLE_POSITIONS.has(token)) out["list-style-position"] = token;
+	else if (LIST_STYLE_TYPES.has(token)) out["list-style-type"] = token;
+};
+var expandTextDecoration = (value, out) => {
+	for (const token of splitTokens(value)) if (TEXT_DECORATION_LINES.has(token)) out["text-decoration-line"] = token;
+	else if (TEXT_DECORATION_STYLES.has(token)) out["text-decoration-style"] = token;
+	else out["text-decoration-color"] = token;
+};
+var expandTransitionLayer = (layer, out) => {
+	let foundDuration = false;
+	for (const token of splitTokens(layer)) if (isTimingFunction(token)) out["transition-timing-function"] = token;
+	else if (TIME_RE.test(token) || NUMBER_RE.test(token)) if (foundDuration) out["transition-delay"] = token;
+	else {
+		out["transition-duration"] = token;
+		foundDuration = true;
+	}
+	else if (!out["transition-property"]) out["transition-property"] = token;
+};
+var expandTransition = (value, out) => expandLayers(value, out, expandTransitionLayer);
+var expandAnimationLayer = (layer, out) => {
+	let foundDuration = false;
+	for (const token of splitTokens(layer)) if (isTimingFunction(token)) out["animation-timing-function"] = token;
+	else if (TIME_RE.test(token)) if (foundDuration) out["animation-delay"] = token;
+	else {
+		out["animation-duration"] = token;
+		foundDuration = true;
+	}
+	else if (token === "infinite" || NUMBER_RE.test(token)) out["animation-iteration-count"] = token;
+	else if (ANIMATION_DIRECTIONS.has(token) && !out["animation-direction"]) out["animation-direction"] = token;
+	else if (ANIMATION_FILL_MODES.has(token) && !out["animation-fill-mode"]) out["animation-fill-mode"] = token;
+	else if (ANIMATION_PLAY_STATES.has(token) && !out["animation-play-state"]) out["animation-play-state"] = token;
+	else if (!out["animation-name"]) out["animation-name"] = token;
+};
+var expandAnimation = (value, out) => expandLayers(value, out, expandAnimationLayer);
+var BACKGROUND_REPEATS = /* @__PURE__ */ new Set([
+	"repeat",
+	"no-repeat",
+	"repeat-x",
+	"repeat-y",
+	"space",
+	"round"
+]);
+var BACKGROUND_ATTACHMENTS = /* @__PURE__ */ new Set([
+	"scroll",
+	"fixed",
+	"local"
+]);
+var BACKGROUND_BOXES = /* @__PURE__ */ new Set([
+	"border-box",
+	"padding-box",
+	"content-box"
+]);
+var BACKGROUND_POSITIONS = /* @__PURE__ */ new Set([
+	"center",
+	"top",
+	"bottom",
+	"left",
+	"right"
+]);
+var isImage = (token) => token.startsWith("url(") || token.includes("-gradient(");
+var isPosition = (token) => BACKGROUND_POSITIONS.has(token) || LENGTH_RE.test(token);
+var isSize = (token) => token === "cover" || token === "contain" || token === "auto" || LENGTH_RE.test(token);
+var expandBackgroundLayer = (layer, out) => {
+	const [beforeSlash, afterSlash] = splitPair(layer, "/");
+	const tokens = splitTokens(beforeSlash);
+	if (afterSlash !== void 0) {
+		let positionStart = tokens.length;
+		while (positionStart > 0 && isPosition(tokens[positionStart - 1])) positionStart -= 1;
+		const position = tokens.splice(positionStart, tokens.length - positionStart);
+		if (position.length > 0) out["background-position"] = position.join(" ");
+		const afterTokens = splitTokens(afterSlash);
+		let sizeEnd = 0;
+		while (sizeEnd < afterTokens.length && isSize(afterTokens[sizeEnd])) sizeEnd += 1;
+		if (sizeEnd > 0) out["background-size"] = afterTokens.slice(0, sizeEnd).join(" ");
+		tokens.push(...afterTokens.slice(sizeEnd));
+	}
+	const positions = [];
+	for (const token of tokens) if (isImage(token)) out["background-image"] = token;
+	else if (BACKGROUND_REPEATS.has(token)) out["background-repeat"] = token;
+	else if (token === "cover" || token === "contain") out["background-size"] = token;
+	else if (BACKGROUND_ATTACHMENTS.has(token)) out["background-attachment"] = token;
+	else if (BACKGROUND_BOXES.has(token)) if (out["background-origin"]) out["background-clip"] = token;
+	else out["background-origin"] = token;
+	else if (isPosition(token)) positions.push(token);
+	else if (!out["background-color"]) out["background-color"] = token;
+	if (positions.length > 0) out["background-position"] = positions.join(" ");
+};
+var expandBackground = (value, out) => expandLayers(value, out, expandBackgroundLayer);
+var expandFont = (value, out) => {
+	const [beforeSlash, afterSlash] = splitPair(value, "/");
+	const tokens = splitTokens(beforeSlash);
+	if (afterSlash !== void 0) {
+		const [lineHeight, ...family] = splitTokens(afterSlash);
+		out["line-height"] = lineHeight;
+		if (family.length > 0) out["font-family"] = family.join(" ");
+	}
+	const family = [];
+	let foundSize = false;
+	for (const token of tokens) {
+		if (foundSize) {
+			family.push(token);
+			continue;
+		}
+		if (token === "normal") {
+			const slot = [
+				"font-style",
+				"font-variant",
+				"font-weight"
+			].find((prop) => !out[prop]);
+			if (slot) out[slot] = token;
+		} else if (FONT_STYLE_KEYWORDS.has(token) && !out["font-style"]) out["font-style"] = token;
+		else if (FONT_VARIANT_KEYWORDS.has(token) && !out["font-variant"]) out["font-variant"] = token;
+		else if (FONT_WEIGHT_KEYWORDS.has(token) && !out["font-weight"]) out["font-weight"] = token;
+		else if (LENGTH_RE.test(token)) {
+			out["font-size"] = token;
+			foundSize = true;
+		}
+	}
+	if (family.length > 0) out["font-family"] = family.join(" ");
+};
+//#endregion
+export { expandAnimation, expandBackground, expandFont, expandListStyle, expandOutline, expandTextDecoration, expandTransition };

package/dist/modules/mcp/catalogs/registry.js

@@ -1,5 +1,5 @@
 import { BUILTIN_COMPONENTS } from "./builtinComponents.js";
-import { cssProperties } from "./cssCatalog.js";
+import { cssProperties } from "./cssCatalog/index.js";
 //#region src/modules/mcp/catalogs/registry.ts
 var enrichType = (typeName, info, catalog) => {
 	const entry = catalog?.[typeName];

package/dist/modules/mcp/helpers/guide.js

@@ -1,5 +1,5 @@
 //#region src/modules/mcp/helpers/guide.ts
-var serverInstructions = "Plitzi AI server: read-then-write editing of a Plitzi space. Reads follow a filesystem model — list cheap, read one item in detail on demand; never fetch a whole tree you do not need. Workflow: (1) read plitzi://primer/{env} once — it bundles the guide, types, css-properties and page/definition/variable summaries in a single call; (2) plitzi_search with include:\"detail\" to jump to elements — each hit then carries its uri, stateVersion AND full style/resolvedStyle, so an edit needs no per-element read; open a page skeleton or element only when you need its tree/detail (the skeleton already lists the style classes of each node, and plitzi_read fetches many uris at once); (3) plitzi_apply with dryRun to preview a batch; (4) plitzi_apply to persist, passing expectedResourceVersions to guard against concurrent edits — apply and search both hand back the versions you need for the next edit. Use patchElement / patchDefinition to change only some props / CSS (the upsert variants replace them all). An element read (and search include:\"detail\") inlines the CSS of the definitions it attaches under resolvedStyle, so you rarely need a separate definition read. Refs accept a semantic idRef ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) or the raw id — the idRef is ALSO the runtime wiring key, so a provider source is `<type>_<idRef>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is kebab-case and ATOMIC (shorthands like border/padding expanded; compound ones like flex/background/font rejected — use longhands); style vars are var(--name), schema vars are {{name}}. READERS — do not confuse them: MCP *resources* are the browsable catalog (list them, or open one by URI); plitzi_search FINDS refs by label/type/attribute; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. Elements also carry applied style variants + visibility (initialState), data bindings and interaction flows: edit them with patchElement (initialState), upsertBinding/patchBinding/deleteBinding, and upsertInteractionFlow/patchInteractionNode/deleteInteraction. An element read shows all three plus availableVariants (which variant each of its classes offers). Separately, to SHOW the user a small self-contained widget (offline, no space or backend) instead of editing the space — a card, hero, pricing table, a visual answer — use plitzi_render; read plitzi://render/guide for it.";
+var serverInstructions = "Plitzi AI server: read-then-write editing of a Plitzi space. Reads follow a filesystem model — list cheap, read one item in detail on demand; never fetch a whole tree you do not need. Workflow: (1) read plitzi://primer/{env} once — it bundles the guide, types, css-properties and page/definition/variable summaries in a single call; (2) plitzi_search with include:\"detail\" to jump to elements — each hit then carries its uri, stateVersion AND full style/resolvedStyle, so an edit needs no per-element read; open a page skeleton or element only when you need its tree/detail (the skeleton already lists the style classes of each node, and plitzi_read fetches many uris at once); (3) plitzi_apply with dryRun to preview a batch; (4) plitzi_apply to persist, passing expectedResourceVersions to guard against concurrent edits — apply and search both hand back the versions you need for the next edit. Use patchElement / patchDefinition to change only some props / CSS (the upsert variants replace them all). An element read (and search include:\"detail\") inlines the CSS of the definitions it attaches under resolvedStyle, so you rarely need a separate definition read. Refs accept a semantic idRef ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) or the raw id — the idRef is ALSO the runtime wiring key, so a provider source is `<type>_<idRef>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is plain kebab-case — write shorthands freely (`border: 1px solid red`, `padding: 8px 16px`, `font: bold 16px/1.5 Arial`), they are expanded to longhands for you and STORED that way, so read-back shows the longhands; style vars are var(--name), schema vars are {{name}}. READERS — do not confuse them: MCP *resources* are the browsable catalog (list them, or open one by URI); plitzi_search FINDS refs by label/type/attribute; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. Elements also carry applied style variants + visibility (initialState), data bindings and interaction flows: edit them with patchElement (initialState), upsertBinding/patchBinding/deleteBinding, and upsertInteractionFlow/patchInteractionNode/deleteInteraction. An element read shows all three plus availableVariants (which variant each of its classes offers). Separately, to SHOW the user a small self-contained widget (offline, no space or backend) instead of editing the space — a card, hero, pricing table, a visual answer — use plitzi_render; read plitzi://render/guide for it.";
 var guideQuickstart = `# Plitzi AI MCP — quickstart
 This is the condensed guide; read \`plitzi://guide\` for the full reference (every resource, op and example).
 
@@ -19,10 +19,12 @@ interactions target by it. A dot would split that path; an **underscore is fine*
 from the idRef (element types have none), so \`list_food_item\` reads unambiguously as type \`list\`, idRef \`food_item\`.
 
 **Styling:** CSS keys are **kebab-case** (\`background-color\`); \`var(--token)\` for style vars, \`{{name}}\` for schema
-vars. Shorthands \`border\`/\`padding\`/\`margin\`/\`gap\` are expanded for you. Write **atomically — no compound
-shorthands** (\`flex\`, \`background\`, \`font\`, \`transition\`, \`grid\` are rejected/warned): use their longhands, and
-express flex layout as \`display: flex\` + \`flex-direction\`/\`align-items\`/… Mind a type's \`defaultStyle\` (\`text\`
-is \`display: inline\`). Global styles (\`button {…}\`) and id styles (\`#id\`) have their own ops.
+vars. **Write plain CSS** — shorthands (\`border\`, \`padding\`, \`margin\`, \`gap\`, \`overflow\`, \`flex\`, \`background\`,
+\`font\`, \`transition\`, \`animation\`, \`grid\`, \`grid-row\`/\`grid-column\`, \`place-*\`, \`outline\`, \`columns\`,
+\`list-style\`, \`text-decoration\`) are expanded to their longhands for you, so \`border: 1px solid red\` is stored as
+\`border-top-color\`/\`border-top-width\`/\`border-top-style\`/… That is also how you read them back. Flex layout is
+still \`display: flex\` + \`flex-direction\`/\`align-items\`/…, not a \`flex\` value. Mind a type's \`defaultStyle\`
+(\`text\` is \`display: inline\`). Global styles (\`button {…}\`) and id styles (\`#id\`) have their own ops.
 
 **Data bindings** (\`upsertBinding\`, category attributes|style|initialState): connect a \`source\` to a \`to\` field.
 A source \`<type>_<idRef>\` is scoped to the provider's **DESCENDANTS only** — bind inside the provider's subtree
@@ -202,14 +204,22 @@ pointed at the old name is repointed with it, so the element stays wired. You do
 - A definition lives in the **style schema**; an element's \`style.base\` (element schema) is the link that applies
   it. Styling an element = upsertDefinition + upsertElement with that ref in \`style.base\`, in one batch.
 - CSS keys are **kebab-case** (\`background-color\`). camelCase is rejected — read \`plitzi://css-properties\`.
-- Common **shorthands are accepted** and expanded for you: \`border\`, \`border-{side}\`, \`border-radius\`,
-  \`padding\`, \`margin\`, \`inset\`, \`gap\` (they persist as their longhand keys).
-- **Write CSS atomically — no multi-value compound shorthands.** Plitzi stores each property on its own so a
-  breakpoint/state/variant can override just that one, so \`flex\`, \`background\`, \`font\`, \`transition\`,
-  \`animation\`, \`grid\`, \`place-*\`, \`outline\`, \`columns\` are **rejected** (or warned) — use their longhands
-  instead: \`background\` → \`background-color\`/\`background-image\`/…, \`font\` → \`font-size\`/\`font-weight\`/
-  \`line-height\`, \`flex: 1\` → \`flex-grow\`/\`flex-shrink\`/\`flex-basis\`. **Flex layout is not a \`flex\` value**: set
-  \`display: flex\` **plus** \`flex-direction\`, \`align-items\`, \`justify-content\` as separate properties.
+- **Write normal CSS — shorthands are accepted and expanded for you.** \`border\`, \`border-{side}\`,
+  \`border-width\`/\`-color\`/\`-style\`, \`border-radius\`, \`padding\`, \`margin\`, \`inset\`, \`gap\`, \`overflow\`,
+  \`flex\`, \`flex-flow\`, \`background\`, \`font\`, \`transition\`, \`animation\`, \`grid\`, \`grid-template\`,
+  \`grid-area\`, \`grid-row\`, \`grid-column\`, \`place-content\`, \`place-items\`, \`place-self\`, \`outline\`,
+  \`columns\`, \`list-style\`, \`text-decoration\` — the full list is in \`plitzi://css-properties\` under
+  \`shorthands\`. They **persist as longhand keys** (that is what a read gives back), so a breakpoint/state/variant
+  can still override one property at a time.
+  - \`border: 1px solid red\` → \`border-top-width: 1px\`, \`border-top-style: solid\`, \`border-top-color: red\`, …
+    for all four sides. A shorthand also RESETS what it omits, so \`border: none\` clears a width a previous
+    definition set.
+  - Comma-separated layers are kept per longhand: \`transition: opacity 200ms, transform 300ms\` →
+    \`transition-property: opacity, transform\` + \`transition-duration: 200ms, 300ms\`.
+  - In a **patch**, a shorthand replaces the longhands it controls (\`padding: 8px\` overwrites a previous
+    \`padding-left\`), and \`"border": null\` removes all twelve border longhands.
+- **Flex layout is not a \`flex\` value**: set \`display: flex\` **plus** \`flex-direction\`, \`align-items\`,
+  \`justify-content\` as separate properties.
 - CSS is grouped by breakpoint: \`desktop\`, \`tablet\`, \`mobile\`.
 - Reference a style variable in CSS as \`var(--name)\`; a schema variable in a prop as \`{{name}}\`.
 - \`element.style.base\` is a **list** of definition refs; other slots go under \`element.style.slots\`.

package/dist/modules/mcp/helpers/space.js

@@ -280,7 +280,7 @@ var pageRefOfElement = (schema, el) => {
 /** Total number of descendant elements under a subtree (excluding the root). */
 var descendantCount = (schema, rootId) => descendantIds(schema, rootId).length;
 var emptySpaceMessage = "Space data not available";
-var unauthorizedSpaceMessage = "This tool/resource needs a space, but no spaceId could be resolved from the Authorization token";
+var unauthorizedSpaceMessage = "This connection has no space attached (a guest or widgets-only grant, or a token that carries no space), so NOTHING in a space can be read or edited — every other space tool will fail the same way, do not retry them. Use plitzi_render instead: it builds a self-contained widget offline, with no space, backend or account (read plitzi://render/guide). To edit a real space, the user must reconnect the integration and grant access to one.";
 var generateObjectId = () => {
 	return `${Math.floor(Date.now() / 1e3).toString(16).padStart(8, "0")}${Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join("")}`;
 };

package/dist/modules/mcp/resources/core.js

@@ -1,4 +1,4 @@
-import { cssProperties } from "../catalogs/cssCatalog.js";
+import { cssProperties, cssShorthands } from "../catalogs/cssCatalog/index.js";
 import { buildTypeRegistry } from "../catalogs/registry.js";
 import "../helpers/uris.js";
 import { guideText } from "../helpers/guide.js";
@@ -9,7 +9,10 @@ import { envelope } from "./envelope.js";
 var readCoreResource = (space, uri) => {
 	if (uri === "plitzi://guide") return envelope(guideText);
 	if (uri === "plitzi://types") return envelope(buildTypeRegistry(space.schema, space.catalog));
-	if (uri === "plitzi://css-properties") return envelope(cssProperties);
+	if (uri === "plitzi://css-properties") return envelope({
+		properties: cssProperties,
+		shorthands: cssShorthands
+	});
 };
 //#endregion
 export { readCoreResource };

package/dist/modules/mcp/resources/primer.js

@@ -1,4 +1,4 @@
-import { cssProperties } from "../catalogs/cssCatalog.js";
+import { cssProperties, cssShorthands } from "../catalogs/cssCatalog/index.js";
 import { buildDataSourceCatalog, buildInteractionCatalog } from "../catalogs/observed.js";
 import { buildTypeRegistry } from "../catalogs/registry.js";
 import { guideQuickstart } from "../helpers/guide.js";
@@ -16,6 +16,7 @@ var readPrimerResource = (space, env, uri) => {
 		guide: guideQuickstart,
 		types: buildTypeRegistry(space.schema, space.catalog),
 		cssProperties,
+		cssShorthands,
 		pages: pageSummariesToAI(space.schema),
 		folders: foldersToAI(space.schema),
 		definitions: definitionRefs(space.style),

package/dist/modules/mcp/resources/register.js

@@ -1,4 +1,4 @@
-import { cssProperties } from "../catalogs/cssCatalog.js";
+import { cssProperties, cssShorthands } from "../catalogs/cssCatalog/index.js";
 import { guideText } from "../helpers/guide.js";
 import { resourceErrorMessage } from "./canonical.js";
 import { envelope, jsonContents } from "./envelope.js";
@@ -36,9 +36,12 @@ var registerResources = (server, getSpace, env, log) => {
 		text: guideText
 	}] })));
 	server.registerResource("CSS properties", "plitzi://css-properties", {
-		description: "Valid kebab-case CSS property keys",
+		description: "Valid kebab-case CSS property keys, plus the shorthands that are accepted and auto-expanded",
 		mimeType: "application/json"
-	}, () => emitStatic("plitzi://css-properties", () => jsonContents("plitzi://css-properties", envelope(cssProperties))));
+	}, () => emitStatic("plitzi://css-properties", () => jsonContents("plitzi://css-properties", envelope({
+		properties: cssProperties,
+		shorthands: cssShorthands
+	}))));
 	registerRenderResources(server, log);
 	const fixed = [
 		[

package/dist/modules/mcp/resources/renderGuide.js

@@ -68,7 +68,21 @@ Styling is separate from structure: declare a class, then attach it by ref.
 - CSS properties in **kebab-case** (\`background-color\`, \`font-size\`, \`border-radius\`), values as plain strings.
 - Attach to an element via \`style: { "base": ["card"] }\`. Stack classes: \`"base": ["card", "shadow"]\`.
 - One \`ref\` can name both an element and its class (as above) — they live in different namespaces.
-- Lay containers out with flexbox: \`{ "display": "flex", "flex-direction": "column", "gap": "12px" }\`.
+- Lay containers out with flexbox or grid — pick the direction on purpose, see **Fit the panel** below.
+- **You are not styling from zero.** Each type lands on the page with CSS you did not write, and it is the usual
+  reason a widget does not look like the definitions say. The SDK stylesheet resets almost nothing (\`box-sizing\`,
+  \`border: 0 solid\`, \`body\` margin), so anything you leave unset comes from one of two places:
+  - The per-type rule the SDK ships — the one that changes layouts is \`container\`, which carries
+    \`min-width: 50px; min-height: 50px\`. A rail, a divider, a dot, a spacer or a narrow cell will NOT go below
+    50px until you say \`"min-width": "0"\` (and/or \`"min-height": "0"\`) on it: a 2px timeline line renders 50px
+    wide otherwise. Any flex child that must be allowed to shrink needs it too.
+  - The BROWSER's own defaults for the rest: \`heading\` keeps its UA font-size and ~0.67em top/bottom margins,
+    \`paragraph\` ~1em margins, \`list\` a 40px \`padding-left\`, \`button\` its native chrome, \`image\` its intrinsic
+    size, \`link\` its own colour and underline. In a compact widget set these explicitly — usually
+    \`"margin-top": "0"\`, \`"margin-bottom": "0"\` — and space things with the parent's \`gap\` instead.
+  - Borders start at \`0 solid\`, so \`border-color\` alone paints nothing: give \`border-width\` (and the colour).
+  - The \`defaultStyle\` a type reports in the EDITING catalog (\`plitzi://types\`) is authoring metadata for the
+    builder — it does not paint here, so do not count on it in a widget.
 - **Mind the intrinsic display.** Some types start non-block: \`text\` is \`display: inline\`, so to stack or size it,
   wrap it in a \`container\` (or set \`display: block\`). \`heading\` and \`paragraph\` are already block.
 - **Use atomic longhands.** \`padding\`, \`margin\`, \`border\`, \`border-radius\` are fine (they expand cleanly), but
@@ -80,6 +94,62 @@ Styling is separate from structure: declare a class, then attach it by ref.
   \`{ "desktop": { "background-color": "#3b82f6" }, "states": { "hover": { "desktop": { "background-color": "#2563eb" } } } }\`
   (\`hover\`, \`active\`, \`focus\`).
 
+## Fit the panel — go wide, stay short
+
+The widget renders in a **side panel** (Claude Desktop, ChatGPT, the Plitzi builder), so it gets a usable width but
+very little height: everything past the first screenful costs the user a scroll. Height is the scarce resource —
+spend width instead.
+
+Plain containers are blocks, so doing nothing stacks children **vertically** and produces exactly the tall,
+half-empty widget to avoid. Choose the axis every time:
+
+- **Peers side by side** — metrics, plans, options, a comparison, an image next to its text: a row, wrapping when
+  it runs out of width, children sharing it (no fixed widths).
+  \`\`\`json
+  { "type": "upsertDefinition", "ref": "row", "desktop": { "display": "flex", "flex-direction": "row", "flex-wrap": "wrap", "gap": "12px", "align-items": "stretch" } }
+  { "type": "upsertDefinition", "ref": "col", "desktop": { "flex-grow": "1", "flex-basis": "0%", "min-width": "150px" } }
+  \`\`\`
+  \`flex-grow: 1\` + \`flex-basis: 0%\` splits the row evenly; \`min-width\` is the wrap threshold — under it the item
+  drops to the next line by itself, so a narrow panel degrades gracefully with no breakpoints.
+- **Many uniform items** — cards, tiles, a gallery: one grid line does it all.
+  \`\`\`json
+  { "type": "upsertDefinition", "ref": "grid", "desktop": { "display": "grid", "grid-template-columns": "repeat(auto-fit, minmax(160px, 1fr))", "gap": "12px" } }
+  \`\`\`
+- **Label + value pairs** stay on one line (\`display: flex\`, \`justify-content: space-between\`) instead of two.
+- **Vertical is right** for reading order: a heading over its paragraph, a form, a step list, long prose.
+- Force a stack on tiny screens with the \`mobile\` block: \`"mobile": { "flex-direction": "column" }\`.
+
+Keep it compact, and the numbers low: \`padding\` 12–16px (24+ only on a single hero card), \`gap\` 8–12px,
+\`font-size\` 13–15px for body and 16–20px for headings. Let the outer container **fill** the panel — no \`width\` on
+it — and reach for \`max-width\` only to stop one lone card from stretching across the whole panel.
+
+## Match the host theme — never hardcode a light palette
+
+The widget is embedded in the host's own UI (Claude Desktop, ChatGPT, the builder), and that UI **may be in dark
+mode**. A widget painted with fixed light colours is the most common way to ship something unusable: a white card
+in a dark chat glares, and — worse — text left at a dark default disappears against the host's dark background.
+
+The host publishes its palette as CSS variables on the page, so use them for every colour, with a
+\`light-dark(<light>, <dark>)\` fallback for hosts that send none:
+
+\`\`\`json
+{ "type": "upsertDefinition", "ref": "card", "desktop": {
+    "background-color": "var(--color-background-secondary, light-dark(#ffffff, #1f2430))",
+    "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))",
+    "border-width": "1px", "border-style": "solid",
+    "border-color": "var(--color-border-primary, light-dark(#e2e8f0, #333a48))"
+} }
+\`\`\`
+
+- Surfaces: \`--color-background-primary\` (the page), \`--color-background-secondary\` / \`--color-background-tertiary\`
+  (cards, raised areas). Text: \`--color-text-primary\`, \`--color-text-secondary\`, \`--color-text-tertiary\` (muted).
+  Borders: \`--color-border-primary\` / \`--color-border-secondary\`. Status pairs: \`--color-background-danger\` |
+  \`success\` | \`warning\` | \`info\` with the matching \`--color-text-…\`. Also \`--font-sans\`, \`--border-radius-md\` /
+  \`lg\` / \`full\`, \`--shadow-sm\` / \`md\`.
+- **Set \`color\` wherever you set \`background-color\`** — the pair is what stays legible, either one alone is a
+  gamble. Same rule for a brand accent: a CTA on your own blue must state its own text colour (\`#ffffff\`).
+- Prefer a border to a drop shadow for separation: shadows all but vanish on a dark surface.
+
 ## Element types (type → what to set)
 
 | type | renders | set |
@@ -103,21 +173,31 @@ that is not here (lists, tabs, dialogs, forms, icons…).
 \`image\`/\`video\` \`src\` accepts any \`https\` URL, or a \`data:\`/\`blob:\` URI for a fully self-contained graphic
 (e.g. an inline SVG icon or a base64 image) — both render with no extra setup.
 
-## Full worked example — a pricing card
+## Full worked example — two plans side by side
+
+The cards sit in a wrapping row and split it evenly, so the widget uses the panel's width and stays short; on a
+narrow panel \`min-width\` drops the second card under the first on its own.
 
 \`\`\`json
 {
   "operations": [
-    { "type": "upsertDefinition", "ref": "card", "desktop": { "display": "flex", "flex-direction": "column", "gap": "8px", "padding": "24px", "background-color": "#ffffff", "border-radius": "12px", "width": "260px", "text-align": "center", "box-shadow": "0 4px 20px rgba(0,0,0,0.08)" } },
-    { "type": "upsertDefinition", "ref": "price", "desktop": { "font-size": "36px", "font-weight": "800", "color": "#3b82f6" } },
-    { "type": "upsertDefinition", "ref": "cta", "desktop": { "background-color": "#3b82f6", "color": "#ffffff", "padding": "12px 20px", "border-radius": "8px", "font-weight": "600" }, "states": { "hover": { "desktop": { "background-color": "#2563eb" } } } },
+    { "type": "upsertDefinition", "ref": "plans", "desktop": { "display": "flex", "flex-direction": "row", "flex-wrap": "wrap", "gap": "12px", "align-items": "stretch" } },
+    { "type": "upsertDefinition", "ref": "card", "desktop": { "display": "flex", "flex-direction": "column", "gap": "6px", "flex-grow": "1", "flex-basis": "0%", "min-width": "150px", "padding": "16px", "background-color": "var(--color-background-secondary, light-dark(#ffffff, #1f2430))", "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))", "border-width": "1px", "border-style": "solid", "border-color": "var(--color-border-primary, light-dark(#e2e8f0, #333a48))", "border-radius": "var(--border-radius-lg, 12px)", "text-align": "center" } },
+    { "type": "upsertDefinition", "ref": "price", "desktop": { "font-size": "28px", "font-weight": "800", "color": "#3b82f6" } },
+    { "type": "upsertDefinition", "ref": "cta", "desktop": { "background-color": "#3b82f6", "color": "#ffffff", "padding": "10px 16px", "border-radius": "8px", "font-weight": "600" }, "states": { "hover": { "desktop": { "background-color": "#2563eb" } } } },
     { "type": "upsertElement", "pageRef": "render", "element": {
-        "ref": "card", "type": "container", "style": { "base": ["card"] },
+        "ref": "plans", "type": "container", "style": { "base": ["plans"] },
         "children": [
-          { "ref": "plan",   "type": "heading",   "subType": "h3", "props": { "content": "Pro" } },
-          { "ref": "amount", "type": "text",      "props": { "content": "$29/mo" }, "style": { "base": ["price"] } },
-          { "ref": "feat",   "type": "paragraph", "props": { "content": "Unlimited projects" } },
-          { "ref": "buy",    "type": "button",    "props": { "content": "Start free trial" }, "style": { "base": ["cta"] } }
+          { "ref": "free", "type": "container", "style": { "base": ["card"] }, "children": [
+            { "ref": "free-plan",   "type": "heading", "subType": "h3", "props": { "content": "Starter" } },
+            { "ref": "free-amount", "type": "text",    "props": { "content": "$0" }, "style": { "base": ["price"] } },
+            { "ref": "free-buy",    "type": "button",  "props": { "content": "Start free" }, "style": { "base": ["cta"] } }
+          ] },
+          { "ref": "pro", "type": "container", "style": { "base": ["card"] }, "children": [
+            { "ref": "pro-plan",   "type": "heading", "subType": "h3", "props": { "content": "Pro" } },
+            { "ref": "pro-amount", "type": "text",    "props": { "content": "$29/mo" }, "style": { "base": ["price"] } },
+            { "ref": "pro-buy",    "type": "button",  "props": { "content": "Start free trial" }, "style": { "base": ["cta"] } }
+          ] }
         ]
     } }
   ]

package/dist/modules/mcp/server.js

@@ -43,7 +43,7 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.32.15"
+		version: "0.32.17"
 	}, { instructions: serverInstructions });
 	registerResources(server, getSpace, MCP_ENV, log);
 	registerApps(server);

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

@@ -16,13 +16,14 @@ var upsertInteractionFlow = (space, env, op) => {
 	const found = resolveElement(space, env, op.pageRef, op.ref);
 	if ("error" in found) return found.error;
 	const ownerRef = ensureIdRef(space, found.el);
-	const { flowId, record } = materializeFlow((op.flowId && !op.nodes[0].id ? [{
+	const nodes = (op.flowId && !op.nodes[0].id ? [{
 		...op.nodes[0],
 		id: op.flowId
 	}, ...op.nodes.slice(1)] : op.nodes).map((node) => node.elementId === void 0 || node.nodeType === "utility" ? node : {
 		...node,
 		elementId: resolveTargetRef(space, node.elementId)
-	}), ownerRef);
+	});
+	const { flowId, record } = materializeFlow(nodes, ownerRef);
 	const interactions = found.el.definition.interactions ?? {};
 	const targetFlow = op.flowId ?? flowId;
 	let replaced = false;

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/style/shared.ts
-var cssMap = z.record(z.string(), z.union([z.string(), z.number()])).describe("kebab-case CSS props; use var(--name) for tokens and {{name}} for schema vars");
+var cssMap = z.record(z.string(), z.union([z.string(), z.number()])).describe("Plain kebab-case CSS. Shorthands are welcome — `border: 1px solid red`, `padding: 8px 16px`, `font: bold 16px/1.5 Arial`, `transition: opacity 200ms ease` — and are stored as their longhands so a breakpoint/state/variant can override each property on its own. Use var(--name) for style tokens and {{name}} for schema vars.");
 var displayModeCss = z.object({
 	desktop: cssMap.optional(),
 	tablet: cssMap.optional(),
@@ -14,7 +14,7 @@ var cssPatchMap = z.record(z.string(), z.union([
 	z.string(),
 	z.number(),
 	z.null()
-])).describe("kebab-case CSS props; a value of null removes the property, others are merged onto the existing CSS");
+])).describe("Plain kebab-case CSS merged onto the existing declarations; shorthands are accepted and expanded, so `padding: 8px` replaces all four sides. A value of null removes the property — null on a shorthand (`border: null`) removes every longhand it controls.");
 var displayModeCssPatch = z.object({
 	desktop: cssPatchMap.optional(),
 	tablet: cssPatchMap.optional(),

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

@@ -1,4 +1,4 @@
-import { expandShorthand } from "../../../catalogs/cssCatalog.js";
+import { expandShorthand, expandShorthandPatch } from "../../../catalogs/cssCatalog/index.js";
 import { defUri, defsUri, globalUri, globalsUri, idUri, idsUri, styleVarUri, styleVarsUri } from "../../../helpers/uris.js";
 import { fail } from "../../../helpers/opResult.js";
 import processSelector from "@plitzi/sdk-style/helpers/processSelector";
@@ -65,7 +65,7 @@ var writeStyleItem = (style, ref, base, slots, itemType, componentType) => {
 };
 var mergeCss = (base, patch) => {
 	const merged = { ...base };
-	for (const [key, value] of Object.entries(patch ?? {})) if (value === null) Reflect.deleteProperty(merged, key);
+	for (const [key, value] of Object.entries(expandShorthandPatch(patch ?? {}))) if (value === null) Reflect.deleteProperty(merged, key);
 	else merged[key] = value;
 	return Object.keys(merged).length > 0 ? merged : void 0;
 };

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

@@ -105,7 +105,7 @@ var toRenderResult = (res) => {
 var renderTool = defineTool({
 	name: "plitzi_render",
 	title: "Render widget",
-	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n2. STYLE — declare reusable classes with upsertDefinition { ref, desktop:{ …CSS props in kebab-case… } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid.\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nReturns a compact summary (the widget is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
+	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n2. STYLE — declare reusable classes with upsertDefinition { ref, desktop:{ …CSS props in kebab-case… } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Watch the SDK defaults: every container has min-width/min-height 50px (set them to \"0\" for rails, dividers, dots and any flex child that must shrink), and heading/paragraph keep the browser's own margins (zero them and space with the parent's gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nReturns a compact summary (the widget is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
 	inputShape: renderShape,
 	access: "read",
 	spaceless: true,

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

@@ -83,10 +83,7 @@ var collectTouched = (ops) => {
 			touched.globalStyles.add(op.componentType);
 			break;
 		case "upsertIdStyle":
-		case "patchIdStyle":
-			touched.idStyles.add(op.targetId);
-			break;
-		default: break;
+		case "patchIdStyle": touched.idStyles.add(op.targetId);
 	}
 	return touched;
 };