@plitzi/sdk-server 0.32.5 → 0.32.7

package/dist/src/modules/mcp/catalogs/paramSpec.d.ts

@@ -0,0 +1,42 @@
+export type BuiltinParamType = 'text' | 'textarea' | 'select' | 'boolean' | 'number' | 'scalar';
+export interface BuiltinParam {
+    type: BuiltinParamType;
+    description: string;
+    default?: string | number | boolean;
+    options?: string[];
+    when?: (params: Record<string, unknown>) => boolean;
+    required?: boolean;
+}
+export type ParamSpec = Record<string, BuiltinParam>;
+/** Keys the agent supplied that are not declared params — mistakes for a CLOSED (strict) param set, dropped on
+ *  apply. Callers decide whether a set is strict; an open set never reports unknown keys. */
+export declare const unknownParams: (params: Record<string, unknown>, spec: ParamSpec) => string[];
+/** Declared params the agent supplied that end up HIDDEN because their own `when` guard is false against the
+ *  effective params — they are silently ignored (e.g. a global setState `value` with no `type`, or an
+ *  addNotification `autoDismissTimeout` with autoDismiss:false). Evaluated against the effective params so a param
+ *  the default fills in (e.g. category:"attribute") does not false-report a value as hidden. */
+export declare const hiddenParams: (provided: Record<string, unknown>, effective: Record<string, unknown>, spec: ParamSpec) => string[];
+/** Declared params marked `required` that the agent did NOT supply, and whose `when` guard holds against the
+ *  effective params (so they are actually in play). Evaluated against the effective params so a required param
+ *  gated by a companion (e.g. setState `value`, shown only once `category` is set) is not reported when its guard
+ *  is not met. */
+export declare const missingRequiredParams: (provided: Record<string, unknown>, effective: Record<string, unknown>, spec: ParamSpec) => string[];
+/** A param the agent supplied whose VALUE does not match its declared type — a boolean given as the string "true",
+ *  a number given as a string, a `select` value outside its options, a null placeholder left behind. `expected` is
+ *  the declared type, `got` the JS typeof (or "null"), and `options` the allowed values for a `select`. */
+export interface InvalidParam {
+    key: string;
+    expected: BuiltinParamType;
+    got: string;
+    options?: string[];
+}
+/** Declared params the agent supplied whose value is the WRONG type for the catalog — the check that catches a
+ *  malformed node the unknown/missing/hidden checks miss (a boolean stored as a string, a select value not in its
+ *  options, a leftover `null`). Only params actually in play are checked: undefined values (the param is absent) and
+ *  params hidden by their own `when` guard against the effective params are skipped, so this never fires on a param
+ *  that is not really used. Callers gate this to CLOSED (strict) catalogs, whose types we own authoritatively. */
+export declare const invalidParams: (provided: Record<string, unknown>, effective: Record<string, unknown>, spec: ParamSpec) => InvalidParam[];
+/** Reconcile supplied params to a catalog schema: drop unknown keys when the set is CLOSED (strict), then fill the
+ *  builder's defaults for any declared param the agent omitted whose `when` guard holds. Mirrors what the builder
+ *  stores, so the persisted node round-trips cleanly. */
+export declare const reconcileParams: (params: Record<string, unknown>, spec: ParamSpec, strict: boolean) => Record<string, unknown>;

package/dist/src/modules/mcp/catalogs/registry.d.ts

@@ -0,0 +1,35 @@
+import { ComponentCatalog, Schema } from '@plitzi/sdk-shared';
+export interface TypePropInfo {
+    valueTypes: string[];
+    examples: unknown[];
+}
+/** Where a type's semantics came from: a Plitzi 'builtin' (curated), a 'plugin' (custom element, from the
+ *  getComponentCatalog adapter), or 'unknown' (observed in the schema but neither knows it — label only). */
+export type TypeSource = 'builtin' | 'plugin' | 'unknown';
+export interface TypeInfo {
+    count: number;
+    /** Human name of the type (e.g. "Api Container"). */
+    label?: string;
+    /** What the type is FOR — so an agent picks the right one. */
+    description?: string;
+    /** Grouping (provider, structure, media, form, advanced…). */
+    category?: string;
+    source: TypeSource;
+    subTypes: string[];
+    slots: string[];
+    props: Record<string, TypePropInfo>;
+    /** The type's intrinsic base CSS before any class is attached (e.g. `text` → `{ display: 'inline' }`). Style
+     *  against this starting point rather than assuming `display: block`. */
+    defaultStyle?: Record<string, string>;
+}
+export interface TypeRegistry {
+    note: string;
+    cssProperties: string[];
+    styleVariableCategories: string[];
+    templateSyntax: {
+        schemaVariable: string;
+        styleVariable: string;
+    };
+    types: Record<string, TypeInfo>;
+}
+export declare const buildTypeRegistry: (schema: Schema, catalog?: ComponentCatalog) => TypeRegistry;

package/dist/src/modules/mcp/handler.d.ts

@@ -1,9 +1,9 @@
 import { createMcpServer } from './server';
 import { PreviewClient, ScreenshotClient } from './types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
-import { SSRAdapters, SSRRequest } from '@plitzi/sdk-shared';
+import { SSRAdapters, SSRRequest, McpLogger } from '@plitzi/sdk-shared';
 import { IncomingMessage, ServerResponse } from 'node:http';
 export declare const readMcpBody: (req: IncomingMessage) => Promise<unknown>;
 export declare const serveMcp: (raw: IncomingMessage, res: ServerResponse, server: McpServer) => Promise<void>;
-export declare const handleMcp: (raw: IncomingMessage, res: ServerResponse, req: SSRRequest, adapters: SSRAdapters, preview?: PreviewClient, screenshot?: ScreenshotClient) => Promise<void>;
+export declare const handleMcp: (raw: IncomingMessage, res: ServerResponse, req: SSRRequest, adapters: SSRAdapters, preview?: PreviewClient, screenshot?: ScreenshotClient, logger?: McpLogger) => Promise<void>;
 export { createMcpServer };

package/dist/src/modules/mcp/helpers/agentPrompt.d.ts

@@ -0,0 +1,4 @@
+/** The MCP-owned guidance block a consumer concatenates into its system prompt. Covers what the MCP is
+ *  authoritative about: its editing model, tools, resources and interaction vocabulary. It intentionally does NOT
+ *  cover a consumer’s own tools (previews, design helpers) or product framing (modes, identity, security). */
+export declare const buildAgentGuide: () => string;

package/dist/src/modules/mcp/helpers/guide.d.ts

@@ -1,2 +1,3 @@
 export declare const serverInstructions: string;
