Pro module36 abilities

Mosaic

These abilities register when Mosaic is detected on the site and a Pro licence is active. If either is missing the module stays absent rather than failing at call time.

At a glance

Mosaic registers 36 abilities: 16 that only read, 13 that write, and 7 marked destructive. That split is the practical answer to how much of this module can run unattended. Reads cost nothing and are safe to repeat, so discovery is the part to be generous with; the writes are where review belongs, and the destructive calls stop for an explicit confirmation every single time regardless of which profile is active.

What this module is for

Work with Mosaic elements, components, templates, collections, variables, utility classes, theme settings, and template assignments through WPPilot Pro.

Before you rely on it: Prefer reusable variables and utilities over one-off overrides, and review template assignment scope.

Typical workflows

Check the design system before adding a new utility
Build a collection-backed template
Apply a component override without changing the source component

The Mosaic integration page covers the same module from the workflow side, with the capability map and the questions worth asking before a first write.

Availability on your site

The Mosaic module needs three things at once: WPPilot Free as the MCP foundation, an active Pro licence, and the companion plugin detected on the site. Miss any one and the module does not register, which is deliberate: an ability that appears in the tool list but fails at call time is worse than an ability that was never offered. What the connected agent can actually call is then narrowed twice more: by the safety profile active on the site, and by the WordPress capabilities of the user behind the credential. A read that succeeds for an administrator can be absent entirely for an editor.

Every write these abilities perform is recorded in the change ledger, and destructive calls can be routed through the approval queue so a person signs off before anything is applied. A successful tool result means the operation returned, not that the front end, the cache, and every dependent template are correct: that still needs a look.

Reads

Available in every safety profile, including Read Only. Inspection costs nothing and is not rate limited.

