@plitzi/sdk-mcp 0.38.6 → 0.38.8

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

@@ -2,7 +2,6 @@ import { componentView, findComponentByRef } from "../../../helpers/components.j
 import { findElementByRef, findFolderByRef, findPageByRef, findRootByRef, folderAncestorIds, getLayoutElements, getPageElements, pageFoldersOf, resolveRef, routeParamNames } from "../../../helpers/space.js";
 import { observedDataSources, observedInteractionActions } from "../../../catalogs/observed.js";
 import { buildTypeRegistry } from "../../../catalogs/registry.js";
-import { elementTypeNames } from "../../../catalogs/index.js";
 import { MAX_OPS } from "../../operations/index.js";
 import { batchDeclaredElements, batchDeclaredFolders, batchDeclaredPages, batchDeclaredVariants, batchDeclaredVars } from "./batch.js";
 import { checkObservedName, warnOnce } from "./context.js";
@@ -13,6 +12,7 @@ import { checkRef } from "./refs.js";
 import { checkElementInput, checkRawMarkup, checkTypeProps, checkVariantApplication } from "./elements.js";
 import { checkInteractionNode } from "./interactions.js";
 import { treeOf } from "@plitzi/sdk-schema/helpers/components";
+import { closest } from "@plitzi/sdk-authoring";
 import { isValidElementId } from "@plitzi/sdk-schema/helpers/elementId";
 //#region src/modules/mcp/tools/shared/validator/index.ts
 var STYLE_CATEGORIES = [
@@ -49,7 +49,6 @@ var buildValidationCtx = (space, ops, mode = "space") => {
 		errors: [],
 		warnings: [],
 		warned: /* @__PURE__ */ new Set(),
-		knownTypes: /* @__PURE__ */ new Set([...Object.keys(registry.types), ...elementTypeNames]),
 		typeProps: new Map(Object.entries(registry.types).map(([type, info]) => [type, new Set(Object.keys(info.props))])),
 		typeMeta: buildTypeMeta(space.catalog),
 		elementType: (ref) => treeOf(space.schema, ref)?.flat[ref]?.definition.type,
@@ -76,6 +75,28 @@ var validateOperations = (space, ops, mode = "space") => {
 		if (input.type === PROVIDER_TYPE) checkProviderElement(space, ctx, input.ref, input.runtime, input.props, batchConnectors, base);
 		(input.children ?? []).forEach((child, i) => checkProviders(child, `${base}.children[${i}]`));
 	};
+	const classes = /* @__PURE__ */ new Set([...Object.values(space.style.platform).flatMap((breakpoint) => Object.entries(breakpoint).filter(([, item]) => item.type === "class").map(([name]) => name)), ...ops.flatMap((op) => op.type === "upsertDefinition" ? [op.ref] : op.type === "upsertDefinitions" ? Object.keys(op.definitions) : [])]);
+	const checkClasses = (style, path) => {
+		const worn = [...(style?.base ?? []).map((name) => ({
+			name,
+			at: `${path}.base`
+		})), ...Object.entries(style?.slots ?? {}).flatMap(([slot, names]) => names.map((name) => ({
+			name,
+			at: `${path}.slots.${slot}`
+		})))];
+		for (const { name, at } of worn) if (!classes.has(name)) {
+			const nearest = closest(name, classes);
+			ctx.errors.push({
+				path: at,
+				message: `"${name}" is not a class of the space${nearest ? ` — did you mean "${nearest}"?` : ""}`,
+				hint: "Name one of plitzi://definitions/{env}, or declare it earlier in the batch with upsertDefinition"
+			});
+		}
+	};
+	const checkTreeClasses = (input, path) => {
+		checkClasses(input.style, `${path}.style`);
+		(input.children ?? []).forEach((child, i) => checkTreeClasses(child, `${path}.children[${i}]`));
+	};
 	if (ops.length > 1e3) ctx.errors.push({
 		path: "operations",
 		message: `Batch has ${ops.length} operations (max ${MAX_OPS})`,
@@ -103,11 +124,13 @@ var validateOperations = (space, ops, mode = "space") => {
 		switch (op.type) {
 			case "upsertElement":
 				checkElementInput(op.element, `${base}.element`, ctx, /* @__PURE__ */ new Set());
+				checkTreeClasses(op.element, `${base}.element`);
 				checkVariantApplication(op.element.initialState, `${base}.element.initialState`, ctx);
 				checkProviders(op.element, `${base}.element`);
 				break;
 			case "patchElement": {
 				checkRef(op.ref, `${base}.ref`, ctx);
+				checkClasses(op.style, `${base}.style`);
 				const page = findRootByRef(scoped, component ? component.rootId : op.pageRef);
 				const target = page ? resolveRef(scoped, page, op.ref) : void 0;
 				if (op.props && target && target.id !== page?.id) {

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

@@ -223,10 +223,22 @@ export interface AIAncestorCondition extends DisplayModeCss {
     states?: Record<string, DisplayModeCss>;
     variants?: Record<string, DisplayModeCss>;
 }
+/** A pseudo-element of a selector (`before`, `after`, `placeholder`…): its rules per breakpoint, and in its states. */
+export interface AIPseudo extends DisplayModeCss {
+    states?: Record<string, DisplayModeCss>;
+}
+/** A variant: its rules per breakpoint, its states and its pseudo-elements. */
+export interface AIVariant extends AIPseudo {
+    pseudos?: Record<string, AIPseudo>;
+}
+/** The rules under a condition of the page (`motion-reduce`, `container (max-width: 30rem)`), as a variant has them. */
+export type AICondition = AIVariant;
 export interface AIDefinitionSlot extends DisplayModeCss {
     states?: Record<string, DisplayModeCss>;
-    variants?: Record<string, DisplayModeCss>;
+    variants?: Record<string, AIVariant>;
     ancestors?: Record<string, AIAncestorCondition>;
+    pseudos?: Record<string, AIPseudo>;
+    conditions?: Record<string, AICondition>;
 }
 export interface AIDefinition extends AIDefinitionSlot {
     ref: string;

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

@@ -44,9 +44,9 @@ export type ScreenshotInput = {
      */
     views?: CaptureView[];
 };
-/** How plitzi_screenshot reaches the headless-browser service. The consumer injects an implementation (an HTTP
- *  client to the dedicated browser pod); absent → the tool is not registered. A capture that fails (pod down)
- *  returns `ok:false` rather than throwing, so the tool can degrade to the HTML preview. */
+/** How a look reaches the headless-browser service. The consumer injects an implementation (an HTTP
+ *  client to the dedicated browser pod); absent, or a capture that fails (pod down) and answers `ok:false` rather than
+ *  throwing, and the look answers the HTML instead. */
 export type ScreenshotClient = {
     capture: (input: ScreenshotInput) => Promise<ScreenshotResult>;
 };

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

@@ -44,6 +44,8 @@ export interface WriteResponse {
         updated: number;
         deleted: number;
     };
+    /** What the batch did, read off the space before and after it: a line per change, nothing left unsaid. */
+    effects?: string[];
     changed: ChangedResource[];
     elements?: WriteElement[];
     warnings?: string[];
@@ -83,10 +85,6 @@ export interface ApplyInput {
     expectedResourceVersions?: Record<string, string>;
     operations: Operation[];
 }
-export interface ValidateInput {
-    environment?: string;
-    operations: Operation[];
-}
 export interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];

package/dist/options.d.ts

@@ -58,11 +58,10 @@ export type McpOptions = {
         url: string;
         secret?: string;
     };
-    /** Dedicated headless-browser service for plitzi_screenshot (off unless set). `serviceUrl` is the browser
-     *  service that turns a URL into PNG(s); `renderBaseUrl` is the SSR base the browser navigates to (a page path
-     *  + the one-shot `__pt` token are appended). When absent, plitzi_screenshot is not registered and only the HTML
-     *  plitzi_preview is available; when the service is unreachable at call time the tool degrades to returning the
-     *  HTML preview with a warning. */
+    /** Dedicated headless-browser service a look renders an image or an accessibility outline through (off unless
+     *  set). `serviceUrl` is the browser service that turns a URL into PNG(s); `renderBaseUrl` is the SSR base the
+     *  browser navigates to (a page path + the one-shot `__pt` token are appended). When absent — or unreachable at call
+     *  time — a look answers the HTML instead, with a warning. */
     screenshot?: {
         serviceUrl: string;
         renderBaseUrl: string;

package/dist/preview/createPreview.js

@@ -1,7 +1,6 @@
 import { computeVersion } from "../modules/mcp/helpers/computeVersion.js";
-import { cloneSpace, findPageByRef, getPageElements } from "../modules/mcp/helpers/space.js";
-import { validateOperations } from "../modules/mcp/tools/shared/validator/index.js";
-import { applyOperations } from "../modules/mcp/tools/apply/dispatch.js";
+import { findPageByRef, getPageElements } from "../modules/mcp/helpers/space.js";
+import { draftBatch } from "../modules/mcp/tools/shared/draftBatch.js";
 import { randomUUID } from "node:crypto";
 import { buildBody } from "@plitzi/sdk-server/ssr";
 //#region src/preview/createPreview.ts
@@ -41,30 +40,22 @@ var createPreview = async (body, config, renderFn, pluginManager, caches) => {
 	};
 	let draftOffline = offlineData;
 	if (body.operations && body.operations.length > 0) {
-		const draft = cloneSpace({
+		const batch = draftBatch({
 			schema: offlineData.schema,
 			style: offlineData.style,
 			connectors: [],
 			actions: []
-		});
-		const validation = validateOperations(draft, body.operations);
-		if (!validation.valid) return {
+		}, env, body.operations);
+		if (!batch.ok) return {
 			ok: false,
 			error: "INVALID_OPERATIONS",
-			message: "The operations did not validate.",
-			errors: validation.errors
-		};
-		const outcome = applyOperations(draft, env, body.operations);
-		if (outcome.errors.length > 0) return {
-			ok: false,
-			error: "APPLY_FAILED",
-			message: "The operations could not be applied.",
-			errors: outcome.errors
+			message: "The operations were refused, as plitzi_apply would refuse them.",
+			errors: batch.errors
 		};
 		draftOffline = {
 			...offlineData,
-			schema: draft.schema,
-			style: draft.style
+			schema: batch.draft.schema,
+			style: batch.draft.style
 		};
 	}
 	const pagePath = resolvePagePath(draftOffline.schema, body.pageRef);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-mcp",
-  "version": "0.38.6",
+  "version": "0.38.8",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -30,12 +30,12 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.32.0",
-    "@plitzi/plitzi-sdk": "0.38.6",
-    "@plitzi/sdk-authoring": "0.38.6",
-    "@plitzi/sdk-schema": "0.38.6",
-    "@plitzi/sdk-server": "0.38.6",
-    "@plitzi/sdk-shared": "0.38.6",
-    "@plitzi/sdk-style": "0.38.6",
+    "@plitzi/plitzi-sdk": "0.38.8",
+    "@plitzi/sdk-authoring": "0.38.8",
+    "@plitzi/sdk-schema": "0.38.8",
+    "@plitzi/sdk-server": "0.38.8",
+    "@plitzi/sdk-shared": "0.38.8",
+    "@plitzi/sdk-style": "0.38.8",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "zod": "^4.6.5"

package/skills/plitzi-render/SKILL.md

@@ -30,125 +30,6 @@ Read the MCP resource **`plitzi://render/guide`** once per conversation. It is t
 every operation, the element types and their props, the styling system, worked examples. `plitzi://render/types`
 lists every element type with its description. Don't reconstruct the schema from memory — read the guide.
 
-## The shape of a good call
-
-Everything the widget needs travels in ONE call, as `operations`. Three ops carry almost every widget:
-
-- **`upsertDefinitions`** — declare ALL the CSS classes at once, one class per *look* (not per property).
-- **`upsertElement`** — build the whole tree in a single op, nesting with `children` under `pageRef: "render"`.
-- **`repeatElement`** — the moment two siblings differ only in data, write the row ONCE as a template with
-  `{{item.field}}` placeholders and pass `items`. Rows come out numbered (`tile-1`, `tile-2`…). A list inside each
-  row is the same op: give a template node `repeat: { items: "{{item.<field>}}", template: … }`.
-
-```json
-{
-  "operations": [
-    {
-      "type": "upsertDefinitions",
-      "definitions": {
-        "panel": {
-          "desktop": {
-            "display": "flex",
-            "flex-direction": "column",
-            "gap": "12px",
-            "padding": "16px",
-            "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))"
-          }
-        },
-        "row": {
-          "desktop": { "display": "flex", "flex-wrap": "wrap", "gap": "12px" },
-          "mobile": { "flex-direction": "column" }
-        },
-        "tile": {
-          "desktop": {
-            "flex": "1 1 0%",
-            "min-width": "160px",
-            "padding": "12px",
-            "border-radius": "10px",
-            "border": "1px solid var(--color-border-primary, light-dark(#e2e8f0, #333a48))",
-            "background-color": "var(--color-background-secondary, light-dark(#ffffff, #1f2430))"
-          }
-        },
-        "tile-title": { "desktop": { "margin": "0", "font-size": "15px" } },
-        "tile-price": { "desktop": { "margin": "0", "font-size": "13px", "opacity": "0.75" } }
-      }
-    },
-    {
-      "type": "upsertElement",
-      "pageRef": "render",
-      "element": {
-        "ref": "panel",
-        "type": "container",
-        "style": { "base": ["panel"] },
-        "children": [{ "ref": "title", "type": "heading", "subType": "h3", "props": { "content": "Plans" } }]
-      }
-    },
-    {
-      "type": "repeatElement",
-      "pageRef": "render",
-      "parentRef": "panel",
-      "ref": "plans",
-      "style": { "base": ["row"] },
-      "template": {
-        "ref": "tile",
-        "type": "container",
-        "style": { "base": ["tile"] },
-        "children": [
-          {
-            "ref": "name",
-            "type": "heading",
-            "subType": "h4",
-            "props": { "content": "{{item.name}}" },
-            "style": { "base": ["tile-title"] }
-          },
-          {
-            "ref": "price",
-            "type": "paragraph",
-            "props": { "content": "{{item.price}}" },
-            "style": { "base": ["tile-price"] }
-          }
-        ]
-      },
-      "items": [
-        { "name": "Starter", "price": "$0 / month" },
-        { "name": "Team", "price": "$19 / month" },
-        { "name": "Business", "price": "$49 / month" }
-      ]
-    }
-  ]
-}
-```
-
-## The six things that decide whether it looks good
-
-1. **Width is free, height is scarce.** The widget renders in a side panel. A plain container stacks its children
-   vertically — that is the tall, half-empty default to avoid. Put peers (metrics, plans, options, image + text) in
-   a wrapping row (`display:flex` + `flex-wrap:wrap`, children `flex:1 1 0%` with a `min-width` as the wrap
-   threshold) or a grid with `grid-template-columns: repeat(auto-fit, minmax(160px, 1fr))`. Stack only what reads in
-   order: heading over paragraph, forms, steps, prose.
-2. **The host may be in dark mode.** Never hardcode a light palette. Take colours from the host variables with a
-   `light-dark()` fallback, and always set `color` wherever you set `background-color`.
-3. **You are not styling from zero.** The SDK's per-type CSS imposes **no minimum size**: a rail, a divider, a dot
-   or a narrow cell is exactly as small as you make it, and no `"min-width": "0"` escape hatch is needed. The flip
-   side is that an element with no content and no size takes no space at all — give a spacer its own `height`.
-   What does land on your elements is the BROWSER's own defaults: `heading` and `paragraph` keep their UA margins
-   (zero them, space with the parent's `gap`), `list` a 40px `padding-left`, `button` its native chrome. Borders
-   start at `0 solid`, so `border-color` alone paints nothing — give `border-width` too.
-4. **Draw with inline SVG, on a budget.** A logo, a sparkline, a badge or a decorative shape goes in a `blockHtml`
-   element whose `props.content` is an `<svg>` — keep a `viewBox` with `width`/`height` `100%` so the element's
-   class sizes it, and `fill`/`stroke` `currentColor` so it follows the theme. A handful of paths, drawn once and
-   reused. Never a `data:` URI, and never a full illustration or a photo-real scene: that costs more than the rest
-   of the widget, so use an `https` image, a flat colour or a CSS gradient instead. Markup only — `<script>` and
-   inline `on*` handlers are rejected.
-5. **Only use image URLs you have seen work.** Everything the widget loads from outside is fetched for it by the
-   render server, so redirects, hotlink rules and missing CORS headers are already handled and there is nothing to
-   configure — but nothing can guess a URL. Write a direct file URL, never a page about the picture, a search
-   result, or a pattern assembled from memory: one that 404s leaves a grey box in the middle of a finished layout.
-   With no URL you trust, draw that block instead (a gradient, a flat colour, an inline `<svg>`).
-6. **Write CSS plainly.** Kebab-case properties, shorthands welcome (`padding: 8px 16px`, `border: 1px solid red`,
-   `font: bold 16px/1.5 Arial`) — they are expanded and stored as longhands, so a breakpoint or state can override
-   one property on its own.
-
 ## Iterating on a widget you already rendered
 
 Every render answers with a **`renderId`**. To change that widget, do NOT rebuild it: call again with
@@ -170,71 +51,6 @@ storage, a conversation resumed elsewhere), send the whole batch again without `
 issues. The `path` names the operation, so fix that one and call again — you never lose the rest of the batch. An
 unknown prop comes back as a warning naming the right one, so probing is safe.
 
-## Making it interactive
-
-Widgets are not only static: `upsertInteractionFlow` attaches a flow to an element — a `trigger` node first
-(`onClick`), then the steps that run after it, in order.
-
-**To show and hide, use `toggleState`.** Every element registers `setState` and `toggleState` as `callback`
-actions, and `elementId` names the element they act on — the flow's own element by default, or another element's
-ref to act on that one. `toggleState` with `category: "state"` and `key: "visibility"` is the show/hide toggle;
-there is no separate `toggleVisibility` action. The element starts hidden with `initialState: { "visibility":
-false }` on the element itself.
-
-```json
-{
-  "operations": [
-    {
-      "type": "upsertElement",
-      "pageRef": "render",
-      "element": {
-        "ref": "card",
-        "type": "container",
-        "children": [
-          { "ref": "card-head", "type": "button", "props": { "content": "Details" } },
-          {
-            "ref": "card-body",
-            "type": "container",
-            "initialState": { "visibility": false },
-            "children": [
-              { "ref": "card-text", "type": "paragraph", "props": { "content": "The hidden detail." } }
-            ]
-          }
-        ]
-      }
-    },
-    {
-      "type": "upsertInteractionFlow",
-      "pageRef": "render",
-      "ref": "card-head",
-      "nodes": [
-        { "title": "On click", "nodeType": "trigger", "action": "onClick" },
-        {
-          "title": "Toggle body",
-          "nodeType": "callback",
-          "action": "toggleState",
-          "elementId": "card-body",
-          "params": { "category": "state", "key": "visibility" }
-        }
-      ]
-    }
-  ]
-}
-```
-
-Expand/collapse is **one step on one trigger** — never two `setState` branches under opposite `when` conditions,
-which read the state as it was when the flow started and so are always one click behind. For several flows on one
-element (an `onClick` and an `onMouseEnter`, or two independent clicks), call `upsertInteractionFlow` again with
-the same `ref` and **omit `flowId`**; passing an existing `flowId` replaces that flow instead.
-
-Two things routinely go wrong. Events **bubble**, so a clickable element inside another clickable element runs
-BOTH flows — put the trigger on one of them (the render warns you and names the pair). And a `globalCallback`
-(`addNotification`, `navigate`, app-level `setState`) is provided by a module, not by an element, so **omit
-`elementId`** on those; a step with the wrong node type resolves against nothing and silently does nothing.
-
-For data-driven widgets, an `apiContainer` fetches at runtime and `upsertBinding` wires the result into elements —
-see "Data & interactivity" in `plitzi://render/guide`, which is also the full reference for everything above.
-
 ## After it renders
 
 The widget is shown to the user; you get a compact summary. Don't re-describe what they can already see — a short
@@ -244,3 +60,11 @@ When the widget has flows, the summary includes an `interactions` line per flow
 (`"card-head onClick → toggleState card-body[visibility]"`). Read it: it is what confirms the flow landed on the
 element you meant. But it reports the **wiring**, not a click that was performed — this tool authors the widget,
 it does not drive it. So tell the user what you connected; never claim you verified the behaviour at runtime.
+
+## What to read
+
+| The task | Read |
+| --- | --- |
+| Writing the call: the tree, the classes, the order of operations | [the shape of a good call](reference/good-call.md) |
+| Making it look good: spacing, type, colour, images | [the six things](reference/looks.md) |
+| Toggles, expanders, tabs — a widget that reacts | [making it interactive](reference/interactive.md) |

package/skills/plitzi-render/reference/good-call.md

@@ -0,0 +1,88 @@
+# The shape of a good call
+
+Everything the widget needs travels in ONE call, as `operations`. Three ops carry almost every widget:
+
+- **`upsertDefinitions`** — declare ALL the CSS classes at once, one class per *look* (not per property).
+- **`upsertElement`** — build the whole tree in a single op, nesting with `children` under `pageRef: "render"`.
+- **`repeatElement`** — the moment two siblings differ only in data, write the row ONCE as a template with
+  `{{item.field}}` placeholders and pass `items`. Rows come out numbered (`tile-1`, `tile-2`…). A list inside each
+  row is the same op: give a template node `repeat: { items: "{{item.<field>}}", template: … }`.
+
+```json
+{
+  "operations": [
+    {
+      "type": "upsertDefinitions",
+      "definitions": {
+        "panel": {
+          "desktop": {
+            "display": "flex",
+            "flex-direction": "column",
+            "gap": "12px",
+            "padding": "16px",
+            "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))"
+          }
+        },
+        "row": {
+          "desktop": { "display": "flex", "flex-wrap": "wrap", "gap": "12px" },
+          "mobile": { "flex-direction": "column" }
+        },
+        "tile": {
+          "desktop": {
+            "flex": "1 1 0%",
+            "min-width": "160px",
+            "padding": "12px",
+            "border-radius": "10px",
+            "border": "1px solid var(--color-border-primary, light-dark(#e2e8f0, #333a48))",
+            "background-color": "var(--color-background-secondary, light-dark(#ffffff, #1f2430))"
+          }
+        },
+        "tile-title": { "desktop": { "margin": "0", "font-size": "15px" } },
+        "tile-price": { "desktop": { "margin": "0", "font-size": "13px", "opacity": "0.75" } }
+      }
+    },
+    {
+      "type": "upsertElement",
+      "pageRef": "render",
+      "element": {
+        "ref": "panel",
+        "type": "container",
+        "style": { "base": ["panel"] },
+        "children": [{ "ref": "title", "type": "heading", "subType": "h3", "props": { "content": "Plans" } }]
+      }
+    },
+    {
+      "type": "repeatElement",
+      "pageRef": "render",
+      "parentRef": "panel",
+      "ref": "plans",
+      "style": { "base": ["row"] },
+      "template": {
+        "ref": "tile",
+        "type": "container",
+        "style": { "base": ["tile"] },
+        "children": [
+          {
+            "ref": "name",
+            "type": "heading",
+            "subType": "h4",
+            "props": { "content": "{{item.name}}" },
+            "style": { "base": ["tile-title"] }
+          },
+          {
+            "ref": "price",
+            "type": "paragraph",
+            "props": { "content": "{{item.price}}" },
+            "style": { "base": ["tile-price"] }
+          }
+        ]
+      },
+      "items": [
+        { "name": "Starter", "price": "$0 / month" },
+        { "name": "Team", "price": "$19 / month" },
+        { "name": "Business", "price": "$49 / month" }
+      ]
+    }
+  ]
+}
+```

package/skills/plitzi-render/reference/interactive.md

@@ -0,0 +1,64 @@
+# Making it interactive
+
+Widgets are not only static: `upsertInteractionFlow` attaches a flow to an element — a `trigger` node first
+(`onClick`), then the steps that run after it, in order.
+
+**To show and hide, use `toggleState`.** Every element registers `setState` and `toggleState` as `callback`
+actions, and `elementId` names the element they act on — the flow's own element by default, or another element's
+ref to act on that one. `toggleState` with `category: "state"` and `key: "visibility"` is the show/hide toggle;
+there is no separate `toggleVisibility` action. The element starts hidden with `initialState: { "visibility":
+false }` on the element itself.
+
+```json
+{
+  "operations": [
+    {
+      "type": "upsertElement",
+      "pageRef": "render",
+      "element": {
+        "ref": "card",
+        "type": "container",
+        "children": [
+          { "ref": "card-head", "type": "button", "props": { "content": "Details" } },
+          {
+            "ref": "card-body",
+            "type": "container",
+            "initialState": { "visibility": false },
+            "children": [
+              { "ref": "card-text", "type": "paragraph", "props": { "content": "The hidden detail." } }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "upsertInteractionFlow",
+      "pageRef": "render",
+      "ref": "card-head",
+      "nodes": [
+        { "title": "On click", "nodeType": "trigger", "action": "onClick" },
+        {
+          "title": "Toggle body",
+          "nodeType": "callback",
+          "action": "toggleState",
+          "elementId": "card-body",
+          "params": { "category": "state", "key": "visibility" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Expand/collapse is **one step on one trigger** — never two `setState` branches under opposite `when` conditions,
+which read the state as it was when the flow started and so are always one click behind. For several flows on one
+element (an `onClick` and an `onMouseEnter`, or two independent clicks), call `upsertInteractionFlow` again with
+the same `ref` and **omit `flowId`**; passing an existing `flowId` replaces that flow instead.
+
+Two things routinely go wrong. Events **bubble**, so a clickable element inside another clickable element runs
+BOTH flows — put the trigger on one of them (the render warns you and names the pair). And a `globalCallback`
+(`addNotification`, `navigate`, app-level `setState`) is provided by a module, not by an element, so **omit
+`elementId`** on those; a step with the wrong node type resolves against nothing and silently does nothing.
+
+For data-driven widgets, an `apiContainer` fetches at runtime and `upsertBinding` wires the result into elements —
+see "Data & interactivity" in `plitzi://render/guide`, which is also the full reference for everything above.

package/skills/plitzi-render/reference/looks.md

@@ -0,0 +1,29 @@
+# The six things that decide whether it looks good
+
+1. **Width is free, height is scarce.** The widget renders in a side panel. A plain container stacks its children
+   vertically — that is the tall, half-empty default to avoid. Put peers (metrics, plans, options, image + text) in
+   a wrapping row (`display:flex` + `flex-wrap:wrap`, children `flex:1 1 0%` with a `min-width` as the wrap
+   threshold) or a grid with `grid-template-columns: repeat(auto-fit, minmax(160px, 1fr))`. Stack only what reads in
+   order: heading over paragraph, forms, steps, prose.
+2. **The host may be in dark mode.** Never hardcode a light palette. Take colours from the host variables with a
+   `light-dark()` fallback, and always set `color` wherever you set `background-color`.
+3. **You are not styling from zero.** The SDK's per-type CSS imposes **no minimum size**: a rail, a divider, a dot
+   or a narrow cell is exactly as small as you make it, and no `"min-width": "0"` escape hatch is needed. The flip
+   side is that an element with no content and no size takes no space at all — give a spacer its own `height`.
+   What does land on your elements is the BROWSER's own defaults: `heading` and `paragraph` keep their UA margins
+   (zero them, space with the parent's `gap`), `list` a 40px `padding-left`, `button` its native chrome. Borders
+   start at `0 solid`, so `border-color` alone paints nothing — give `border-width` too.
+4. **Draw with inline SVG, on a budget.** A logo, a sparkline, a badge or a decorative shape goes in a `blockHtml`
+   element whose `props.content` is an `<svg>` — keep a `viewBox` with `width`/`height` `100%` so the element's
+   class sizes it, and `fill`/`stroke` `currentColor` so it follows the theme. A handful of paths, drawn once and
+   reused. Never a `data:` URI, and never a full illustration or a photo-real scene: that costs more than the rest
+   of the widget, so use an `https` image, a flat colour or a CSS gradient instead. Markup only — `<script>` and
+   inline `on*` handlers are rejected.
+5. **Only use image URLs you have seen work.** Everything the widget loads from outside is fetched for it by the
+   render server, so redirects, hotlink rules and missing CORS headers are already handled and there is nothing to
+   configure — but nothing can guess a URL. Write a direct file URL, never a page about the picture, a search
+   result, or a pattern assembled from memory: one that 404s leaves a grey box in the middle of a finished layout.
+   With no URL you trust, draw that block instead (a gradient, a flat colour, an inline `<svg>`).
+6. **Write CSS plainly.** Kebab-case properties, shorthands welcome (`padding: 8px 16px`, `border: 1px solid red`,
+   `font: bold 16px/1.5 Arial`) — they are expanded and stored as longhands, so a breakpoint or state can override
+   one property on its own.