-export declare const guideText = "# Plitzi AI MCP \u2014 usage guide\n\nA Plitzi space is **two separate schemas** you edit together:\n- **Element schema** \u2014 the tree of pages and elements (their type, label, props, and which style classes they use).\n- **Style schema** \u2014 reusable **definitions** (CSS classes), design tokens (variables), theme.\n\nThey are stored and persisted independently, but a single `plitzi_apply` batch may touch **both atomically**.\nTo style a specific element you do two things in one batch: write a **definition** (style schema) and **attach**\nit via the element's `style.base` (element schema). Example \u2014 \"rename button X to PEPE and make it red\":\n```json\n{ \"operations\": [\n  { \"type\": \"upsertDefinition\", \"ref\": \"btn-x\", \"desktop\": { \"color\": \"red\" } },\n  { \"type\": \"upsertElement\", \"pageRef\": \"home\",\n    \"element\": { \"ref\": \"X\", \"type\": \"button\", \"label\": \"PEPE\", \"style\": { \"base\": [\"btn-x\"] } } }\n] }\n```\n\nReads are cheap by design \u2014 treat them like a filesystem: **list** to navigate, **read one item** for detail.\nNever download a whole tree you do not need.\n\n## Resources (read)\n- `plitzi://primer/{env}` \u2014 **cold-start bundle**: guide + types + css-properties + page/definition/variable\n  **summaries** in one read. Fetch this first instead of the individual resources below. Summaries only \u2014 open a\n  page skeleton or element for its tree/detail.\n- `plitzi://guide` \u2014 this guide.\n- `plitzi://types` \u2014 element types **observed in this space** (ground truth): props, slots, subTypes.\n- `plitzi://css-properties` \u2014 valid kebab-case CSS property keys.\n- `plitzi://schema/{env}/pages` \u2014 page **summaries** (ref, label, elementCount, folder). No element trees.\n- `plitzi://folders/{env}` \u2014 page **folders** (the sidebar tree): ref, name, slug, parentId. `/{ref}` for one.\n- `plitzi://schema/{env}/pages/{ref}` \u2014 one page as a **skeleton tree**: each node is `ref/type/label` **plus the\n  style classes it attaches** (`base`, and `slots` for non-base slots) \u2014 names only, no CSS. So you can map every\n  element to its class in a single page read, without opening each element just to learn which class it uses.\n- `plitzi://schema/{env}/pages/{ref}/styles` \u2014 **every style the page uses in one read**: the class definitions its\n  elements attach (deduplicated, **with full CSS**) plus the global styles affecting any element type on the page.\n  Reach for this to recolor/restyle a whole page \u2014 it needs no shared class-name prefix and no per-element reads.\n- `plitzi://schema/{env}/elements/{ref}` \u2014 one element in **full detail** (props, style, parentRef, childRefs).\n  Its `resolvedStyle` inlines the **CSS of every definition** the element attaches (keyed by class ref), so you\n  can see and edit its style without a separate definition read. Its `globalStyles` lists the **global element\n  selectors** that also affect it (the CSS equivalent of `button { \u2026 }`, keyed by the type they target) \u2014 every\n  element of that type inherits them. Edit a global only through the global-style tools (never per element).\n- `plitzi://definitions/{env}` \u2014 the **names** of every style definition.\n- `plitzi://definitions/{env}/{ref}` \u2014 one definition's CSS.\n- `plitzi://global-styles/{env}` \u2014 element **types** that have a site-wide global style. `/{componentType}` for one.\n- `plitzi://style-variables/{env}` \u2014 design tokens by category. `/{category}` for one.\n- `plitzi://schema-variables/{env}` \u2014 space-level values referenced in props as `{{name}}`.\n\nThe style resources also answer under the `plitzi://schema/{env}/\u2026` root as aliases \u2014 `plitzi://schema/{env}/definitions/{ref}`, `plitzi://schema/{env}/style-variables/{category}`, `plitzi://schema/{env}/schema-variables` \u2014 but prefer the ready-made `uri` from search / a write response over hand-building either form.\n\nData resources return `{ stateVersion, data }`. Keep `stateVersion` for optimistic concurrency.\n\n## Navigating (files analogy)\nPages and containers are folders; elements are files. **Prefer `plitzi_search` (especially with `include: \"detail\"`)\nover reading elements one by one** \u2014 it jumps straight to elements by label/type/attribute and each hit already\ncarries the element's `uri`, `stateVersion`, `pageUri`, `parentRef` and tree `path`, so you can edit it (with\noptimistic concurrency) **without a follow-up read**. `include: \"detail\"` additionally inlines each hit's props/style\n**and** its `resolvedStyle` (the CSS behind its classes) \u2014 so a search-then-edit is the efficient path and a manual\nelement read is the exception. Search also matches **pages** by name/slug (returned under `pages`, each with its uri +\nstateVersion) and returns any **style definitions** whose name matches the query, with full CSS, under `definitions`.\nWhen you do hold several refs to open (e.g. from a skeleton), read them together with `plitzi_read` rather than one at a time.\n\n## Tools (write)\n- `plitzi_validate` \u2014 check a batch, returns teachable errors/warnings. Writes nothing.\n- `plitzi_apply` \u2014 validate \u2192 apply \u2192 persist atomically. Rejects the whole batch on any error or conflict. Pass\n  `dryRun: true` to apply in memory only and get the same result back (changed versions + full element detail)\n  without persisting \u2014 inspect it, then re-run without `dryRun` to commit.\n- `plitzi_search` \u2014 find elements (and pages/definitions) across the space.\n- `plitzi_read` \u2014 read many resource **uris in one batch** (pages, elements, definitions, variables). Pass the\n  ready-made uris from search / a write response; each result is `{ uri, stateVersion, data }` or a teachable error,\n  so one bad uri never fails the batch. Use it instead of N single reads whenever you already hold several refs.\n\nWrite tools return what **changed** (`{ uri, stateVersion }`) plus counts, and the **full detail of every element\nthey created or updated** \u2014 each with its own `uri` and `stateVersion` (`elements: [...]`) so a follow-up edit of\nthe same element needs **no intermediate read**. Other resources (pages, definitions, variables) still report only\nuri+stateVersion \u2014 re-read them if you need their new content. The operation shapes are in each tool's input\nschema (discriminated by `type`).\n\n## Addressing\nRefs are a semantic `aiRef` you choose (e.g. `\"hero.cta\"`) or the element's **raw id**. Both always resolve, so\nschemas predating aiRef keep working through ids. Creating an element stores its `ref` as the aiRef.\n\n## Styling (crosses both schemas)\n- A definition lives in the **style schema**; an element's `style.base` (element schema) is the link that applies\n  it. Styling an element = upsertDefinition + upsertElement with that ref in `style.base`, in one batch.\n- CSS keys are **kebab-case** (`background-color`). camelCase is rejected \u2014 read `plitzi://css-properties`.\n- Common **shorthands are accepted** and expanded for you: `border`, `border-{side}`, `border-radius`,\n  `padding`, `margin`, `inset`, `gap` (they persist as their longhand keys).\n- CSS is grouped by breakpoint: `desktop`, `tablet`, `mobile`.\n- Reference a style variable in CSS as `var(--name)`; a schema variable in a prop as `{{name}}`.\n- `element.style.base` is a list of definition refs; other slots go under `element.style.slots`.\n- **Two kinds of style live in the style schema \u2014 do not confuse them:**\n  - **Definitions** = reusable CSS **classes** (`upsertDefinition`/`patchDefinition`/`deleteDefinition`, keyed by a\n    class `ref`). Attach one to an element via `style.base` to style **that** element (and anything else that opts in).\n  - **Global styles** = the CSS equivalent of a bare element selector like `button { \u2026 }`\n    (`upsertGlobalStyle`/`patchGlobalStyle`/`deleteGlobalStyle`, keyed by `componentType`). They style **every**\n    element of that type at once. Use these for site-wide intent \u2014 e.g. \"all buttons rounded\":\n    `{ \"type\": \"upsertGlobalStyle\", \"componentType\": \"button\", \"desktop\": { \"border-radius\": \"9999px\" } }`.\n  - The two share one name space, so a class op refuses a name held by a global and vice-versa (guards against a\n    typo silently rewriting every element of a type). If refused, you targeted the wrong kind \u2014 switch tools or\n    rename. To style one element only, never reach for a global.\n\n## Pages & folders\nPages can be grouped into **folders** (the sidebar tree). A folder is `{ ref, name, slug, parentId? }`; its `ref`\n**is its id** (there is no separate aiRef), and that id is what a page and a nested folder reference.\n- Create/rename/move a folder with `upsertFolder` (the `ref` you pass on create becomes its id \u2014 pick a stable one\n  like `\"blog\"`). Nest it under another with `parentId` (a folder ref); `parentId: null` moves it back to the root.\n- Put a page in a folder with `upsertPage`'s `folder` (a folder ref). A page's `folder` is always either **empty\n  (root)** or an **existing folder id**: `folder: null` or `folder: \"\"` moves it to the root, and any other value\n  must resolve to a folder that already exists or is created earlier in the same batch \u2014 an unknown folder is\n  rejected, never stored.\n- `deleteFolder` removes a folder and **promotes its contents up one level** \u2014 its child folders and its pages move\n  to its parent (or the root). A folder cannot be nested under itself or one of its descendants.\n\n## Semantics\n- **props are fully replaced** on `upsertElement`: send every prop you want to keep. To change only some props,\n  use **`patchElement`** \u2014 it merges `props`/`style` onto the existing element (listed keys change, `null` unsets\n  a key, everything else is preserved) and never creates. Combined with `plitzi_search` (which returns the ref +\n  stateVersion), a targeted edit is two calls with no read.\n- **definition CSS is fully replaced** on `upsertDefinition`: send every property you want to keep. To change only\n  some declarations, use **`patchDefinition`** \u2014 it merges CSS per breakpoint/state/variant/slot onto the existing\n  definition (listed keys change, `null` removes a property, everything else is preserved) and never creates.\n  Example \u2014 recolor one definition without resending it: `{ \"type\": \"patchDefinition\", \"ref\": \"btn-x\",\n  \"desktop\": { \"background-color\": \"#111\" } }`.\n- **Atomic batches**: if any operation fails, `plitzi_apply` persists nothing.\n- **Optimistic concurrency**: pass `expectedResourceVersions` (URI \u2192 the stateVersion you read). If the live data\n  drifted, apply is rejected with a conflict; re-read the reported resources and retry.\n";
+export declare const guideQuickstart = "# Plitzi AI MCP \u2014 quickstart\nThis is the condensed guide; read `plitzi://guide` for the full reference (every resource, op and example).\n\nA space is **two schemas you edit together in one atomic `plitzi_apply` batch**: the **element schema** (tree of\npages/elements) and the **style schema** (definitions = CSS classes, tokens, theme). To style an element: write a\n**definition** and attach it via the element's `style.base` in the same batch.\n\n**Workflow:** (1) you already have this primer (guide + types + css + page/style summaries). (2) `plitzi_search`\nwith `include:\"detail\"` to find elements \u2014 each hit carries its `uri`, `stateVersion` and full style, so no\nper-element read. (3) `plitzi_apply` with `dryRun:true` to preview. (4) `plitzi_apply` to persist, passing\n`expectedResourceVersions` (uri \u2192 the stateVersion you read) for every resource you change \u2014 omitting it lets a\nconcurrent edit be lost. Use `patchElement`/`patchDefinition` to change only some props/CSS (upsert replaces all).\n\n**Refs & wiring:** a ref is the semantic `idRef` (letters, numbers, hyphens and underscores, **starting with a\nletter \u2014 no dots**) or the raw id. The idRef is the runtime wiring key: a provider's source is `<type>_<idRef>`, and\ninteractions target by it. A dot would split that path; an **underscore is fine** \u2014 the first `_` separates the type\nfrom the idRef (element types have none), so `list_food_item` reads unambiguously as type `list`, idRef `food_item`.\n\n**Styling:** CSS keys are **kebab-case** (`background-color`); `var(--token)` for style vars, `{{name}}` for schema\nvars. Shorthands `border`/`padding`/`margin`/`gap` are expanded for you. Write **atomically \u2014 no compound\nshorthands** (`flex`, `background`, `font`, `transition`, `grid` are rejected/warned): use their longhands, and\nexpress flex layout as `display: flex` + `flex-direction`/`align-items`/\u2026 Mind a type's `defaultStyle` (`text`\nis `display: inline`). Global styles (`button {\u2026}`) and id styles (`#id`) have their own ops.\n\n**Data bindings** (`upsertBinding`, category attributes|style|initialState): connect a `source` to a `to` field.\nA source `<type>_<idRef>` is scoped to the provider's **DESCENDANTS only** \u2014 bind inside the provider's subtree\n(module sources state/space/navigation/auth/collection are global). `apiContainer.mockData` is builder-only; set a\nreal `query` for production. `transformers: [{action, params}]` post-process the value \u2014 use exact action names\nfrom `plitzi://data-sources`; `twigTemplate` formats it (the value is `{{source}}`, not `{{value}}`). `when` is\na QueryBuilder RuleGroup gating the binding.\n\n**Interactions** (`upsertInteractionFlow`): a `trigger` node first, then callbacks/utilities **in order** (links\ncomputed for you). Node types: `callback` (an element's own callback \u2014 `elementId` is that element), `globalCallback`\n(a source module \u2014 omit `elementId`, the MCP sets it), `utility` (no element). Element `setState`\n(category/key/value/revertOnFinish) \u2260 global `setState` (source `state`, key/type/value). To turn a step off use\n`patchInteractionNode {enabled:false}` \u2014 `deleteInteraction` removes it (destructive; confirm first). Any param\n**value** can be a binding token `{{ source }}` (e.g. notification `content: \"{{ list_<idRef>.item.name }}\"`).\n\n**Pages & navigation:** `upsertPage` \u2014 always set a **relative** `slug` (no leading `/`; the runtime and folder\nslugs prepend the path). A `:name` segment (`\"posts/:postId\"`) is a route param, readable as `{{name}}` and as the\nsource `navigation.routeParams.name` \u2192 build dynamic pages this way. To move between pages **prefer the `Link`\nelement** (a container: `mode` \"page\"/\"internal\"/\"external\") over a `navigate` interaction.\n\n**Touched resources must be malformation-free.** Editing an element/definition also checks its CURRENT stored content\nand BLOCKS the save on any `Pre-existing malformation in <resource>` error (a broken transformer, malformed node,\ninvalid CSS) \u2014 even parts you did not touch. These are NOT from your change (the message says so); fix them in the\nSAME batch and re-apply (the check runs on the result, so the fix unblocks it). `Pre-existing issue` warnings advise\nbut do not block.\n\nRead `plitzi://guide` before anything above is unclear.\n";
+export declare const guideText = "# Plitzi AI MCP \u2014 usage guide\n\nA Plitzi space is **two separate schemas** you edit together:\n- **Element schema** \u2014 the tree of pages and elements (their type, label, props, and which style classes they use).\n- **Style schema** \u2014 reusable **definitions** (CSS classes), design tokens (variables), theme.\n\nThey are stored and persisted independently, but a single `plitzi_apply` batch may touch **both atomically**.\nTo style a specific element you do two things in one batch: write a **definition** (style schema) and **attach**\nit via the element's `style.base` (element schema). Example \u2014 \"rename button X to PEPE and make it red\":\n```json\n{ \"operations\": [\n  { \"type\": \"upsertDefinition\", \"ref\": \"btn-x\", \"desktop\": { \"color\": \"red\" } },\n  { \"type\": \"upsertElement\", \"pageRef\": \"home\",\n    \"element\": { \"ref\": \"X\", \"type\": \"button\", \"label\": \"PEPE\", \"style\": { \"base\": [\"btn-x\"] } } }\n] }\n```\n\nReads are cheap by design \u2014 treat them like a filesystem: **list** to navigate, **read one item** for detail.\nNever download a whole tree you do not need.\n\n## Resources (read)\n- `plitzi://primer/{env}` \u2014 **cold-start bundle**: guide + types + css-properties + page/definition/variable\n  **summaries** in one read. Fetch this first instead of the individual resources below. Summaries only \u2014 open a\n  page skeleton or element for its tree/detail.\n- `plitzi://guide` \u2014 this guide.\n- `plitzi://types` \u2014 element types **observed in this space** (ground truth): props, slots, subTypes, plus each\n  type's `label`, `description` (what it is FOR) and `category`, and a `source` (`builtin` | `plugin` | `unknown`).\n  Read the descriptions to pick the right type \u2014 e.g. `apiContainer` fetches backend data into the frontend,\n  `link` navigates between pages, `list` repeats a template over a data array. `plugin` types are custom elements.\n- `plitzi://css-properties` \u2014 valid kebab-case CSS property keys.\n- `plitzi://schema/{env}/pages` \u2014 page **summaries** (ref, label, elementCount, folder). No element trees.\n- `plitzi://folders/{env}` \u2014 page **folders** (the sidebar tree): ref, name, slug, parentId. `/{ref}` for one.\n- `plitzi://schema/{env}/pages/{ref}` \u2014 one page as a **skeleton tree**: each node is `ref/type/label` **plus the\n  style classes it attaches** (`base`, and `slots` for non-base slots) \u2014 names only, no CSS. So you can map every\n  element to its class in a single page read, without opening each element just to learn which class it uses.\n- `plitzi://schema/{env}/pages/{ref}/styles` \u2014 **every style the page uses in one read**: the class definitions its\n  elements attach (deduplicated, **with full CSS**) plus the global styles affecting any element type on the page.\n  Reach for this to recolor/restyle a whole page \u2014 it needs no shared class-name prefix and no per-element reads.\n- `plitzi://schema/{env}/elements/{ref}` \u2014 one element in **full detail** (props, style, parentRef, childRefs).\n  Its `resolvedStyle` inlines the **CSS of every definition** the element attaches (keyed by class ref), so you\n  can see and edit its style without a separate definition read. Its `globalStyles` lists the **global element\n  selectors** that also affect it (the CSS equivalent of `button { \u2026 }`, keyed by the type they target) \u2014 every\n  element of that type inherits them. Edit a global only through the global-style tools (never per element). If the\n  element carries a DOM `id` that an id rule matches, its `idStyle` (`#id`) is inlined too.\n- `plitzi://definitions/{env}` \u2014 the **names** of every style definition.\n- `plitzi://definitions/{env}/{ref}` \u2014 one definition's CSS.\n- `plitzi://global-styles/{env}` \u2014 element **types** that have a site-wide global style. `/{componentType}` for one.\n- `plitzi://id-styles/{env}` \u2014 DOM **ids** that have an id rule (`#id`) targeting a single element. `/{targetId}` for one.\n- `plitzi://style-variables/{env}` \u2014 design tokens by category. `/{category}` for one.\n- `plitzi://schema-variables/{env}` \u2014 space-level values referenced in props as `{{name}}`.\n- `plitzi://settings/{env}` \u2014 space-level settings: the global `customCss` and the state/auth (user-provider) config.\n- `plitzi://interactions/{env}` \u2014 interaction **actions** observed in this space (grouped by node type): the\n  vocabulary for interaction flows.\n- `plitzi://data-sources/{env}` \u2014 data-source **paths** and binding targets observed in this space: the\n  vocabulary for data bindings.\n\nThe style resources also answer under the `plitzi://schema/{env}/\u2026` root as aliases \u2014 `plitzi://schema/{env}/definitions/{ref}`, `plitzi://schema/{env}/style-variables/{category}`, `plitzi://schema/{env}/schema-variables` \u2014 but prefer the ready-made `uri` from search / a write response over hand-building either form.\n\nData resources return `{ stateVersion, data }`. Keep `stateVersion` for optimistic concurrency.\n\n**Reuse what you already know \u2014 don't re-scan an unchanged page.** A page read (`plitzi://schema/{env}/pages/{ref}`)\nreturns a `stateVersion` that is an **aggregate of the whole page**: it changes if and only if some element on the\npage changed. Its skeleton `tree` also carries a `stateVersion` **per node**, identical to the one a direct element\nread or search hit returns for that element. So when you come back to a page you already inspected:\n1. Re-read just the page skeleton and compare its top-level `stateVersion` to the one you held. **Same \u2192 nothing\n   changed since your read; skip re-reading and re-searching the tree** and act on what you already know.\n2. If it differs, diff the per-node `stateVersion`s against the ones you cached and `plitzi_read` **only the nodes\n   that changed** \u2014 never re-search or re-read the whole tree.\n\nThis is a **read-time** shortcut, not a safety guarantee. **Other agents/sub-agents may edit the same space\nconcurrently**, so a version you cached can go stale between your read and your write. Never skip the write-time\ncheck below on the strength of a cached hash \u2014 the guarantee that no concurrent edit is lost comes only from\n`expectedResourceVersions` on `plitzi_apply`, which re-validates against the live data at write time.\n\n## Navigating (files analogy)\nPages and containers are folders; elements are files. **Prefer `plitzi_search` (especially with `include: \"detail\"`)\nover reading elements one by one** \u2014 it jumps straight to elements by label/type/attribute and each hit already\ncarries the element's `uri`, `stateVersion`, `pageUri`, `parentRef` and tree `path`, so you can edit it (with\noptimistic concurrency) **without a follow-up read**. `include: \"detail\"` additionally inlines each hit's props/style\n**and** its `resolvedStyle` (the CSS behind its classes) \u2014 so a search-then-edit is the efficient path and a manual\nelement read is the exception. Search also matches **pages** by name/slug (returned under `pages`, each with its uri +\nstateVersion) and returns any **style definitions** whose name matches the query, with full CSS, under `definitions`.\nWhen you do hold several refs to open (e.g. from a skeleton), read them together with `plitzi_read` rather than one at a time.\n\n## Tools (write)\n- `plitzi_validate` \u2014 check a batch, returns teachable errors/warnings. Writes nothing. Also reports **pre-existing\n  malformations** in any resource the batch touches (see below).\n- `plitzi_apply` \u2014 validate \u2192 apply \u2192 persist atomically. Rejects the whole batch on any error or conflict. Pass\n  `dryRun: true` to apply in memory only and get the same result back (changed versions + full element detail)\n  without persisting \u2014 inspect it, then re-run without `dryRun` to commit.\n- `plitzi_search` \u2014 find elements (and pages/definitions) across the space.\n- `plitzi_read` \u2014 read many resource **uris in one batch** (pages, elements, definitions, variables). Pass the\n  ready-made uris from search / a write response; each result is `{ uri, stateVersion, data }` or a teachable error,\n  so one bad uri never fails the batch. Use it instead of N single reads whenever you already hold several refs.\n\n## Readers: resources vs plitzi_search vs plitzi_read (do not confuse them)\nThree ways to read, each for a different moment \u2014 pick by what you have in hand:\n- **MCP resources** (the `plitzi://\u2026` catalog above) \u2014 the **browsable index**. List them to discover what exists, or\n  open one by URI when you are exploring. This is the passive catalog, not a tool.\n- **`plitzi_search`** \u2014 you know *what* you want but not its **ref/uri** (\"the hero button\"). Search finds it by\n  label/type/attribute and hands back the uri + stateVersion (and, with `include:\"detail\"`, the full element).\n- **`plitzi_read`** \u2014 you **already hold one or more uris** (from search or a write response) and want their\n  content in one batch. It is the tool form of opening resources, for when you have the addresses.\nRule of thumb: **discover \u2192 resources**, **find a ref \u2192 plitzi_search**, **fetch known uris \u2192 plitzi_read**. Never\nhand-build a URI to guess your way to an element \u2014 search for it instead.\n\nWrite tools return what **changed** (`{ uri, stateVersion }`) plus counts, and the **full detail of every element\nthey created or updated** \u2014 each with its own `uri` and `stateVersion` (`elements: [...]`) so a follow-up edit of\nthe same element needs **no intermediate read**. Other resources (pages, definitions, variables) still report only\nuri+stateVersion \u2014 re-read them if you need their new content. The operation shapes are in each tool's input\nschema (discriminated by `type`).\n\n## Addressing\nRefs are the semantic `idRef` (e.g. `\"hero-cta\"`) or the element's **raw id** \u2014 both resolve. Creating an element\nstores the `ref` you chose as its **idRef**.\n\nThe idRef is not just an alias \u2014 it is the **wiring key the runtime uses**. A provider registers its data source as\n`<type>_<idRef>`, so a `source` you write against a ref resolves to that element at runtime with no id translation.\nRules for a **new** ref (both are enforced; a violation fails the batch):\n- Charset `[A-Za-z0-9_-]`, **starting with a letter** (e.g. `\"products-api\"`, `\"food_item\"`). A `.` would split the\n  `<type>_<idRef>.<field>` source path and the interaction target lookup, so **no dots**. An **underscore is\n  allowed**: the FIRST `_` separates `<type>` from `<idRef>` and element types are camelCase with none, so\n  underscores inside the idRef are unambiguous (`list_food_item` \u2192 type `list`, idRef `food_item`).\n- **Unique across the space**; creating a ref that is taken is rejected (address the existing element instead).\n\nAn idRef is **optional** on an element \u2014 one built in the builder may not have it. The consequence is specific: an\nelement without an idRef **publishes no data source** and **holds no interactions**, because the runtime keys\neverything by idRef and the raw id is never a fallback. You do not have to fix this by hand: writing an\ninteraction **mints an idRef for you** \u2014 the element that hosts the flow, and any element a node targets, is given\na free `<type>-<n>` ref if it lacks one, and the flow is wired to it. A node target you write may be a raw id; it\nis normalised to that element's idRef. (To make an element a data-source **provider** to bind against, give it an\nidRef explicitly with `patchElement`, or create it with the `ref` you want \u2014 a created element stores its ref as\nits idRef.)\n\n**Renaming** an idRef moves the wiring key: every binding source and interaction target across the space that\npointed at the old name is repointed with it, so the element stays wired. You do not have to rewrite them.\n\n## Styling (crosses both schemas)\n- **Mind the type's intrinsic default style.** A type renders with a base CSS *before* any class is attached \u2014 read\n  it from `defaultStyle` on the type in `plitzi://types` (the primer includes it). Do not assume `display: block`:\n  `text`, for one, defaults to `display: inline`, so margins/width/vertical padding behave differently. If you need\n  block/flex layout on such an element, set `display` explicitly in your definition rather than relying on a default.\n- **Images: preserve aspect ratio.** Setting only `width` and `height` (or forcing both) distorts an image. Change\n  one dimension and let the other be `auto`, or set `aspect-ratio` with `object-fit: cover`/`contain`, so the\n  image scales without stretching.\n- **Font size and line height move together.** When you change `font-size`, set `line-height` in the same edit\n  (prefer a unitless ratio like `1.5`, which tracks the font size). Changing one without the other leaves cramped or\n  loosely-spaced text \u2014 they are a joint change, not two separate ones.\n- A definition lives in the **style schema**; an element's `style.base` (element schema) is the link that applies\n  it. Styling an element = upsertDefinition + upsertElement with that ref in `style.base`, in one batch.\n- CSS keys are **kebab-case** (`background-color`). camelCase is rejected \u2014 read `plitzi://css-properties`.\n- Common **shorthands are accepted** and expanded for you: `border`, `border-{side}`, `border-radius`,\n  `padding`, `margin`, `inset`, `gap` (they persist as their longhand keys).\n- **Write CSS atomically \u2014 no multi-value compound shorthands.** Plitzi stores each property on its own so a\n  breakpoint/state/variant can override just that one, so `flex`, `background`, `font`, `transition`,\n  `animation`, `grid`, `place-*`, `outline`, `columns` are **rejected** (or warned) \u2014 use their longhands\n  instead: `background` \u2192 `background-color`/`background-image`/\u2026, `font` \u2192 `font-size`/`font-weight`/\n  `line-height`, `flex: 1` \u2192 `flex-grow`/`flex-shrink`/`flex-basis`. **Flex layout is not a `flex` value**: set\n  `display: flex` **plus** `flex-direction`, `align-items`, `justify-content` as separate properties.\n- CSS is grouped by breakpoint: `desktop`, `tablet`, `mobile`.\n- Reference a style variable in CSS as `var(--name)`; a schema variable in a prop as `{{name}}`.\n- `element.style.base` is a **list** of definition refs; other slots go under `element.style.slots`.\n- **An element can attach SEVERAL classes at once, and they all apply.** `style.base` holds a list, and each\n  non-base slot holds its own \u2014 every attached definition contributes CSS, and they **cascade** (a later class, then a\n  global/id rule, overrides an earlier one on the same property). So when a style looks wrong, the culprit may be\n  ANY attached class, not the one you just edited: read the element's `resolvedStyle` (it inlines the CSS of every\n  class it attaches, keyed by ref) together with its `globalStyles`/`idStyle` and the type's `defaultStyle`, and\n  fix the class that actually sets the property \u2014 do not just pile another class on top.\n- **Three kinds of style live in the style schema \u2014 do not confuse them:**\n  - **Definitions** = reusable CSS **classes** (`upsertDefinition`/`patchDefinition`/`deleteDefinition`, keyed by a\n    class `ref`). Attach one to an element via `style.base` to style **that** element (and anything else that opts in).\n    This is the **default** way to style one element.\n  - **Global styles** = the CSS equivalent of a bare element selector like `button { \u2026 }`\n    (`upsertGlobalStyle`/`patchGlobalStyle`/`deleteGlobalStyle`, keyed by `componentType`). They style **every**\n    element of that type at once. Use these for site-wide intent \u2014 e.g. \"all buttons rounded\":\n    `{ \"type\": \"upsertGlobalStyle\", \"componentType\": \"button\", \"desktop\": { \"border-radius\": \"9999px\" } }`.\n  - **Id styles** = the CSS equivalent of an id selector like `#hero { \u2026 }`\n    (`upsertIdStyle`/`patchIdStyle`/`deleteIdStyle`, keyed by `targetId`). They style the **single** element whose\n    DOM `id` attribute equals `targetId` \u2014 so the element must carry that `id` (set it in its props). Prefer a\n    **definition** for one element; reach for an id style only when a specific, uniquely-identified node must be\n    targeted by id: `{ \"type\": \"upsertIdStyle\", \"targetId\": \"hero\", \"desktop\": { \"min-height\": \"100vh\" } }`.\n  - The three share one name space, so an op refuses a name held by another kind (guards against a typo silently\n    rewriting every element of a type, or converting a class into an id rule). If refused, you targeted the wrong\n    kind \u2014 switch tools or rename.\n\n## Style variants & element state\nA **variant** is a named CSS override on a definition (e.g. a button class with a `primary` variant). It takes two\nsteps across the two schemas:\n- **Declare** the variant CSS on the class (style schema): `upsertDefinition`/`patchDefinition` with\n  `variants: { \"primary\": { \"desktop\": { \"background-color\": \"#111\" } } }` (per slot under `slots.<slot>.variants`).\n- **Apply** it to an element (element schema): `initialState.styleVariant` =\n  `{ \"<class-ref>\": { \"base\": \"primary\" } }` \u2014 a slot name instead of `base` targets that slot; an array applies\n  several. Set it via `upsertElement`/`patchElement`.\nAn element read reports `availableVariants` (which variant each attached class offers) and the element's current\n`initialState`, so you can see a button **has** a `primary` variant and whether it uses it. If the user asks for a\nvariant that does not exist yet, **create it (upsertDefinition variants) and apply it in the same batch**.\n- `initialState.visibility` (boolean) sets whether the element starts shown or hidden.\n\n## Data bindings\nConnect a data **source** to an element field. A binding is `{ to, source, transformers?, when?, enabled? }` grouped\nby **category**: `attributes` (a prop), `style` (a style value), `initialState` (an initial-state key).\n- `upsertBinding` adds one, or replaces the binding already feeding the same `to` (or `id`).\n- `patchBinding` edits an existing one (matched by `to`/`id`); `deleteBinding` removes it.\nDiscover valid source paths **and the transformer catalog** in `plitzi://data-sources/{env}`. Example \u2014 feed an API\nlist into a list element:\n`{ \"type\": \"upsertBinding\", \"pageRef\": \"home\", \"ref\": \"myList\", \"category\": \"attributes\",\n  \"binding\": { \"to\": \"items\", \"source\": \"apiContainer_x.data\" } }`.\n\n**Source scope \u2014 a source is visible to the provider's DESCENDANTS only.** An element source named\n`<type>_<idRef>` (e.g. `apiContainer_products`, `list_food-list`) is published by that element into the scope of\nits **subtree**, so **only elements INSIDE the provider can bind to it**. Binding a sibling or an unrelated element\nto it resolves to nothing at runtime. So to consume `apiContainer_products.data`, the bound element must live under\nthat apiContainer; inside a `list`, the repeated `listItem` and its children read the per-row source\n(`list_<idRef>.item.<field>`). Module sources (no `<type>_<idRef>` head \u2014 `state`, `space`, `navigation`,\n`auth`, `collection`) are global and bindable anywhere. Binding an element to an element source outside its\nprovider's subtree is schema-valid but **broken at runtime** (the source is not in scope), so\n`plitzi_validate`/`plitzi_apply` treat it as an **error and reject the batch** \u2014 move the element under the\nprovider, or bind a source that is in scope.\n\n**mockData is builder-only.** An `apiContainer`'s `mockData` prop feeds sample data **while editing in the\nbuilder**; the published runtime fetches the real `query` instead. Never rely on mockData as the production source \u2014\nset a real `query`/`method` so the binding has data at runtime.\n\n**`transformers` \u2014 post-process the value before it reaches the field** (`source \u2192 t\u2081 \u2192 t\u2082 \u2192 field`). An array of\n`{ action, params }`; the runtime runs them in order and resolves each by its `action` alone, so an **unknown\naction is silently skipped** and the raw value passes through. Use the **exact** action names from\n`plitzi://data-sources` (`transformers`). The most common is **`twigTemplate`** to format a value \u2014 the incoming\nvalue is the **`{{source}}`** token (NOT `{{value}}`); `{{sourceTo}}` is the field's previous value. Example \u2014\nshow a number with units:\n`{ \"type\": \"upsertBinding\", \"pageRef\": \"home\", \"ref\": \"food-item-time\", \"category\": \"attributes\",\n  \"binding\": { \"to\": \"content\", \"source\": \"list_food-list.item.cookTimeMinutes\",\n    \"transformers\": [ { \"action\": \"twigTemplate\", \"params\": { \"template\": \"{{source}} min de cocci\u00F3n\" } } ] } }`.\nOther transformers: `dateConverter` (format a date/timestamp), `capitalize`, `stringToArray` (split on a\nseparator), `arrayMap` (remap the keys of each object in an array), `staticValue`. Transformer `params` values are\nstrings. Each transformer also takes an optional `enabled` flag: set `\"enabled\": false` to keep it in the chain but\nskip it at runtime (defaults to true) \u2014 the value passes through untouched, and a disabled transformer is not\nvalidated.\n\n**`when` \u2014 gate the binding** with a QueryBuilder RuleGroup: the binding only applies when the guard passes against\nthe data source. Shape: `{ \"combinator\": \"and\", \"rules\": [ { \"field\": \"<path>\", \"operator\": \"=\", \"value\": \"x\" } ] }`\n(operators: `=`, `!=`, `<`, `>`, `contains`, `beginsWith`, `empty`, `in`, `between`, \u2026; nest RuleGroups for\nand/or). The guard is validated structurally. Example \u2014 only bind when a flag is set:\n`\"when\": { \"combinator\": \"and\", \"rules\": [ { \"field\": \"status\", \"operator\": \"=\", \"value\": \"published\" } ] }`.\n\n## Interactions\nAn interaction **flow** is a **trigger** (an event like `onClick`, `onPageLoad`) followed by the callbacks/utilities\nit runs, in order. You pass the steps **in order** and the stored beforeNode/afterNode/flowId links are computed for\nyou \u2014 never wire them by hand. Each step also has an `enabled` flag (see disable vs delete below).\n\n**Node types & `elementId`** \u2014 a step names which element (or module) provides the callback it runs. Picking the\n**wrong node type for an action** makes the runtime resolve it against nothing, so the step **silently does nothing**:\n- `trigger` \u2014 the event; belongs to the host element. `elementId` defaults to the host.\n- `callback` \u2014 a callback provided by a **specific element**. `elementId` is that element's ref (the flow host by\n  default, or another element to act on); give its ref or raw id and it is normalised to the idRef. Every element\n  registers a built-in **`setState`** callback that changes **its own attribute or state**: params\n  `category` (`\"attribute\"` \u2014 set a prop like `content`/`disabled` \u2014 or `\"state\"` \u2014 `visibility` or a style\n  selector), `key`, `value` (a **scalar** whose type follows the target attribute \u2014 a real boolean `true`/`false`\n  for a boolean attribute, a number for a numeric one, otherwise a string), and **`revertOnFinish`**. Set\n  `revertOnFinish: true` for a **temporary** change (a \"loading\u2026\" label, disabling a button while it works): it is\n  **undone automatically when the flow finishes**, so you do **NOT** add manual restore steps at the end. This element\n  `setState` has **no** `type` param (that belongs to the global one below). An element type may also register its\n  own extra callbacks.\n- `globalCallback` \u2014 a callback provided by a **source module**, NOT by any element: `addNotification` (source\n  `space`), `setState`/`clearState` (`state`), `navigate` (`navigation`), `authLogin`/`authLogout`/\n  `authRefreshDetails` (`auth`), `addCollectionRecord`/`updateCollectionRecord`/`removeCollectionRecord`\n  (`collection`). Its `elementId` is the **source module id**, never the host element \u2014 a node that stored the host\n  idRef here would resolve to nothing at runtime. **Omit `elementId`**: the MCP sets the correct source and fills the\n  builder's **param defaults** (e.g. `addNotification` gets `autoDismiss:true`, `autoDismissTimeout:5000`,\n  `placement:\"top-right\"`, `appeareance:\"success\"`) for any params you leave out. Use **only** the params each\n  callback declares (exact spelling) \u2014 for `addNotification` the visible text goes in `content`; there is **no**\n  `title`/`message`/`type` param, and any unknown key is dropped. See the full param schema for each callback under\n  `globalCallbacks` in `plitzi://interactions/{env}`.\n- **Two `setState`s \u2014 do not mix them:** the **element** `setState` (nodeType `callback`, on an element,\n  category/key/value/revertOnFinish) changes THAT element's attribute/state and is what you want to change a button's\n  label or disabled flag. The **global** `setState` (nodeType `globalCallback`, source `state`, key/type/value)\n  writes `runtime.state.<key>`. They share a name but have different node types AND different params.\n- `utility` \u2014 a built-in utility action (no element/source module); nodeType `utility`. Use the **exact** param\n  names: `delayTime` waits `time` milliseconds (**not** `delay`), `twigTemplate` (`returnMode`, `template`),\n  `webHook` (`url`, `method`, \u2026). See `utilities` in `plitzi://interactions/{env}`.\n\n**A param value can be a data binding.** Any interaction param may hold a `{{ source }}` token instead of a literal \u2014\nit resolves at runtime exactly like a prop binding, using the same source grammar (`<type>_<idRef>.<path>`, or a\nmodule source like `navigation`/`state`). This is how a step reacts to *the data in context*: inside a `listItem`,\na click on a row can show `addNotification` with `content: \"{{ list_<idRef>.item.name }}\"` \u2014 the clicked row's field.\nThe value follows the source's type, so a token is valid even where a param expects a boolean/number. Copy/paste of an\nelement repoints these tokens to the new idRefs automatically, along with the element's bindings.\n\n**Navigating between pages \u2014 prefer the `Link` element over an interaction.** For a plain \"go to page X\" the right\ntool is a `link` element (a container, see *Pages & folders*), not a `navigate` interaction step. Use the\n`navigate` globalCallback only when the navigation is one step of a larger flow (e.g. submit a form, then go).\n\nTools:\n- `upsertInteractionFlow` \u2014 create or replace one flow. The FIRST node must be a `trigger`. Pass `flowId` (the\n  trigger's node id) to replace an existing flow. Example (elementId omitted \u2014 the MCP wires it to `space` and fills\n  the notification defaults):\n  `{ \"type\": \"upsertInteractionFlow\", \"pageRef\": \"home\", \"ref\": \"cta\", \"nodes\": [\n    { \"nodeType\": \"trigger\", \"action\": \"onClick\", \"title\": \"Click\" },\n    { \"nodeType\": \"globalCallback\", \"action\": \"addNotification\", \"title\": \"Notify\",\n      \"params\": { \"content\": \"Saved!\" } } ] }`.\n- `patchInteractionNode` \u2014 change one step in place (by `nodeId`); `params` merge onto the node.\n\n**Disable vs delete a step \u2014 do not confuse them (three different intents):**\n- **Disable / deactivate / turn off a step** (keep it in the flow, just stop it running): `patchInteractionNode`\n  with `{ \"enabled\": false }`. Re-enable with `{ \"enabled\": true }`. This is NOT a deletion \u2014 the step stays.\n- **Remove one step** from a flow: `deleteInteraction` with `nodeId` (its neighbors are re-linked).\n- **Remove the whole flow**: `deleteInteraction` with `flowId` (the trigger node id).\n\nSo \"deactivate the addNotification step\" means `patchInteractionNode { enabled: false }` \u2014 never delete the step, and\nnever delete the flow. `deleteInteraction` is **destructive and not undoable**: only use it when the user asked to\n*remove* something, and **confirm with the user before deleting** a step or a flow.\n\nDiscover valid actions in `plitzi://interactions/{env}`: `actions` = observed, `globalCallbacks` /\n`elementCallbacks` / `utilities` = the built-in vocabularies with their full param schema, so you know the exact\nnode type and valid params per action. An element read lists its flows as ordered nodes (each with its `id` and\n`enabled`), so a follow-up patch/delete needs no extra read.\n\n## Pages & folders\n- **Always set a `slug` when creating a page** (`upsertPage`) \u2014 it is the page's URL path and good practice for a\n  clean, stable route (e.g. `\"pricing\"` or `\"posts/:postId\"`). Omit it and the page ref is used as the slug,\n  and `plitzi_validate`/`plitzi_apply` warn so you remember to set a meaningful one.\n- **A page slug is RELATIVE \u2014 do NOT start it with `/`.** The runtime prepends the leading slash (and any folder\n  path) itself, so a leading slash doubles it. Write `\"pricing\"`, not `\"/pricing\"`. (upsertPage strips a leading\n  slash for you, but write it relative.)\n- **Dynamic pages \u2014 route params.** A slug segment written `:name` (e.g. `\"posts/:postId\"`) is a **route param**,\n  exactly like React Router. On that page it is readable **two ways**: as `{{name}}` inside a prop, and as the\n  data-binding source **`navigation.routeParams.name`** (the `navigation` module source, global \u2014 bindable\n  anywhere). So a blog is a `\"posts\"` list page plus a `\"posts/:postId\"` detail page whose `apiContainer` query\n  binds `navigation.routeParams.postId` to fetch that one post. (`navigation.queryParams.<name>` exposes `?query=`\n  string params the same way.)\n- **Navigate with the `Link` element, not an interaction.** `link` is a **container** \u2014 it wraps any children and\n  navigates on click, so it is the default way to move between pages. Its `mode`: `\"page\"` links to another space\n  page (set `href` to the target page, folder path resolved for you); `\"internal\"` takes a path inside the space and\n  resolves `{{token}}` templates in it, so a row's \"view\" link is `mode:\"internal\", href:\"posts/{{postId}}\"`;\n  `\"external\"` is a full URL. `target` is `self`/`blank`/`parent`/`top`. Reach for the `navigate` globalCallback\n  only when navigation must be **one step inside a larger interaction flow** (e.g. save, then go) \u2014 for a plain link,\n  use `link`.\n\nPages can be grouped into **folders** (the sidebar tree). A folder is `{ ref, name, slug, parentId? }`; its `ref`\n**is its id** (there is no separate idRef), and that id is what a page and a nested folder reference.\n- **Folder slugs PREPEND to the page URL \u2014 this is how nested URLs are built.** The full path is each ancestor\n  folder's slug plus the page slug, joined by `/`: a page at slug `\"1-1-1\"` inside `folder-1` > `folder-1-1`\n  resolves to `/folder-1/folder-1-1/1-1-1`. So a folder slug is part of the route; keep folder slugs relative too.\n- Create/rename/move a folder with `upsertFolder` (the `ref` you pass on create becomes its id \u2014 pick a stable one\n  like `\"blog\"`). Nest it under another with `parentId` (a folder ref); `parentId: null` moves it back to the root.\n- Put a page in a folder with `upsertPage`'s `folder` (a folder ref). A page's `folder` is always either **empty\n  (root)** or an **existing folder id**: `folder: null` or `folder: \"\"` moves it to the root, and any other value\n  must resolve to a folder that already exists or is created earlier in the same batch \u2014 an unknown folder is\n  rejected, never stored.\n- `deleteFolder` removes a folder and **promotes its contents up one level** \u2014 its child folders and its pages move\n  to its parent (or the root). A folder cannot be nested under itself or one of its descendants.\n- **Disable a page** with `upsertPage`'s `enabled: false`; `enabled: true` re-enables it (defaults to enabled, and\n  a page read reports its current `enabled`). Disabling only affects the **published SDK runtime** \u2014 the page stops\n  being routable/accessible to end users. It stays fully **editable here**: you can still read it and apply any op to\n  a disabled page. This does not delete it \u2014 `deletePage` does.\n\n## Settings\nSpace-level configuration lives in `plitzi://settings/{env}` and is edited with a single **`patchSettings`** op\n(merge \u2014 only the fields you pass change):\n- `customCss` \u2014 **raw global CSS** injected for the whole space. Use it only for genuinely site-wide rules\n  (`@keyframes`, `@font-face`, resets). To style an element, write a **definition** and attach it \u2014 never customCss.\n- `keepState` / `stateStorage` \u2014 persist element state across reloads (`localStorage`/`sessionStorage`).\n- **User provider / auth**: `userProvider` (`auth0`|`basic`|`custom`|`\"\"` to disable), `auth0Domain`,\n  `auth0ClientId`, `tokenStorage`, and the `loginUrl`/`userUrl`/`refreshUrl`/`logoutUrl` + `detailsPath`/\n  `tokenPath`/`expirationTimePath` mapping. Example \u2014 inject a keyframe globally:\n  `{ \"type\": \"patchSettings\", \"customCss\": \"@keyframes spin { to { transform: rotate(360deg); } }\" }`.\n\n## Semantics\n- **props are fully replaced** on `upsertElement`: send every prop you want to keep. To change only some props,\n  use **`patchElement`** \u2014 it merges `props`/`style` onto the existing element (listed keys change, `null` unsets\n  a key, everything else is preserved) and never creates. Combined with `plitzi_search` (which returns the ref +\n  stateVersion), a targeted edit is two calls with no read.\n- **definition CSS is fully replaced** on `upsertDefinition`: send every property you want to keep. To change only\n  some declarations, use **`patchDefinition`** \u2014 it merges CSS per breakpoint/state/variant/slot onto the existing\n  definition (listed keys change, `null` removes a property, everything else is preserved) and never creates.\n  Example \u2014 recolor one definition without resending it: `{ \"type\": \"patchDefinition\", \"ref\": \"btn-x\",\n  \"desktop\": { \"background-color\": \"#111\" } }`.\n- **Atomic batches**: if any operation fails, `plitzi_apply` persists nothing.\n- **Every resource you touch must be malformation-free \u2014 pre-existing errors block the save.** When your batch edits\n  an element (or a definition/global/id style), the validator also checks the resource's **current stored content**\n  for malformations \u2014 a broken transformer action, a malformed interaction node, invalid CSS \u2014 even in parts your\n  edit does not touch. Such a finding is reported as a `Pre-existing malformation in <resource>: \u2026` **error**, and\n  `plitzi_apply` rejects the batch until it is fixed. These are **not caused by your change** (the message says so)\n  \u2014 do not be confused; fix them **in the same batch** and re-apply. Because the check runs on the resulting state,\n  including the fix in your batch is exactly what unblocks the save. (Advisory issues \u2014 an unobserved source/action\n  name that may still be a valid plugin, a binding target a plugin manifest does not list \u2014 come back as\n  `Pre-existing issue \u2026` **warnings** and do not block.)\n- **Optimistic concurrency \u2014 read before you write, and prove your read is current.** Editing a resource means you\n  read it first, so you hold its `stateVersion`. **Always pass `expectedResourceVersions`** (URI \u2192 the stateVersion\n  you read) for every resource your batch changes. If another agent edited it in the meantime, the live version no\n  longer matches and apply is **rejected with a conflict** \u2014 nothing persists. Then re-read the reported resources\n  (their new content + version) and retry on top of the fresh state. This is exactly how a file editor forces a\n  re-read after a stale write: it is what keeps concurrent agents from silently overwriting each other's changes, so\n  never omit it \"to save a call\".\n";