Ability	What it does
`wppilot/mosaic-check-design-system`Check Mosaic Design-System Compliance	Audits every element of a Mosaic document for design-system compliance — i.e. whether the page styles itself with Mosaic's OWN design system (utility classes + theme variables) rather than custom CSS baked in from outside it. It flags any element whose inline `style` hardcodes a colour (`#hex`, `rgb()`, `hsl()`) or a `font-family` literal instead of referencing a theme variable (`var(--token)`) or a utility class. Returns a COMPACT report: summary counts (total / compliant / flagged nodes, how many elements use utility classes or variable refs, a count per violation type) plus the list of FLAGGED nodes only — each with its id, element type, the offending inline style (truncated) and the violations — so an agent can fix them: replace the literal with a `var(--token)` (discover them via mosaic-list-variables) or move the rule into a utility class (mosaic-create-utility-class + the `class_names` shortcut). Compliant nodes are summarised, not listed, to keep the response small. Read-only. Run it after building or editing a page to self-check — this is the styling the Mosaic editor (and the customer) expects, instead of un-editable custom CSS.
`wppilot/mosaic-check-legacy-data`Check Mosaic Legacy Data	Dry-run report for legacy empty JSON values that can conflict with Mosaic record types. This ability never writes.
`wppilot/mosaic-check-setup`Check Mosaic Setup	Returns the Mosaic Pro runtime state in one call. Use this BEFORE any other Mosaic ability. Surfaces whether the plugin is active, its version, the supported version band (min_supported inclusive, max_supported exclusive — Mosaic at or above max is rejected), whether the active version sits inside the band (min_satisfied + max_satisfied), the edition (free / pro), the distribution channel (stable / beta / dev), whether the custom tables have been provisioned, and counts of the four top-level entities (themes, templates, components, collections). Every other Mosaic call is gated on `plugin.runtime_ready` (the AND of active + version-band + class + tables). A handful of advanced operations additionally require `plugin.edition=pro`.
`wppilot/mosaic-get-collection`Get Mosaic Collection	Returns one Mosaic collection by id, including the full decoded `data` blob. Collections are the design-token BUCKETS that hold variables — typically one per family (e.g. "Brand colors", "Spacings", "Typography"). The compact list lives at mosaic-list-collections; this ability returns the full record `{id, theme_id, ordering, status, revision, name, data}`.
`wppilot/mosaic-get-element-tree`Get Mosaic Element Tree	Returns every published node of a Mosaic document (template / component / master / styleGuide) as a flat list AND as a hierarchical tree. Each node carries id, type (the element-widget identifier such as `section`, `div`, `text`, `button`), theme_id, document_type, document_id, parent_type (the literal `node` for inner nodes or the document_type for root nodes), parent_id (a node id, or the document_id for root nodes), ordering (a fractional-index string), status, and the decoded `data` blob (element settings). Size discipline: `max_nodes` caps the row count (default 500, hard cap 5000) — rows are fetched in BFS order from the document root, so truncation always trims the deepest layer first and the hierarchical `roots` view stays coherent; `max_field_bytes` caps per-node `data` size (default 4096, blobs above the cap become `{_truncated: true, _bytes: <orig>}`); `max_depth` caps hierarchical recursion in `roots` (default 64, descendants past the cap drop and the parent gets `children_truncated: true`). When the row count cap fires, `truncated = true` and the deepest descendants are silently omitted from both views.
`wppilot/mosaic-get-template`Get Mosaic Template	Reads a single Mosaic template by id. Returns id, name, theme_id, master_id, assign (`auto` or `manual`), path, ordering, status (`publish`), version, revision, modified_gmt, and the decoded `conditions` JSON (visibility rules controlling which front-end pages the template applies to; an empty rule set decodes to `[]`). The element tree itself lives in the `nodes` table — call mosaic-get-element-tree (Sprint 3) for the canvas contents. Returns mo_not_found for missing or soft-deleted templates.
`wppilot/mosaic-get-theme`Get Mosaic Theme	Reads a single Mosaic theme by id. Returns id, name, version, revision, ordering, status (`publish`), modified_gmt, and the full decoded `data` blob (settings, metadata, internal flags). Returns mo_not_found when the id is missing or the row has been soft-deleted (status = `delete`).
`wppilot/mosaic-get-theme-settings`Get Mosaic Theme Settings	Returns the global settings stored under a Mosaic theme's `data.settings` sub-key. These are the theme-wide preferences Mosaic's admin Settings panel writes — typically container width, default font stack, breakpoint definitions, page-transition defaults, dark-mode toggle, code-injection slots. The settings shape is theme-defined; on a freshly wizard-seeded theme the value is `null` (Mosaic falls back to built-in defaults). Returns `{theme_id, settings}` where `settings` is either `null` or the decoded object. Use mosaic-edit-theme-settings to merge or replace.
`wppilot/mosaic-get-utility-class`Get Mosaic Utility Class	Returns the full decoded record for one Mosaic utility class, including the structured per-state / per-breakpoint CSS payload under `data.states`. Use this when mosaic-list-utility-classes' compact summary is not enough — typically when reading the rules a designer set in Mosaic's editor before applying that class to elements. Returns `{utility_class}` where `utility_class` carries `id, theme_id, ordering, status, revision, name, css_class, is_excluded, favored_element_classes, data}` (data is the raw decoded blob with `states`, `localStates`, `interactions`).
`wppilot/mosaic-list-collections`List Mosaic Collections	Lists Mosaic design-token collections under a theme. A collection groups variables / modes / skins together — e.g. a "Brand Colors" collection holds color variables across light + dark modes. Summary per collection: id, themeID, parent_id, parent_type, ordering, status, plus the decoded `data` blob (collection name + metadata).
`wppilot/mosaic-list-components`List Mosaic Components	Lists Mosaic components (reusable element subtrees) under a theme, optionally filtered to one component category. Components are the building blocks an agent picks from to compose pages: buttons, cards, hero sections, navigation menus, footer rows. Summary per component: id, theme_id, name, path, parent_id, parent_type (typically `componentCategory`), ordering, status (`publish` or `delete`).
`wppilot/mosaic-list-template-assigns`List Mosaic Template Assigns	Lists template-assignment bindings under a theme. Each binding maps a (post-type slug, post ID) pair to a Mosaic template — Mosaic 1.0.3 only reads this table for single-post bindings (e.g. `type = "page"` + `type_identifier = "42"`). Other content surfaces (archives, taxonomies, search, 404, front page) are matched via the template's `conditions` JSON at render time, not via this table. Each record carries theme_id, type, type_identifier, template_id, and parent_type (always `template`).
`wppilot/mosaic-list-templates`List Mosaic Templates	Lists templates under a specific Mosaic theme (templates are theme-scoped, so `theme_id` is required). Compact summary per template: id, name, theme_id, master_id, assign (one of `auto`/`manual`), path, ordering, status (`publish` or `delete`), modified_gmt. The `conditions` longtext is NOT in the summary; call mosaic-get-template for the full record including the visibility rules.
`wppilot/mosaic-list-themes`List Mosaic Themes	Lists every Mosaic theme on the install. Mosaic stores themes in the `<prefix>mosaic_themes` table (NOT WP themes — Mosaic is its own theme system); each theme owns its templates, components, collections, and design-system records. Compact summary per theme — id, name, version, ordering, status, modified_gmt. Call mosaic-get-theme for the full data blob.
`wppilot/mosaic-list-utility-classes`List Mosaic Utility Classes	Lists Mosaic utility classes (Tailwind-style atomic CSS classes such as `u-padding-md` or `u-text-center`) under a theme. Agents pick these to apply quick styling to elements without creating a new element class. Compact summary per record: id, theme_id, ordering, status (`publish`), name, css_class. The full `data` blob (with `isExcluded`, `favoredElementClasses`, and the per-state styling payload under `states` / `localStates` / `interactions`) is omitted from the list to keep responses small; use `mosaic-get-utility-class` for the full record.
`wppilot/mosaic-list-variables`List Mosaic Collection Variables	Lists design-token variables under a Mosaic collection. Variables are the atomic design tokens (colors, font sizes, spacings, radii, shadows) that components reference via the CSS custom property declared in `data.customProperty` (NOT the row id). Compact summary per variable: id, theme_id, collection_id, ordering, status (`publish`), name, custom_property. The full `data` blob (with `usage`, `propertyGroups`, `skinsData`) is omitted from the list to keep responses small even on Figma-imported design systems with 5000+ variables; use `mosaic-get-variable` for the full record. Scope by `collection_id` (required, get one from mosaic-list-collections); optionally filter by theme_id for an additional safety check.

