@plitzi/sdk-mcp 0.38.10 → 0.38.12

package/CHANGELOG.md

@@ -1,5 +1,300 @@
 # @plitzi/sdk-mcp
 
+## 0.38.12
+
+### Patch Changes
+
+- 1301338: ## Builder
+
+  - **Icons in the canvas again** (`@plitzi/plitzi-builder`): the canvas inlined the SDK's Font Awesome sheet into its
+    `<style>`, where the sheet's `url(webfonts/…)` resolved against the editor's URL — a `srcdoc` frame takes it as its
+    base — so every icon was a 404 under `/spaces/<space>/webfonts/` and drew as an empty box. Only the Vite dev server,
+    which rewrites the URL, hid it. The canvas and the element preview now link the sheet from where the host serves it:
+    a new prop, `sdkIconsStylePath`, the one the host already gives the pages it renders
+    (`/sdk-assets/plitzi-sdk-icons.css` for sdk-server). Absent, the canvas links no icon sheet.
+
+  ## Plugins
+  - **A plugin's other elements, hosted by `custom`** (`@plitzi/sdk-elements`): `custom({ renderType: 'jamDisc' })` on a
+    space with a plugin installed whose main element is another (`plitzi plugin pack` of several folders: the first is the
+    plugin, the rest go in it) rendered "Custom Component jamDisc Not Found" — the page registers only the plugin's main
+    element, and a `custom` host looked nowhere else. It now loads the type from the installed plugin that packs it, as
+    an element of the type itself always did, so the two ways the docs give to place a plugin's element are the same
+    everywhere: in a project `plitzi create` wrote, and once the project is on Plitzi.
+  - **One way to place a plugin's element** (`@plitzi/sdk-authoring`, `@plitzi/cli`, docs): from its declaration,
+    `const seatPicker = defineElement(declaration)` then `seatPicker({ id, … })` — typed by what it
+    declares, and the element the builder adds when somebody drops it. The welcome space `plitzi create` writes, the
+    plugin package's preview, `plitzi plugin add` and `plitzi explain` all write it so (the template's
+    `PluginHostOptions` now takes the plugin's `type` and `declaration: { from, attributes? }`; `custom`/`element` hosting
+    is gone). `pluginFolders(folder)` (`@plitzi/sdk-authoring/node`) reads each plugin with the folder it is in;
+    `pluginDeclarations` is built on it. A `custom({ renderType })` naming a plugin the space was handed the declaration
+    of is offered the declaration instead — suggestion `plugin-custom-host`. `custom` stays for a component registered
+    by name with no declaration. The skills, the CLI README, the MCP guide, `docs/en` and the website say the same.
+  - **`definePlugin`** (`@plitzi/sdk-authoring/plugin`, a new entry of 3 KB with nothing else in it): a plugin's
+    declaration written from what only it can say —
+    `definePlugin<SeatPickerAttributes>()({ type, label, attributes, triggers, callbacks })` — and every other field
+    at the default all plugins share (the builder's gestures, the catalogue entry, each attribute bindable, an empty
+    style). It answers the whole declaration, branded with its attributes, so `defineElement(declaration)` is typed
+    without a generic. `plitzi plugin add` and `create --plugin` write declarations with it (about a third of the lines).
+  - **`usePluginTrigger(declaration)`** (`@plitzi/plitzi-sdk`): fires a plugin's declared event on its element — the
+    event name and what each hands a flow typed off the declaration's `preview` — on a live page only. The hook every
+    plugin wrote for itself (and `plugin add` generated as `use<Name>Events`) is gone from the scaffold.
+  - **Attributes as the types their defaults are** (`@plitzi/sdk-elements`): a plugin's attribute bound from text — a
+    state, a row, a channel message — reaches its component as the number or the flag its declared default is (`'112'`
+    as 112, `'true'` as true). A plugin no longer types its props `number | string` and parses them.
+
+  ## Server actions and functions
+  - **Task params with rules** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`): a task declares `required`, a text's
+    `maxLength` and a number's `min`/`max`, and the runner refuses a call that breaks any of them — every rule broken at
+    once, in the words the page shows (`Title is required; Seconds is at most 300`) — before the code runs. A `text` param
+    bound to a number arrives as its digits. The manifest keeps the rules, so the platform's sandbox checks the same.
+  - **`taskAction(task, { trigger })`** (`@plitzi/sdk-authoring`): the action that runs one of the space's tasks and
+    answers its result, derived from the task — its id (`<namespace>-<action>`), name, description and input (the task's
+    params, once). An action of more than one step is still `defineAction`.
+  - **`ctx.rateLimit(bucket, { …, refuse })`**: past the limit the call is refused with those words instead of answering
+    `allowed: false` for the code to check — natively and in the sandbox.
+
+  ## Authoring
+  - **`runServerActionOrNotify(id, params, fallback)`**: a server action run and the notice the visitor reads when it
+    fails — the action's own refusal, or the fallback — as two steps to spread into a flow.
+  - **`repeated-shape` reads what copies bind**: copies whose bindings read their data in different forms (a count, a
+    total of a quota) and copies holding a provider resolved on the server (found by its own id) are no longer offered
+    as one component.
+  - **`element-color-inherited`** (suggestion): `elements` giving a heading, a text, a link… `color: inherit` or the
+    page's own colour. **A link inherits the page's colour** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-elements`) rather than
+    holding the SDK's grey — the same by default, and the space's palette inside a card that is a link. The template
+    every space starts from writes its colours once, on the page.
+
+  ## Fixes
+  - **A dialog opened with an id** (`@plitzi/sdk-elements`): `openDialog('dialog', '{{ row.id }}')` reads the id as its
+    `content`, as `openModal` already did — a numeric id parsed as the number and the dialog's bindings read nothing.
+  - **A select's chevron** (`@plitzi/plitzi-sdk`): a drawn chevron in the field's own colour, sized by its type, in place
+    of the `▼` glyph — and laid out in the box, so it ends where the box's padding begins whatever that padding is, and
+    the chosen option stops short of it instead of running under it. A disabled select's is faded.
+  - **Every element has its settings** (`@plitzi/plitzi-builder`, `@plitzi/sdk-elements`): the builder found none for
+    `tabContainerHeader` (registered under a misspelt type), `themeToggle`, `dropdownPopup`, `loading` and `notFound`.
+    The theme toggle's panel sets its mode, its labels and whether it offers "System"; the registry is typed by element
+    type and must hold one for each.
+  - **A plugin's panel** (`@plitzi/cli`): `plitzi doctor` warns of a plugin with no `Settings.tsx`, or one its entry never
+    passes as `pluginSettings` (`plugin-settings-missing`); the example `create` writes has its panel, as every element
+    `plugin add` writes does, and the panels it generates are laid out as the project's Prettier lays them out.
+  - **A refused or failed run reaches `onFlowError` in every mode** (`@plitzi/sdk-interactions`): an awaited server
+    action the server refused fired no `onFlowError` on the element that started it, as `detached` and `stream` ones do
+    — a board rolling its edits back on a refusal never did; and a run answered `status: 'failed'` fired `onFlowEnd`
+    (detached) or nothing (awaited) rather than `onFlowError`.
+  - **A source renamed** (`@plitzi/sdk-shared`): the binding picker lists a provider, a form or a modal by the name its
+    element has now, not the one it had when it mounted.
+  - **A text's words in the builder** (`@plitzi/sdk-elements`): a `paragraph`, `text` or `heading` whose `content` is
+    `0` shows `0` while editing too, not its placeholder; one bound to nothing shows nothing rather than `null`.
+  - **Built-in declarations** (`@plitzi/sdk-shared`): `elementDeclaration` fills in what every element shares — the
+    builder's gestures, Plitzi's catalogue entry, a visible element with no bindings, its style named by its label —
+    from the defaults `definePlugin` uses; each element's declaration says only what is its own (a third of the lines).
+
+  ## Typed for plugins and hosts
+  - **`usePlitzi()` and `PlitziProvider`** (`@plitzi/sdk-shared/hooks/usePlitzi`, `@plitzi/plitzi-sdk`): what were
+    `usePlitziServiceContext()` and `PlitziServiceProvider` (and `PlitziServiceContextValue`, now `PlitziContextValue`),
+    holding only what the host rendering a space knows — `settings`, `root`, `utils`. Its `contexts` and
+    `customContexts` are gone: every context it carried is a shared one already, imported from its own module
+    (`@plitzi/sdk-interactions/InteractionsContext`, `@plitzi/sdk-shared/network/NetworkContext`…), and
+    `PluginsContext` moves to `@plitzi/sdk-shared/plugins/PluginsContext` beside the others.
+  - **`InteractionsManagerApi`** (`@plitzi/sdk-shared`): the interactions manager as everything outside
+    `@plitzi/sdk-interactions` reaches it, declared where every package can name it and implemented by
+    `InteractionsManager`, so `use(InteractionsContext)` is typed — `interactionTrigger`, `createChildManager`… — where it
+    was `any`.
+  - **`getPathsFromObject`** (`@plitzi/sdk-shared/helpers/utils`), spelt right; `getPathsFromObeject` is gone.
+  - **`ElementWords` places itself** (`@plitzi/sdk-elements`): `contentPlacement` and the element's children, so a button
+    and a link write their words once.
+
+- Updated dependencies [1301338]
+  - @plitzi/plitzi-sdk@0.38.12
+  - @plitzi/sdk-server@0.38.12
+  - @plitzi/sdk-authoring@0.38.12
+  - @plitzi/sdk-schema@0.38.12
+  - @plitzi/sdk-shared@0.38.12
+  - @plitzi/sdk-style@0.38.12
+
+## 0.38.11
+
+### Patch Changes
+
+- cadf70a: - **`server.cache.invalidate` drops what a page is rendered from** (`@plitzi/sdk-server`): the pages, the RSC answers
+  and the schema data they are rendered from go together. It dropped the pages alone, and the next request rendered
+  the same page again from the schema still cached under the same key — a publish that invalidated the space changed
+  nothing until the schema's TTL ran out. `clear()` and `size` cover the three. A filter on `hostname` drops the schema
+  data too, which belongs to no one host. `server.cache` is `null` only when nothing is cached (`cacheTtlMs: 0` and
+  `rsc.cacheTtlMs: 0`).
+
+  ## Style inspector
+  - **Finds a property** (`@plitzi/sdk-style`): a search above the categories narrows them to the ones that edit what was
+    typed — a CSS name in any order of its words (`border radius` finds the four corners), a category's title, or a
+    common word for it (`bg`, `rounded`) — opens them, and shows the advanced rows when the match lives there. Escape
+    clears it. The categories' properties live in one list (`categoryKeys.ts`) that the dots, the advanced hint and the
+    search all read.
+  - **Rows that fit**: a section with more than two controls puts its label above them and lays them out in as many
+    columns as the panel is wide, instead of one row where every label was cut (`Appearan…`, `Cell Spaci…`, the five
+    scroll-snap controls). A row's label column is 80px.
+  - **Where a value comes from, said quietly**: the label's tint keeps its four meanings — set here, from a token, bound
+    to data, inherited — without the solid blocks of colour; hovering says which (an inherited one names its selector and
+    breakpoint) and that a click resets it, the click shows it by striking the label through. The footer's info icon
+    holds the legend, and its arrow folds every category.
+  - **What is being edited**: an "Editing … › Hover" line under the pickers whenever the rules being written are not the
+    selector's plain ones, with a button back to them. Ancestor, pseudo-element and condition fold behind a toggle —
+    never while one is in use.
+  - The class being edited is the panel's one strong mark (violet), the element's type defaults a softer one; the tools'
+    tabs fit the panel and are reachable from the keyboard.
+
+  - **Lists edited in a popover, all alike**: box and text shadows, transforms, transitions and filters share one row
+    (the CSS it writes, a swatch, a remove button) and one popover (a title, a close button, Escape, the focus moved
+    into it). What none of them could read is now kept and edited as text instead of being replaced with a default — a
+    token for the whole value, `drop-shadow(…)`, `url(#…)`.
+  - **Values read the way CSS writes them**: a shadow with two, three or four lengths and its color on either end;
+    `rgba(…)` inside text shadows and filters no longer split; negative shadow offsets accepted; a transition with any
+    of its parts left out; brightness, contrast and saturation past 1. Transition presets are written as CSS — the
+    preset names (`easeInQuad`) made the browser drop the whole declaration — the curve can be dragged into one of your
+    own, and the preview stops with the editor. `font-color` (not CSS) became `color`.
+  - **Background layers keep what they hold**: a repeating gradient (now a switch), a radial gradient's explicit size, a
+    token or `image-set()` as a layer (a "Custom (CSS)" layer), a one-value position read as CSS reads it (`20%` is
+    `20% center`), lists shorter than the layers repeated as CSS repeats them, an unset repeat read as tiling, two-position
+    stops, negative angles — every one of them was rewritten on the next edit of any layer. Defaults are no longer
+    written back, and "Token values" no longer bakes resolved tokens into the layers.
+  - **A layer's editor in two halves** — what it draws, then where it goes (size, position, tile, attachment, clip,
+    which now offers `text`). The gradient's stops sit on one bar, each a handle that drags or moves with the arrow keys;
+    the stop's color and position below it. Previews and swatches resolve the space's tokens.
+  - Spacing tells margin (dashed, outside) from padding; Border's sides are labelled and readable in the dark theme; a
+    class's menu says what each action does to whom; the Style Manager opens at a size that holds both columns.
+
+  ## Builder
+  - **Shortcuts**: `?` shows every shortcut the builder answers to — the same list the "Nothing selected" card teaches
+    from — and ⌘\ / Ctrl+\ hides both side panels for the canvas alone and brings back the ones that were open. Both
+    work with the canvas focused.
+  - **Panels keep their width**: each side panel opens at the width it was left at; the right one starts at 380px.
+  - **Text no smaller than 11px** across the builder's panels (it went down to 10px in fifty places).
+
+  ## Realtime
+  - **A page hears what it sent when it asks to** (`@plitzi/sdk-shared`, `@plitzi/sdk-server`, `@plitzi/sdk-elements`):
+    `publishOn('room', 'react', data, { echo: true })`, `useChannel().publish(type, data, { echo: true })` and the
+    channel's `publish` callback (`echo`) hand the message back to the page that sent it too, once the server took it —
+    stamped like everyone's, with `echo: true`, its `from` the channel's `me`. Without it a page still never hears its
+    own messages, and the docs said "every page on its topic hears it": they now say every OTHER page. Presence never
+    echoes.
+  - **A topic is opened only once it names one** (`@plitzi/sdk-elements`): `useChannel` — and so the `channel` element —
+    opens a topic only when a channel of the space covers it, by the same `matchChannel` the server decides by. A topic
+    written from data that has not arrived (`room:` while its provider loads, or its template still as text) asked the
+    server for both, was refused with a 403 and a console error on every load, and is now waited for.
+  - **Pages that watch** (`@plitzi/sdk-server`, `@plitzi/cli`): a connection whose page carries the `plitzi-observer`
+    cookie hears its topics and says nothing on them — no `$join`, no presence, its publishes taken and dropped.
+    `page check`, `page shot` and `verify` load pages that way, so checking a live site is no longer a visitor walking
+    into a room (`X walked in`, a member more in every picture). `--presence` takes part as a visitor does.
+
+  ## Authoring
+  - **`template-in-value`** (refused): a `{{ }}` inside an attribute that is an object or a list — a provider's
+    `input`, a list's `items`, a plugin's settings — is never evaluated: only an attribute that is text is interpolated,
+    and the page server reads attributes as saved. A provider's `input` also replaced the route param of the same name
+    the action was already given, so `input: { room: '{{ navigation.routeParams.room }}' }` reached the task as `""` and
+    the page answered 404; its refusal says the action is handed the page's route and query params already. Anything
+    else is a binding on the attribute. `mockData`, a sample, is not held to it.
+  - **Rules on top of a class need no `id`** (`class: [card, { gap: '6px' }]`): they are named after the id the element
+    is given, written or not. `modifier-without-id` is gone; a one-off tweak no longer needs a name nothing reads.
+  - **Typed list rows have `inTemplate`**, as untyped ones do, and `bindTemplate`, `visibleWhen`, `hiddenWhen` and
+    `variantFrom` take a typed source's path as well as a name: turning a list typed broke every template of its rows.
+  - **`when({ field, operator: 'empty' })`** takes no `value` (nor `notEmpty`), as flows.md recommends; it did not
+    type-check.
+  - **Data-driven colours**: a style binding on a custom property (`{ to: '--who', category: 'style' }`) is written as
+    named — it was camel-cased into `who` — so a class reads `var(--who, var(--muted))`. A style binding's value carrying
+    `;` or braces is not written: the page server writes inline styles as text, and such a value added declarations of
+    its own. `binding-target-unknown` on `style` or a CSS property says to bind it in the `style` category.
+  - `unknown-attribute` for `decorative` on an `svg` or a `fontAwesome` says what it means: without a `label` it is
+    already hidden from screen readers.
+
+  - **A folder nobody declared says where to declare it**: `folder-undeclared` (a page, a layout, a folder's parent)
+    ends with `pageFolders: [{ id, name }]` on the space, and with the line of the `pageFamily` that wrote the page. A
+    folder starts its pages' addresses (`/docs/quickstart`), so a misspelt one is never declared on the author's behalf.
+    The skill's `pageFamily` example declares its folder.
+  - **A tag is an element**: a `subType` this element has not but another has — `container({ subType: 'ol' })` — names
+    that element (`list({ subType: 'ol' })`) instead of the value two letters away (`dl`). Read off the elements'
+    declarations, for every element and tag.
+  - **A `pageFamily`'s body is written once**: `repeated-shape` and `repeated-on-pages` no longer count the same part of
+    each page of one family as copies — they were offering a component for exactly what the docs recommend. Copies within
+    one page, or across pages written one by one, are still offered.
+  - **Colour emoji are not text to `page check`**: a character painted in its own colours (🎲, `❤️`, a keycap, a ZWJ
+    sequence) is left out of the contrast measure, which compared `color` with the tile behind it and failed `verify`
+    in the theme whose text colour was close to the tile. A symbol drawn as text (✓, ★) is still measured.
+
+  - **`declared-callback-target`** (refused): a value beside `on` in `declaredCallback(…, { on, date })` — written as
+    `openModal`'s target reads — was read nowhere, and the step ran without it. Refused, with the `params` it goes in
+    (`{ on: 'calendar', params: { date } }`) and whether it is one of the callback's declared params.
+  - The skill's list rows show the typed form beside the untyped one: with `items` typed by a sample, `r.item` is a path
+    (`from: r.item.title`), not text to put in a template string.
+  - **`slot-not-class`** (refused): rules written in place in a slot — `slots: { error: [fieldError, { color }] }`, past
+    the type in JavaScript or a spec rebuilt from JSON — were taken for a declaration with no rules, and `authorSpace`
+    failed later with `Cannot read properties of undefined (reading 'desktop')`, naming nothing. Refused where the slot
+    is written, naming the slot and the element, with the `styles()` declaration to hand instead.
+
+  ## CLI
+  - **`page shot --click` (and `--clip`, `--wait-for`, `--scroll-to`, `--steps`) takes any selector**: a value that is
+    not an element's name (letters, digits, `-`, `_`) is a selector, CSS or Playwright's own (`button:has-text("Orbit")`).
+    It was wrapped as a name, and an invalid selector ended the command with Playwright's stack trace; it is now refused
+    with the reason.
+
+  - **`plitzi functions add <package>`**: a package the functions use comes with them, as a function carries its
+    dependencies. Installed in the project, it is bundled (web APIs only, minified, its licence kept) into
+    `src/functions/vendor/<package>.js`, with a `.d.ts` re-exporting the installed package's types, imported as
+    `./vendor/<package>.js` and pushed, built and run with the rest — nothing is resolved anywhere else, so the builder,
+    the sandbox and the push are unchanged. A package that reaches Node (`fs`, `node:*`) is refused, naming what it
+    reached; one past the functions' 1 MB is too; one that reads `process`/`Buffer` is warned about. The build's refusal
+    of a package import now names the command.
+  - **`page shot` targets**: a bare word is an element's name, or — no element named so — a tag (`textarea`); resolved on
+    the loaded page for `--click`, `--clip`, `--scroll-to`, `--wait-for` and `--steps`. In `--steps`, `type` takes a
+    quoted element with spaces (`type ".panel textarea" hola`) — it was cut at its first space and typed the rest — and
+    fails when the click leaves no field focused, rather than sending the keys to the page's shortcuts.
+
+  ## Server
+  - **`server.listen()` resolves once the port answers** (`@plitzi/sdk-server`) — in a fleet, once the first worker
+    does. `serveProject` writes `tmp/dev-server.json` and says `pages on …` after it, not on the line after `listen`:
+    for about 0.4 s a tool trusting the line (CI, Playwright's `webServer`, `page check`) was refused. A port it cannot
+    take still ends the process, or goes to `onListenError`, and the promise is then never resolved.
+  - **Runs set for later** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`, `@plitzi/sdk-authoring`, `@plitzi/plitzi-builder`):
+    a turn that runs out, a bot's move, a hold that lapses — one run starting one of the space's actions in N seconds,
+    whether or not a page is still open. The action says it may be with a **`later` trigger** (no access rule: the run
+    that set it was let in); a flow sets it with `flow.later { action, in, input, key }`, a function with
+    `ctx.later({ … })`, and `flow.cancelLater` / `ctx.cancelLater(key)` drops it. A `key` names it: set again under the
+    same key, the one still waiting is replaced — the newer of two set at once, on every replica — and a running one is
+    left. It is a job of the queue schedules use: due by the store's clock (0 s to 30 days, about a second late at most),
+    once across replicas, retried, shown in Automations → Queue. Refused before anything is queued, with why: no `later`
+    trigger, one switched off, a time out of range, a key that is not one, a server with no jobs. A plugin's functions
+    set none. `ActionJobQueue` gains `cancelPending({ spaceId, key, olderThan? })` and jobs a `key`: the memory, Mongo
+    and MySQL queues implement it, and the shared contract tests it. **MySQL**: `action_jobs` gains `job_key` (and the
+    `action_jobs_key` index), added on first use; with `createTables: false`, run that statement of
+    `mysqlJobSchemaUpgrades()`. A queue of a deployment's own implements `cancelPending` (`09-schedules` shows one).
+  - **A project's `kv` file has one holder** (`@plitzi/sdk-server`): `createFileKv` takes `<file>.lock` with its pid;
+    a second process — another `npm start`, a `--watch` left running — is refused, naming the first (`the server of
+"orbita", on port 8080`) instead of both writing their whole map over each other's changes, and a lock whose process
+    is gone is taken over. `close()` writes what is pending and lets go. A server with `workers` opens the file once, in
+    the primary, and its workers reach it through the fleet (`fleetKv`): each used to open a copy of its own.
+  - **A self-hosted project's credentials** (`@plitzi/sdk-server`, `@plitzi/cli`): `serveProject` answers
+    `getCredential` from `PLITZI_CREDENTIALS` in `.env` — one JSON object, credential id → its keys — so
+    `ctx.fetch({ credential })`, a connector and an `http.request` step work on the project's own server, not only in
+    `functions dev`. The same variable for both (it was `PLITZI_FUNCTIONS_CREDENTIALS`, read by the CLI alone); a value
+    that is not that object is refused with how to write it, instead of every credential going missing.
+  - **`HOST` beyond loopback says where to open it**: with `HOST=0.0.0.0`, `serveProject` prints the machine's network
+    addresses — what a tablet on the same Wi-Fi opens — and that anyone on that network can. `.env.example` names `HOST`
+    and `PLITZI_CREDENTIALS`.
+
+  ## SDK
+  - **`useElementSize(ref)`** (`@plitzi/plitzi-sdk`): the size a plugin's own box is drawn at, followed as it changes —
+    what `useDisplayMode()` cannot say: a tablet held upright is `mobile` by the window and still a week wide by the
+    plugin's box. `undefined` until measured, so the server's page and the hydrated one agree. The breakpoints are
+    unchanged.
+  - The functions docs say how a task's `params` types (how the builder edits them: `codemirror-json`) and an action's
+    `input` types (what the value is: `json`) correspond.
+
+- Updated dependencies [cadf70a]
+  - @plitzi/plitzi-sdk@0.38.11
+  - @plitzi/sdk-server@0.38.11
+  - @plitzi/sdk-authoring@0.38.11
+  - @plitzi/sdk-schema@0.38.11
+  - @plitzi/sdk-shared@0.38.11
+  - @plitzi/sdk-style@0.38.11
+
 ## 0.38.10
 
 ### Patch Changes

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

@@ -132,7 +132,8 @@ Never download a whole tree you do not need.
 - \`plitzi://types\` — element types **observed in this space** (ground truth): props, slots, subTypes, plus each
   type's \`label\`, \`description\` (what it is FOR) and \`category\`, and a \`source\` (\`builtin\` | \`plugin\` | \`unknown\`).
   Read the descriptions to pick the right type — e.g. \`apiContainer\` fetches backend data into the frontend,
-  \`link\` navigates between pages, \`list\` repeats a template over a data array. \`plugin\` types are custom elements.
+  \`link\` navigates between pages, \`list\` repeats a template over a data array. \`plugin\` types are the elements
+  of the plugins the space installed: added by their type, like a built-in.
 - \`plitzi://css-properties\` — valid kebab-case CSS property keys.
 - \`plitzi://explain/{name}\` — what a name means: an element type's attributes, triggers and callbacks; a step's
   params and what it publishes; what a trigger hands its flow; a problem code's fix. \`plitzi://explain/steps\` (or
@@ -258,8 +259,8 @@ space already had is not repeated on every batch — and none of them blocks any
   page being shown: the \`current\` state marks it (see *Pages & folders*).
 - \`repeated-shape\` — one structure written again with other words: a **component** with props
   (\`upsertComponent { fromRef }\` turns one copy into it), or, for sibling rows of data, one \`repeatElement\`/\`list\`.
-  A few cards a person rewords by hand can stay cards; siblings that read different data or keep different state are
-  controls written alike, and are not offered.
+  A few cards a person rewords by hand can stay cards; siblings that bind different data, keep different state, fill
+  from a template of their own or render on the server are controls written alike, and are not offered.
 - \`content-attribute\` — a \`button\` or \`link\` whose children are only a \`text\` and/or a \`fontAwesome\`: its words
   are its own \`content\` and the icon its \`icon\`. What the text's class adds (\`white-space: nowrap\`) moves to the
   box's class — never the class itself; the icon's class goes in the \`icon\` slot.
@@ -270,6 +271,8 @@ space already had is not repeated on every batch — and none of them blocks any
 - \`unused-class\`, \`unused-token\`, \`unused-component\` — declared and read by nothing: remove it
   (\`deleteDefinition\`, \`deleteStyleVariable\`, \`deleteComponent\`), or use it where it was meant to go. Said
   when a batch leaves one behind.
+- \`element-color-inherited\` — the space's \`elements\` giving a type \`color: inherit\` or the page's own colour,
+  which every element — a link's words included — takes by itself: remove it, and name the colour once on the page.
 - \`literal-colour\` — a class painted from the palette typing out a token's light value: \`var(--token)\` when it
   should follow the scheme; a token of one value when it must stay the same in both.
 \`plitzi://explain/<code>\` explains each. Take one unless the copies are about to diverge; one left on purpose is

package/dist/modules/mcp/server.js

@@ -72,7 +72,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.38.10"
+		version: "0.38.12"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	const { getChanges } = adapters;
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace, getChanges ? (query) => getChanges(requireSpaceId(), MCP_ENV, query) : void 0);

package/dist/modules/mcp/tools/operations/actions/document.js

@@ -21,7 +21,7 @@ var actionTriggerParams = z.object({
 		"public",
 		"session",
 		"role"
-	]).optional().describe("Who may start a run THIS way. Required for every kind but schedule, which has no caller"),
+	]).optional().describe("Who may start a run THIS way — required, except on schedule and later (no caller)"),
 	permissions: z.string().optional().describe("Comma separated; only for access \"role\""),
 	input: z.string().optional().describe("JSON map of ActionField by name: what a caller may send this way. Undeclared keys are DROPPED"),
 	signatureCredential: z.string().optional().describe("webhook only: the credential holding the signing secret. NAMING it is what turns verification on; without it anyone who learns the URL can start a run"),
@@ -55,7 +55,7 @@ var actionNode = z.object({
 	id: z.string(),
 	title: z.string(),
 	type: z.enum(["trigger", "task"]).describe("A trigger heads a chain; the rest are tasks"),
-	action: z.string().describe("A trigger names its KIND — call | webhook | schedule | render | custom — and one action may have several, one per kind, each heading its own chain. A task names \"<namespace>.<action>\" from plitzi://actions/{env}/tasks. A browser step (setState, navigate) cannot run here"),
+	action: z.string().describe("A trigger names its KIND — call | webhook | schedule | later | render | custom — and one action may have several, one per kind, each heading a chain. A task names \"<namespace>.<action>\" from plitzi://actions/{env}/tasks. A browser step (setState, navigate) cannot run here"),
 	params: z.record(z.string(), z.unknown()).default({}).describe("A task: that task's params. A trigger: ActionTriggerParams — access, input, signature*, cron"),
 	afterNode: z.string().default("").describe("Id of the next step; empty ends the chain"),
 	beforeNode: z.string().default(""),

package/package.json

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