package/dist/src/modules/mcp/helpers/index.d.ts

@@ -1,4 +1,8 @@
+export * from './agentPrompt';
 export * from './computeVersion';
 export * from './space';
+export * from './uris';
 export * from './guide';
+export * from './interactions';
+export * from './log';
 export * from './opResult';

package/dist/src/modules/mcp/helpers/interactions.d.ts

@@ -0,0 +1,30 @@
+import { AIBinding, AIBindings, AIInteractionFlow, AIInteractionNodeType } from '../types';
+import { RuleGroup } from '@plitzi/plitzi-ui/QueryBuilder';
+import { ElementBinding, ElementDefinition, ElementInteraction } from '@plitzi/sdk-shared';
+/** The node shape agents supply on write: same as AIInteractionNode but `id` is optional (generated when
+ *  omitted). Kept structural so the tool-layer zod type assigns to it without importing the tool layer here. */
+export interface FlowNodeInput {
+    id?: string;
+    title: string;
+    nodeType: AIInteractionNodeType;
+    action: string;
+    params?: Record<string, unknown>;
+    enabled?: boolean;
+    when?: RuleGroup;
+    elementId?: string;
+    preview?: Record<string, unknown>;
+}
+declare const BINDING_CATEGORIES: Array<keyof AIBindings>;
+export declare const NULLISH_ELEMENT_IDS: Set<string>;
+export declare const flowsFromInteractions: (interactions: Record<string, ElementInteraction> | undefined) => AIInteractionFlow[];
+export declare const newNodeId: () => string;
+/** Materialize an ordered list of nodes into the stored linked-node map for ONE flow: assign ids where missing,
+ *  set flowId to the trigger id, and recompute beforeNode/afterNode from the order. `ownerId` is the default
+ *  source element for callbacks that name none. */
+export declare const materializeFlow: (nodes: FlowNodeInput[], ownerId: string) => {
+    flowId: string;
+    record: Record<string, ElementInteraction>;
+};
+export declare const bindingToAI: (binding: ElementBinding) => AIBinding;
+export declare const bindingsToAI: (bindings: ElementDefinition["bindings"] | undefined) => AIBindings | undefined;
+export { BINDING_CATEGORIES };

