@plitzi/sdk-server 0.32.15 → 0.32.16

package/dist/src/modules/mcp/catalogs/{cssCatalog.d.ts → cssCatalog/index.d.ts}

@@ -1,14 +1,19 @@
-import { CssProps } from '../types';
+import { CssProps } from '../../types';
 /** Every kebab-case CSS property Plitzi's style engine understands. Values written to a definition
  *  must use these exact keys — camelCase or unknown keys are rejected by the validator. */
 export declare const cssProperties: string[];
 export declare const isCssProperty: (key: string) => boolean;
 /** If a camelCase key maps to a known kebab-case property, return it — used to teach the agent the correct key. */
 export declare const suggestCssProperty: (key: string) => string | undefined;
-export declare const COMPOUND_SHORTHANDS: Record<string, string[]>;
-/** The atomic longhands to write instead of a compound shorthand, or undefined when the key is not a compound
- *  shorthand. `flex` layout in particular is NOT `display` + `flex-direction` (those are their own properties). */
-export declare const compoundLonghands: (key: string) => string[] | undefined;
+/** Every shorthand the MCP accepts and atomizes — advertised to the agent so it knows it may write plain CSS. */
+export declare const cssShorthands: string[];
+export declare const isCssShorthand: (key: string) => boolean;
 /** Expand supported CSS shorthands to their longhand keys. Explicit longhands in the same map win over any
  *  expansion (so `{ padding: 8, padding-left: 0 }` keeps padding-left: 0). Unrecognized keys pass through. */
 export declare const expandShorthand: (css: CssProps) => CssProps;
+export type CssPatch = Record<string, string | number | null>;
+/** The longhand keys a shorthand controls — what a `null` patch value has to clear. */
+export declare const shorthandLonghands: (key: string) => string[] | undefined;
+/** Patch flavour of {@link expandShorthand}: a `null` value removes every longhand the key controls, so
+ *  `{ padding: null }` clears all four sides rather than a `padding` key that was never stored. */
+export declare const expandShorthandPatch: (css: CssPatch) => CssPatch;

package/dist/src/modules/mcp/catalogs/cssCatalog/layout.d.ts

@@ -0,0 +1,9 @@
+import { CssProps } from '../../types';
+export declare const expandOverflow: (value: string, out: CssProps) => void;
+export declare const expandFlex: (value: string, out: CssProps) => void;
+export declare const expandFlexFlow: (value: string, out: CssProps) => void;
+export declare const expandPlacePair: (prefix: "place-content" | "place-items" | "place-self", value: string, out: CssProps) => void;
+export declare const expandGridLine: (key: "grid-row" | "grid-column", value: string, out: CssProps) => void;
+export declare const expandGridArea: (value: string, out: CssProps) => void;
+export declare const expandColumns: (value: string, out: CssProps) => void;
+export declare const expandGridTemplate: (value: string, out: CssProps) => void;

package/dist/src/modules/mcp/catalogs/cssCatalog/visual.d.ts

@@ -0,0 +1,8 @@
+import { CssProps } from '../../types';
+export declare const expandOutline: (value: string, out: CssProps) => void;
+export declare const expandListStyle: (value: string, out: CssProps) => void;
+export declare const expandTextDecoration: (value: string, out: CssProps) => void;
+export declare const expandTransition: (value: string, out: CssProps) => void;
+export declare const expandAnimation: (value: string, out: CssProps) => void;
+export declare const expandBackground: (value: string, out: CssProps) => void;
+export declare const expandFont: (value: string, out: CssProps) => void;

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

@@ -1,3 +1,3 @@
 export declare const serverInstructions: string;