Writes

Gated by the active profile and your WordPress capabilities. Rate limited to 120 per minute per credential.

Ability	What it does
`wppilot/mosaic-add-element`Add Mosaic Element	Inserts a new element node into a Mosaic document (template / component / master / styleGuide). Position with `placement` = `at_end` (default), `at_start`, `before` (requires `anchor_id`), or `after` (requires `anchor_id`). The new node gets a generated UUID and a fractional-index `ordering` that sorts correctly between siblings. The `data` blob is element-type-specific (see Mosaic NodeTypes source for the shape per element-type). Returns the full presented node so the caller knows the assigned id. Auto-routing: passing `parent_id = document_id` on a template silently nests the new node under the template-internal canvas wrapper so Mosaic's renderer picks it up — adding directly under the template document would orphan the content. Text elements are WYSIWYG holders: `type=text` produces a container, the visible string lives in a child `type=wysiwyg-text` node with `data={text:"..."}` — add both to make text reach the rendered HTML.
`wppilot/mosaic-create-collection`Create Mosaic Collection	Creates a new Mosaic collection under a theme. Routes through `CollectionsMResourceManager::restoreCollectionMResource` so the row carries valid ordering, defaults, and revision UUID. Use a collection per design-token family (e.g. "Brand colors", "Spacings"); variables created later with mosaic-create-variable nest under one. Returns the new collection record.
`wppilot/mosaic-create-template`Create Mosaic Template	Creates a brand-new Mosaic template that is fully renderable: the row is wired into Mosaic's MResource graph via the wizard's own facade (master linkage + root `template-internal` node), so the Mosaic editor opens it cleanly and the front-end renderer can paint it. Required: theme_id, name. Optional: assign (`auto` / `manual`, defaults to `manual`), path (defaults to `index.php`), conditions (only honored when `assign=auto`; defaults to `[]` which under `auto` would match every front-end page, so leave empty when assign=manual). The template starts with a `template-internal` root (Mosaic's canvas wrapper) but no inner section — call mosaic-add-element with parent_id = the new template_id to seed real content. The Mosaic wizard facade resets `path` to `index.php` regardless of the value supplied (Mosaic resolves path against a registered TemplatePath enum at render time, not as a filesystem path) — leave it default unless you have a registered TemplatePath ID to point at. Returns `{ template: {...} }` with id, name, theme_id, master_id (auto-resolved to the theme's first master), assign, path, ordering, status (`publish`), version, revision, modified_gmt, conditions.
`wppilot/mosaic-create-utility-class`Create Mosaic Utility Class	Creates a new Mosaic utility class under a theme. Routes through Mosaic's `UtilityClassesMResourceManager::restoreUtilityClassMResource` facade — same code path the editor uses — so the row carries valid ordering, defaults, and revision UUID for Mosaic's renderer to pick up. The agent supplies `name` (display label) and `css_class` (the actual class name applied to HTML, must match `^[a-zA-Z_][a-zA-Z0-9_-]*$`). Add per-state / per-breakpoint CSS afterward with `mosaic-set-utility-class-style`. Returns the new utility class record (use `mosaic-apply` shortcuts on add/edit-element to attach it to elements).
`wppilot/mosaic-edit-collection`Edit Mosaic Collection	Renames an existing Mosaic collection. Optimistic-concurrency guarded — if the row was modified by another writer between this call's load and the UPDATE, returns `mo_concurrent_modification`.
`wppilot/mosaic-edit-component-instance-override`Edit Mosaic Component-Instance Override	Overrides one or more properties of a single node ON ONE INSTANCE of a shared Mosaic component, without touching the shared component definition or any other instance. `instance_id` is the visible `component-instance/<uuid>` node in the host document (template / master / styleGuide / another component); `original_node_id` is the UUID of the node INSIDE that shared component (or a component nested inside it) whose property you want to change locally. Pass the new values via `data` (Mosaic-native shape) and/or the `style` / `attributes` / `class_names` shortcuts — same shapes as mosaic-edit-element. The call creates the underlying override row the first time it targets a given `original_node_id`, and merges onto it (preserving properties you do not send) on every call after that — safe to call repeatedly. Properties you never override keep inheriting live from the shared component.
`wppilot/mosaic-edit-element`Edit Mosaic Element	Updates the `data` blob of an existing Mosaic node. The merge strategy is `merge` by default — a shallow array-merge of your supplied keys onto the existing blob, so keys you do NOT send (the element's classes, children, other attributes, content) are PRESERVED. Pass `mode = replace` for a full overwrite (your supplied data becomes the new blob verbatim — use this only when you are sending the complete blob, e.g. to also DROP keys). Nested keys are not deep-merged, and the top-level `style`/`attributes`/`class_names` shortcuts each rebuild their whole key. Returns the updated node. Use mosaic-move-element for re-parenting and re-ordering, NOT this ability.
`wppilot/mosaic-edit-template`Edit Mosaic Template	Updates an existing Mosaic template by id. Supports patching name, assign (auto/manual), path, and conditions; pass only the fields you want to change. Conditions: see mosaic-create-template for the wire shape — a JSON ARRAY of OR-groups using a fixed `ruleID` vocabulary; only honored when `assign=auto`. The element tree is NOT touched (use mosaic-add/edit/delete-element). Returns the updated template.
`wppilot/mosaic-edit-theme-settings`Edit Mosaic Theme Settings	Updates the global theme settings stored under a Mosaic theme's `data.settings` sub-key. Two modes: `merge` (default) — a shallow array-merge against the existing settings, so keys you do NOT send (e.g. the default font stack, breakpoints) are PRESERVED; `replace` — the supplied `settings` object becomes the new value verbatim, OVERWRITING everything (use only when sending the complete settings object). Nested keys are not deep-merged. Pass `settings = null` with `mode = replace` to clear settings back to Mosaic defaults. Optimistic concurrency: if the theme row was modified by another writer (Mosaic editor save on a parallel connection) between this call's load and the UPDATE, returns `mo_concurrent_modification` — re-fetch via mosaic-get-theme-settings and retry. The settings shape is theme-defined; for known Mosaic 1.0.3 surfaces see the admin Settings panel.
`wppilot/mosaic-edit-utility-class`Edit Mosaic Utility Class	Updates the identity fields of an existing Mosaic utility class. Editable: `name`, `css_class`. The structured CSS payload (`data.states`, `data.localStates`, `data.interactions`) is preserved verbatim — this ability only touches the agent-writable surface. Optimistic concurrency: if the row was modified by another writer (Mosaic editor save on a parallel connection) between this call's load and the UPDATE, returns `mo_concurrent_modification`. Renaming `css_class` does NOT rewrite element references — elements that already apply the old name will continue to reference the old name (Mosaic resolves by `cssClass` string, not by uuid for legacy compat).
`wppilot/mosaic-move-element`Move Mosaic Element	Re-parents and/or re-orders a Mosaic node within the same document. Pass `parent_id` to re-parent (a node id to move under, or the document_id to make it a root); pass `placement` = `at_end` / `at_start` / `before` (with `anchor_id`) / `after` (with `anchor_id`) to position it. The node's subtree moves with it (children keep their relative orderings). Returns `{ node: {...} }` with the updated node. Cross-document moves are not supported: the move always stays inside the node's original document, so passing a parent_id from a different document returns mo_not_found.
`wppilot/mosaic-set-template-assign`Set Mosaic Template Assign	Binds a single post to a Mosaic template at render time (Mosaic's "manual template assignment" feature). Wire shape: `type` is Mosaic's INTERNAL resource type — for singular post bindings always pass the literal string `"post"`, regardless of WP's post-type slug (page, post, custom CPT all share resource type `"post"` in Mosaic 1.0.3). `type_identifier` is the numeric post ID as a string. The template the agent binds also needs `path` to match Mosaic's renderer expectation for the WP request type — call `mosaic-edit-template(id, path="single-page.php")` for page posts, `path="single-post.php"` for blog posts, or `path="single-<cpt-slug>.php"` for custom post types. The template the wizard facade creates carries `path=index.php` by default which only renders for front-page / index requests. Other content surfaces (archives, taxonomies, search, 404, front page) are matched via the template's `conditions` JSON instead of this table — use mosaic-edit-template to set `conditions` for those. Calling with the same triple replaces any existing binding (PUT-style, idempotent). Field length caps: `type` ≤ 36 chars, `type_identifier` ≤ 100 chars. Returns the binding: theme_id, type, type_identifier, template_id, parent_type (always `template`).
`wppilot/mosaic-set-utility-class-style`Set Mosaic Utility Class State Style	Sets one validated CSS property on one state and breakpoint of an existing Mosaic utility class. The value is merged into `data.states[state][breakpoint_id]`; unrelated states, breakpoints, and properties are preserved. `state` defaults to `hover` and accepts Mosaic state IDs (`normal` aliases `&`). `breakpoint_id` accepts a Mosaic breakpoint UUID or `base`, `tablet`, `mobile` aliases. `property` accepts Mosaic's camelCase key or its CSS kebab-case form. The write goes through Mosaic's own style validator and resource facade, never direct SQL.

Destructive

Marked destructive in the source, so each call needs an explicit confirmation flag, every time.

Ability	What it does
`wppilot/mosaic-clear-component-instance-override`Clear Mosaic Component-Instance Override	Removes a component-instance property override entirely — the instance reverts to fully inheriting `original_node_id`'s value from the shared component. Does NOT touch the shared component definition or any other override on the same instance. Safe to call when no override exists (no-op, `cleared: false`, not an error).
`wppilot/mosaic-clear-template-assign`Clear Mosaic Template Assign	Removes a (theme_id, type, type_identifier) binding. Hard-delete: the row is removed from `wp_mosaic_template_assigns` entirely (this table is not soft-deletable). Returns `deleted: true` whether or not a binding existed (idempotent). All three fields are required to scope the delete to the exact row mosaic-set-template-assign would have written — passing only two fields would match every binding under that pair.
`wppilot/mosaic-delete-collection`Delete Mosaic Collection	Soft-deletes a Mosaic collection (status=delete). Variables under the collection are NOT cascade-deleted — they remain in `wp_mosaic_collection_variables` with `parentID` pointing at the dead collection. To fully retire a collection, delete its variables first via mosaic-delete-variable. Returns `{id, deleted}`.
`wppilot/mosaic-delete-element`Delete Mosaic Element	Soft-deletes a Mosaic node and every descendant: their `status` flips to `delete`. The rows stay in the table and can be resurrected manually via direct SQL, but they are hidden from every read ability and from Mosaic's own renderer. Returns the count of nodes that flipped status. Cross-document stale-ref note: deleting a node inside a Component document (documentType=`component`) does NOT cascade to `component-instance` nodes in other templates that reference it — Mosaic's renderer falls back to silent empty render for an unresolved instance, and CSS variable refs (`{var: <uuid>}`) emit `var(--unknown-variable)`. Both fallbacks are by Mosaic's design, but the agent should expect visible gaps on the front-end until the orphan instances are removed too.
`wppilot/mosaic-delete-template`Delete Mosaic Template	Soft-deletes a Mosaic template by id (status flips to `delete`). The element tree is left untouched — re-publishing the template directly via SQL would restore the canvas as it was. Returns the deleted template id.
`wppilot/mosaic-delete-utility-class`Delete Mosaic Utility Class	Soft-deletes a Mosaic utility class — the row stays in the table with `status=delete` and disappears from every read ability + from Mosaic's editor. Element references to the underlying `cssClass` string are NOT scrubbed: elements still emit the class on the rendered HTML, but no CSS rules will match (the class definition is gone). To fully retire a utility class, edit each referencing element to drop it from `cssClasses` before calling delete. Returns `{id, deleted: true}`.
`wppilot/mosaic-repair-legacy-data`Repair or Roll Back Mosaic Legacy Data	Explicitly applies the legacy empty-JSON repair or rolls back the most recent WPPilot repair. The operation is transactional, bounded to 1,000 rows, and records affected row IDs before changing data.

PreviousMeta Box NextNinja Forms