package/dist/src/modules/mcp/helpers/log.d.ts

@@ -0,0 +1,8 @@
+import { McpLogger } from '@plitzi/sdk-shared';
+export interface McpLog {
+    toolCall(name: string, args: unknown, ms: number, error?: unknown): void;
+    resourceRead(uri: string, ms: number, error?: unknown): void;
+}
+/** Build the request-log sink for one MCP server. Dispatches structured events to the consumer's `logger` when
+ *  provided; otherwise renders to the console when MCP_DEBUG=1; otherwise a no-op. */
+export declare const createMcpLog: (logger?: McpLogger) => McpLog;

package/dist/src/modules/mcp/helpers/log.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/modules/mcp/helpers/space.d.ts

@@ -1,20 +1,79 @@
-import { Element, PageFolder, Schema, Style } from '@plitzi/sdk-shared';
+import { AIElementDetail } from '../types';
+import { ComponentCatalog, Element, PageFolder, Schema, Style } from '@plitzi/sdk-shared';
 /** The working view the tools read and mutate: the two Plitzi schemas (elements + style), which the platform
- *  stores and persists as separate documents (Space model / Style model). */
+ *  stores and persists as separate documents (Space model / Style model). `catalog` is read-only reference data
+ *  (plugin element-type semantics), not persisted — used only to enrich the plitzi://types resource. */
 export interface Space {
     schema: Schema;
     style: Style;
+    catalog?: ComponentCatalog;
 }
 export declare const cloneSpace: (space: Space) => Space;