-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";
+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. **Write plain CSS** \u2014 shorthands (`border`, `padding`, `margin`, `gap`, `overflow`, `flex`, `background`,\n`font`, `transition`, `animation`, `grid`, `grid-row`/`grid-column`, `place-*`, `outline`, `columns`,\n`list-style`, `text-decoration`) are expanded to their longhands for you, so `border: 1px solid red` is stored as\n`border-top-color`/`border-top-width`/`border-top-style`/\u2026 That is also how you read them back. Flex layout is\nstill `display: flex` + `flex-direction`/`align-items`/\u2026, not a `flex` value. Mind a type's `defaultStyle`\n(`text` is `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- **Write normal CSS \u2014 shorthands are accepted and expanded for you.** `border`, `border-{side}`,\n  `border-width`/`-color`/`-style`, `border-radius`, `padding`, `margin`, `inset`, `gap`, `overflow`,\n  `flex`, `flex-flow`, `background`, `font`, `transition`, `animation`, `grid`, `grid-template`,\n  `grid-area`, `grid-row`, `grid-column`, `place-content`, `place-items`, `place-self`, `outline`,\n  `columns`, `list-style`, `text-decoration` \u2014 the full list is in `plitzi://css-properties` under\n  `shorthands`. They **persist as longhand keys** (that is what a read gives back), so a breakpoint/state/variant\n  can still override one property at a time.\n  - `border: 1px solid red` \u2192 `border-top-width: 1px`, `border-top-style: solid`, `border-top-color: red`, \u2026\n    for all four sides. A shorthand also RESETS what it omits, so `border: none` clears a width a previous\n    definition set.\n  - Comma-separated layers are kept per longhand: `transition: opacity 200ms, transform 300ms` \u2192\n    `transition-property: opacity, transform` + `transition-duration: 200ms, 300ms`.\n  - In a **patch**, a shorthand replaces the longhands it controls (`padding: 8px` overwrites a previous\n    `padding-left`), and `\"border\": null` removes all twelve border longhands.\n- **Flex layout is not a `flex` value**: set `display: flex` **plus** `flex-direction`, `align-items`,\n  `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/resources/index.d.ts

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

package/dist/src/modules/mcp/tests/apply.test.d.ts

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

package/dist/src/modules/mcp/tests/bindings.test.d.ts

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

package/dist/src/modules/mcp/tests/css.test.d.ts

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

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

@@ -0,0 +1,13 @@
+import { Space } from '../helpers';
+import { Operation } from '../tools';
+import { Persisters } from '../types';
+declare const buildSpace: () => Space;
+declare const capturing: (space: Space) => {
+    persisters: Persisters;
+    saved: () => Space;
+};
+declare const spaceWithRoute: () => Space;
+declare const varOp: (pageRef: string, type: string, value: string) => Operation;
+declare const scopeSpace: () => Space;
+declare const malformedSpace: () => Space;
+export { buildSpace, capturing, spaceWithRoute, varOp, scopeSpace, malformedSpace };

package/dist/src/modules/mcp/tests/interactions.test.d.ts

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

package/dist/src/modules/mcp/tests/pages.test.d.ts

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

package/dist/src/modules/mcp/tests/reads.test.d.ts

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

package/dist/src/modules/mcp/tests/search.test.d.ts

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

package/dist/src/modules/mcp/tests/styles.test.d.ts

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

package/dist/src/modules/mcp/tests/tools.test.d.ts

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

package/dist/src/modules/mcp/tests/validation.test.d.ts

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

package/dist/src/modules/mcp/tools/screenshot.d.ts

@@ -412,9 +412,9 @@ export declare const screenshotShape: {
         name: z.ZodString;
     }, z.core.$strip>], "type">>>;
     viewport: z.ZodOptional<z.ZodEnum<{
+        both: "both";
         desktop: "desktop";
         mobile: "mobile";
-        both: "both";
     }>>;
 };
 export declare const screenshotTool: import('.').ToolDef;

package/dist/src/modules/oauth/metadata.d.ts

@@ -19,7 +19,13 @@ export declare const resourceMetadataUrl: (config: OAuthConfig, req: SSRRequest)
  *
  *  `resource` echoes the path the document was asked for: Claude requires it to match the server URL the user
  *  typed, path included, and a dedicated MCP server answers JSON-RPC on every path — so `/.well-known/…/mcp`