+export declare const emptySpace: () => Space;
 export declare const slugify: (value: string) => string;
-export declare const isPageElement: (schema: Schema, el: Element) => boolean;
-export declare const getPageElements: (schema: Schema) => Element[];
-/** Stable, human-readable ref for a page. Prefers an agent-chosen aiRef, then slug, then a slugified label. */
+/** A value when it is a string, otherwise undefined — for the many attributes typed as `unknown` that are strings
+ *  in practice (name, slug, subType, dom id…). */
+export declare const strOr: (value: unknown) => string | undefined;
+/** Display name of a page or element: its `name` attribute when set, otherwise its definition label. */
+export declare const nameOf: (el: Element) => string;
+/** Stable, human-readable ref for a page: its idRef, then slug, then a slugified label. A page without an idRef is
+ *  still addressable — unlike a data source, a page ref has meaningful fallbacks the agent can read off the tree. */
 export declare const pageRefOf: (el: Element) => string;
-/** Stable ref for a non-page element. An agent-chosen aiRef when present, otherwise the opaque id. */
+/** Stable ref for ADDRESSING a non-page element in the tree: its idRef when present, otherwise the opaque id so an
+ *  element without one is still reachable — the agent needs to name it to give it an idRef in the first place.
+ *  This is not the wiring key: the runtime wires interactions and data sources by idRef only, so an element
+ *  addressed here by its id alone publishes no source and takes no interactions (see `getSourceName`). */
 export declare const elementRefOf: (el: Element) => string;
-/** Finds a page by its semantic ref (aiRef/slug/…) or its raw id, so legacy schemas without an aiRef still resolve. */
+/** A memoized element projection: its full detail and the stateVersion (content hash) derived from it, plus the
+ *  style object they were computed against (a different style ref forces a recompute). */
+export interface ElementVersion {
+    style: Style;
+    detail: AIElementDetail;
+    version: string;
+}
+export interface SpaceIndex {
+    /** Ids of the page elements (schema.pages ∪ every element whose type is 'page'). */
+    pageIds: Set<string>;
+    /** The page elements, in schema.flat insertion order (what getPageElements returns). */
+    pageElements: Element[];
+    /** page ref (idRef/slug/label) AND raw page id → the page element. First writer wins on a ref collision. */
+    pageByRef: Map<string, Element>;
+    /** non-page idRef AND raw id → the element. First writer wins on a ref collision. */
+    elementByRef: Map<string, Element>;
+    /** Any element id (page root or nested descendant) → the id of the page it belongs to. */
+    pageOf: Map<string, string>;
+    /** element id → its memoized detail/version, so a page-skeleton hash, a search hit and a follow-up element read
+     *  all resolve the same element once. Populated lazily by `elementView`; dropped whole on `invalidateIndex`. */
+    detailCache: Map<string, ElementVersion>;
+}
+/** The index for a schema, built once and memoized on the schema object. */
+export declare const spaceIndex: (schema: Schema) => SpaceIndex;
+/** Drop the memoized index wholesale. A correctness fallback for a mutation with no dedicated incremental updater;
+ *  the next scanner rebuilds against current state. Prefer the index* helpers below, which keep a built index in
+ *  step in O(1) — a large structural batch would otherwise pay an O(flat) rebuild after every op. */
+export declare const invalidateIndex: (schema: Schema) => void;
+/** A new non-page element was created under `pageId`. */
+export declare const indexAddElement: (schema: Schema, el: Element, pageId: string) => void;
+/** These non-page elements were deleted (an element and its descendants). */
+export declare const indexRemoveElements: (schema: Schema, els: Element[]) => void;
+/** An existing element was just given an idRef (it had none), so it becomes addressable by that ref. */
+export declare const indexReRefElement: (schema: Schema, el: Element) => void;
+/** A new page element was created. */
+export declare const indexAddPage: (schema: Schema, page: Element) => void;
+/** A page and its `descendants` (its non-page elements) were deleted. */
+export declare const indexRemovePage: (schema: Schema, page: Element, descendants: Element[]) => void;
+/** A page's slug/name/default changed; re-key its pageByRef entry if that changed its ref. `oldRef` is the ref
+ *  computed BEFORE the attribute change. */
+export declare const indexReRefPage: (schema: Schema, page: Element, oldRef: string) => void;
+/** A move reparented an element within its page: the ref/page maps are unchanged, but the moved element's
+ *  parentRef and both parents' childRefs did change, so their memoized detail must be dropped. */
+export declare const indexInvalidateDetails: (schema: Schema) => void;
+export declare const isPageElement: (schema: Schema, el: Element) => boolean;
+export declare const getPageElements: (schema: Schema) => Element[];
+/** Finds a page by its semantic ref (idRef/slug/…) or its raw id, so legacy schemas without an idRef still resolve. */
 export declare const findPageByRef: (schema: Schema, pageRef: string) => Element | undefined;