- *  describes `https://host/mcp` while the bare path describes the origin. */
+ *  describes `https://host/mcp` while the bare path describes the origin.
+ *
+ *  A server mounted at the ORIGIN is `https://host/`, WITH the trailing slash: a host parses the URL the user
+ *  typed before it does anything with it, and an empty path renders as `/` — that normalized form is what the
+ *  client sends back as the `resource` parameter (asserted in the connector e2e). A document claiming to be
+ *  `https://host` then disagrees with the request made against it, and Claude's connector drops the grant it
+ *  just completed — it takes the token and never opens the session. */
 export declare const protectedResourceMetadata: (config: OAuthConfig, req: SSRRequest) => Record<string, unknown>;
 /** RFC 8414. Public clients with PKCE only: a desktop host stores no secret, so `none` is the sole endpoint auth
  *  method and S256 the sole challenge method. `offline_access` is advertised whenever refresh grants are issued,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.32.15",
+  "version": "0.32.16",
   "license": "AGPL-3.0",
   "files": [
     "dist"
@@ -28,10 +28,10 @@
   "sideEffects": false,
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@plitzi/plitzi-sdk": "0.32.15",
-    "@plitzi/sdk-schema": "0.32.15",
-    "@plitzi/sdk-shared": "0.32.15",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@plitzi/plitzi-sdk": "0.32.16",
+    "@plitzi/sdk-schema": "0.32.16",
+    "@plitzi/sdk-shared": "0.32.16",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.1",
     "zod": "^4.4.3"
@@ -43,18 +43,18 @@
   "devDependencies": {
     "@types/ejs": "^3.1.5",
     "@types/jsdom": "^28.0.3",
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.1.2",
     "@types/react": "^19.2.17",
-    "@vitejs/plugin-react": "^6.0.4",
+    "@vitejs/plugin-react": "^6.0.5",
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.32.0",
-    "jsdom": "^29.1.1",
+    "jsdom": "^30.0.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "vite": "^8.1.5",
+    "vite": "^8.2.0",
     "vite-plugin-dts": "^5.0.3",
     "vitest": "^4.1.10"
   },

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

@@ -1,205 +0,0 @@
-import styleConstants from "@plitzi/sdk-shared/style/styleConstants";
-//#region src/modules/mcp/catalogs/cssCatalog.ts
-/** Every kebab-case CSS property Plitzi's style engine understands. Values written to a definition
-*  must use these exact keys — camelCase or unknown keys are rejected by the validator. */
-var cssProperties = Array.from(new Set(Object.values(styleConstants))).sort();
-var cssPropertySet = new Set(cssProperties);
-var isCssProperty = (key) => cssPropertySet.has(key);
-var toKebab = (key) => key.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-/** If a camelCase key maps to a known kebab-case property, return it — used to teach the agent the correct key. */
-var suggestCssProperty = (key) => {
-	const kebab = toKebab(key);
-	return cssPropertySet.has(kebab) ? kebab : void 0;
-};
-var splitTokens = (value) => {
-	const tokens = [];
-	let depth = 0;
-	let current = "";
-	for (const ch of value.trim()) {
-		if (ch === "(") depth += 1;
-		else if (ch === ")") depth = Math.max(0, depth - 1);
-		if (/\s/.test(ch) && depth === 0) {
-			if (current) {
-				tokens.push(current);
-				current = "";
-			}
-		} else current += ch;
-	}
-	if (current) tokens.push(current);
-	return tokens;
-};
-var COMPOUND_SHORTHANDS = {
-	flex: [
-		"flex-grow",
-		"flex-shrink",
-		"flex-basis"
-	],
-	"flex-flow": ["flex-direction", "flex-wrap"],
-	background: [
-		"background-color",
-		"background-image",
-		"background-position",
-		"background-size",
-		"background-repeat"
-	],
-	font: [
-		"font-family",
-		"font-size",
-		"font-weight",
-		"line-height"
-	],
-	transition: [
-		"transition-property",
-		"transition-duration",
-		"transition-timing-function",
-		"transition-delay"
-	],
-	animation: [
-		"animation-name",
-		"animation-duration",
-		"animation-timing-function",
-		"animation-delay",
-		"animation-iteration-count"
-	],
-	grid: [
-		"grid-template-columns",
-		"grid-template-rows",
-		"grid-template-areas"
-	],
-	"grid-template": [
-		"grid-template-columns",
-		"grid-template-rows",
-		"grid-template-areas"
-	],
-	"grid-area": [
-		"grid-row-start",
-		"grid-column-start",
-		"grid-row-end",
-		"grid-column-end"
-	],
-	"place-content": ["align-content", "justify-content"],
-	"place-items": ["align-items", "justify-items"],
-	"place-self": ["align-self", "justify-self"],
-	"list-style": [
-		"list-style-type",
-		"list-style-position",
-		"list-style-image"
-	],
-	"text-decoration": [
-		"text-decoration-line",
-		"text-decoration-color",
-		"text-decoration-style"
-	],
-	outline: [
-		"outline-width",
-		"outline-style",
-		"outline-color"
-	],
-	columns: ["column-width", "column-count"],
-	overflow: ["overflow-x", "overflow-y"]
-};
-/** The atomic longhands to write instead of a compound shorthand, or undefined when the key is not a compound
-*  shorthand. `flex` layout in particular is NOT `display` + `flex-direction` (those are their own properties). */
-var compoundLonghands = (key) => Object.hasOwn(COMPOUND_SHORTHANDS, key) ? COMPOUND_SHORTHANDS[key] : void 0;
-var SIDES = [
-	"top",
-	"right",
-	"bottom",
-	"left"
-];
-var box4 = (tokens) => {
-	const [a, b = a, c = a, d = b] = tokens;
-	return [
-		a,
-		b,
-		c,
-		d
-	];
-};
-var radius4 = (tokens) => {
-	const [a, b = a, c = a, d = b] = tokens;
-	return [
-		a,
-		b,
-		c,
-		d
-	];
-};
-var BORDER_STYLES = /* @__PURE__ */ new Set([
-	"none",
-	"hidden",
-	"dotted",
-	"dashed",
-	"solid",
-	"double",
-	"groove",
-	"ridge",
-	"inset",
-	"outset"
-]);
-var BORDER_WIDTH_KEYWORDS = /* @__PURE__ */ new Set([
-	"thin",
-	"medium",
-	"thick"
-]);
-var LENGTH_RE = /^-?[\d.]+([a-z%]*)$/;
-var classifyBorderToken = (token) => {
-	if (BORDER_STYLES.has(token)) return "style";
-	if (BORDER_WIDTH_KEYWORDS.has(token) || LENGTH_RE.test(token)) return "width";
-	return "color";
-};
-var expandBorder = (key, value, out) => {
-	const sides = key === "border" ? SIDES : [key.slice(7)];
-	for (const token of splitTokens(value)) {
-		const kind = classifyBorderToken(token);
-		for (const side of sides) out[`border-${side}-${kind}`] = token;
-	}
-};
-var BORDER_SIDE_KEYS = new Set(SIDES.map((s) => `border-${s}`));
-var expandOne = (key, raw, out) => {
-	const value = String(raw);
-	if (key === "padding" || key === "margin" || key === "inset") {
-		const [t, r, b, l] = box4(splitTokens(value));
-		const prefix = key === "inset" ? "" : `${key}-`;
-		out[`${prefix}top`] = t;
-		out[`${prefix}right`] = r;
-		out[`${prefix}bottom`] = b;
-		out[`${prefix}left`] = l;
-		return true;
-	}
-	if (key === "border-radius" && !value.includes("/")) {
-		const [tl, tr, br, bl] = radius4(splitTokens(value));
-		const corners = [
-			["top-left", tl],
-			["top-right", tr],
-			["bottom-right", br],
-			["bottom-left", bl]
-		];
-		for (const [corner, v] of corners) out[`border-${corner}-radius`] = v;
-		return true;
-	}
-	if (key === "gap") {
-		const [row, col = row] = splitTokens(value);
-		out["row-gap"] = row;
-		out["column-gap"] = col;
-		return true;
-	}
-	if (key === "border" || BORDER_SIDE_KEYS.has(key)) {
-		expandBorder(key, value, out);
-		return true;
-	}
-	return false;
-};
-/** Expand supported CSS shorthands to their longhand keys. Explicit longhands in the same map win over any
-*  expansion (so `{ padding: 8, padding-left: 0 }` keeps padding-left: 0). Unrecognized keys pass through. */
-var expandShorthand = (css) => {
-	const expanded = {};
-	const direct = {};
-	for (const [key, value] of Object.entries(css)) if (!expandOne(key, value, expanded)) direct[key] = value;
-	return {
-		...expanded,
-		...direct
-	};
-};
-//#endregion
-export { COMPOUND_SHORTHANDS, compoundLonghands, cssProperties, expandShorthand, isCssProperty, suggestCssProperty };

package/dist/src/core/server/ssrServer.d.ts

@@ -1,2 +0,0 @@
-import { SSRServer, SSRServerConfig } from '@plitzi/sdk-shared';
-export declare const createSSRServer: (config: SSRServerConfig) => SSRServer;