+/** Find any non-page element by its semantic ref (idRef) or raw id, across the whole space. */
+export declare const findElementByRef: (schema: Schema, ref: string) => Element | undefined;
 export declare const pageFoldersOf: (schema: Schema) => PageFolder[];
 /** Resolve a folder by its id, or (for agent convenience) by an exact name or slug when that is unambiguous. */
 export declare const findFolderByRef: (schema: Schema, ref: string) => PageFolder | undefined;
@@ -34,14 +93,12 @@ export declare const routeParamNames: (schema: Schema) => string[];
 export declare const elementById: (schema: Schema, id: string) => Element | undefined;
 export declare const descendantIds: (schema: Schema, pageRootId: string) => string[];
 /** Resolve a ref to a concrete element within a page subtree (or the page root itself). Accepts either the
- *  semantic ref (aiRef) or the raw element id, so schemas predating aiRef keep working through their ids. */
+ *  semantic ref (idRef) or the raw element id, so schemas predating idRef keep working through their ids. */
 export declare const resolveRef: (schema: Schema, page: Element, ref: string) => Element | undefined;
 /** Ordered children of an element, honoring definition.items and skipping dangling ids. */
 export declare const orderedChildren: (schema: Schema, el: Element) => Element[];
-/** The page ref an element belongs to, walking up parents. 'unknown' when it has no page ancestor. */
+/** The page ref an element belongs to. 'unknown' when it has no page ancestor. */
 export declare const pageRefOfElement: (schema: Schema, el: Element) => string;
-/** Find any non-page element by its semantic ref (aiRef) or raw id, across the whole space. */
-export declare const findElementByRef: (schema: Schema, ref: string) => Element | undefined;
 /** Total number of descendant elements under a subtree (excluding the root). */
 export declare const descendantCount: (schema: Schema, rootId: string) => number;
 export declare const emptySpaceMessage = "Space data not available";

package/dist/src/modules/mcp/helpers/uris.d.ts

@@ -0,0 +1,28 @@
+import { Env } from '../types';
+export declare const guideUri = "plitzi://guide";
+export declare const typesUri = "plitzi://types";
+export declare const cssPropertiesUri = "plitzi://css-properties";
+export declare const primerUri: (env: Env) => string;
+export declare const pagesUri: (env: Env) => string;
+export declare const pageUri: (env: Env, ref: string) => string;
+export declare const pageStylesUri: (env: Env, ref: string) => string;
+export declare const elementUri: (env: Env, ref: string) => string;
+export declare const schemaVarsUri: (env: Env) => string;
+export declare const settingsUri: (env: Env) => string;
+export declare const interactionsUri: (env: Env) => string;
+export declare const dataSourcesUri: (env: Env) => string;
+export declare const foldersUri: (env: Env) => string;
+export declare const folderUri: (env: Env, ref: string) => string;
+export declare const defsUri: (env: Env) => string;
+export declare const defUri: (env: Env, ref: string) => string;
+export declare const globalsUri: (env: Env) => string;
+export declare const globalUri: (env: Env, componentType: string) => string;
+export declare const idsUri: (env: Env) => string;
+export declare const idUri: (env: Env, targetId: string) => string;
+export declare const styleVarsUri: (env: Env) => string;
+export declare const styleVarUri: (env: Env, category: string) => string;
+export declare const aliasedRoots: string[];
+export declare const itemTemplates: (env: Env) => string[];
+/** The remainder of `uri` after `prefix`, or undefined when it does not start with it — so a resolver matches a
+ *  family and extracts its ref in one step, without repeating the prefix string for both the startsWith and slice. */
+export declare const afterPrefix: (uri: string, prefix: string) => string | undefined;

package/dist/src/modules/mcp/index.d.ts

@@ -1,7 +1,7 @@
 export { createMcpServer, handleMcp, serveMcp, readMcpBody } from './handler';
 export { readResource, resourceVersion, registerResources, buildTypeRegistry, cssProperties } from './resources';
 export { apply, validate, search, read, validateOperations, operation, tools } from './tools';
-export { computeVersion } from './helpers';
+export { computeVersion, buildAgentGuide } from './helpers';
 export { createHttpPreviewClient } from './previewClient';
 export { createHttpScreenshotClient } from './screenshotClient';
 export type { HttpPreviewClientConfig } from './previewClient';

package/dist/src/modules/mcp/mcp.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/modules/mcp/resources/canonical.d.ts

@@ -1,6 +1,5 @@
 import { Env } from '../types';
 export declare const canonicalUri: (env: Env, uri: string) => string;
-export declare const itemTemplates: (env: Env) => string[];
 /** Teachable message for a URI that read as null. Distinguishes a well-formed URI whose ref does not resolve (the
  *  resource may be stale/deleted) from a URI whose shape matches no template at all (malformed — echo the valid
  *  templates so the agent stops hand-building URIs). See RFC 0004 I2. */

package/dist/src/modules/mcp/resources/index.d.ts

@@ -1,8 +1,7 @@
 export { readResource, resourceVersion } from './router';
 export { registerResources } from './register';
 export { resourceErrorMessage } from './canonical';
-export { buildTypeRegistry } from '../tools/operations/schema/registry';
-export type { TypeInfo, TypePropInfo, TypeRegistry } from '../tools/operations/schema/registry';
+export { buildTypeRegistry, compoundLonghands, cssProperties, expandShorthand, isCssProperty, suggestCssProperty } from '../catalogs';
+export type { TypeInfo, TypePropInfo, TypeRegistry } from '../catalogs';
 export * from '../tools/operations/schema/translator';
-export { cssProperties, expandShorthand, isCssProperty, suggestCssProperty } from '../tools/operations/style/cssCatalog';
 export * from '../tools/operations/style/translator';

package/dist/src/modules/mcp/resources/primer.d.ts

@@ -2,5 +2,6 @@ import { Space } from '../helpers';
 import { Env, ResourceEnvelope } from '../types';
 /** The cold-start bundle: everything the guide says to read before the first write, in one round-trip.
  *  Summaries only — never full page/element trees (those are opened on demand), so it stays cheap even on a
- *  large space. Returns undefined when the URI is not the primer. */
+ *  large space. Carries the condensed `guideQuickstart` (not the full guideText, which the agent reads on demand at
+ *  plitzi://guide) to keep the bundle small. Returns undefined when the URI is not the primer. */
 export declare const readPrimerResource: (space: Space, env: Env, uri: string) => ResourceEnvelope<unknown> | undefined;

package/dist/src/modules/mcp/resources/register.d.ts

@@ -1,6 +1,6 @@
-import { Space } from '../helpers';
+import { McpLog, Space } from '../helpers';
 import { Env } from '../types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
 /** Register every resource on the MCP server: fixed listings plus templated per-item reads. The space is
  *  loaded lazily via getSpace, so listing resources never touches the store — only reading one does. */
-export declare const registerResources: (server: McpServer, getSpace: () => Promise<Space>, env: Env) => void;
+export declare const registerResources: (server: McpServer, getSpace: () => Promise<Space>, env: Env, log: McpLog) => void;

package/dist/src/modules/mcp/server.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
 import { PreviewClient, ScreenshotClient } from './types';
-import { SSRAdapters } from '@plitzi/sdk-shared';
+import { SSRAdapters, McpLogger } from '@plitzi/sdk-shared';
 /** The MCP service is stateless: every request resolves its own `spaceId` (from the request JWT) and reads the
  *  space fresh through the adapters — schema and style are two documents, read/written independently. Both the
  *  spaceId and the space itself resolve lazily, so the public surface (handshake, tools-list, resources-list,
@@ -15,5 +15,8 @@ export interface McpServerContext {
     /** The dedicated browser service for plitzi_screenshot. Absent → the tool is not registered (only the HTML
      *  plitzi_preview is offered). */
     screenshot?: ScreenshotClient;
+    /** Structured request-log sink. When set, every tool call and resource read emits an McpLogEvent to it (the
+     *  consumer renders them); otherwise logging falls back to the console when MCP_DEBUG=1. */
+    logger?: McpLogger;
 }
-export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot }: McpServerContext) => McpServer;
+export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger }: McpServerContext) => McpServer;