Nerti Abilities for Oxygen

Jedna wtyczka, jedna instalacja, komplet abilities dla agenta pracującego w Oxygenie. Grupy włączają się same, zależnie od tego, co zastaną na witrynie.

MCP ability pack for Oxygen 6.x + Breakdance Elements for Oxygen, built on the WP Abilities API and Agent Connector for WP.

Download the latest release →

Install the .zip from the release page, not the green Code → Download ZIP button: that one names the folder …-main, so WordPress installs it under a different slug and the next update lands as a second copy instead of replacing the first.

It exists because an agent building client-editable pages in Oxygen keeps hitting the same walls. Every claim below was re-measured on 2026-08-21 on a live install: Oxygen 6.2.0-beta.5, Breakdance Elements for Oxygen 1.1.0.beta.1, WordPress 7.1, PHP 8.2.29. Nothing here comes from documentation, and two claims in the 0.7.0 README were wrong by this version — the element counts, and "the hidden-elements option does not affect MCP". Both are corrected below.

The walls, as measured on 6.2.0-beta.6

1. MCP cannot see the elements every page is made of — and two separate bans cause it

count( \Breakdance\Elements\get_element_classnames() )   // 186
count( breakdance_mcp_visible_element_classnames() )     // 151   pack filter removed
count( breakdance_mcp_visible_element_classnames() )     // 164   pack active

The 13 the pack restores: Section, Div, Heading, Icon, Text, RichText, TextLink, WrapperLink, Image2, CodeBlock, CssCode, HtmlCode, PhpCode. Without them get-element-schemas returns them as missing and edit-post rejects the element_type.

• Ban A — BREAKDANCE_MCP_HIDDEN_ELEMENTS in mcp/schemas/elements.php. 14 entries on this version: CssCode, HtmlCode, PhpCode, CodeBlock, FHtmlCode, Div, WrapperLink, Text, TextLink, Image, Image2, RichText, FSvgIcon, SvgIcon. Section, Heading and Icon came off this list since beta.2. No site setting can change it.
• Ban B — the oxygen_builder_hidden_elements option, pre-filled by addDefaultHiddenElements() with 10 entries and still populated on a current install: Section, Div, Heading, Text, TextLink, WrapperLink, Icon, RichText, CodeBlock, Image2. Updating Oxygen does not clear it.

The Oxygen → Settings → Elements screen and oxygen_builder_hidden_elements are the same thing, not two views of it: admin/settings-page/tabs/elements.php reads and writes get_global_option('builder_hidden_elements'), and Breakdance\Data\get_global_option() (plugin/data/api/options.php) is get_option( __bdox('meta_prefix') . $field ) with meta_prefix = oxygen_.

Ban B is not editor-only. That same file hangs filter_builder_elements() on the breakdance_builder_elements filter at priority 10, and mcp/schemas/elements.php runs the MCP element list through that same filter. Two independent gates, and either one alone is enough to make an element unaddressable. Measured two ways:

• Removing the pack's filter in-process took breakdance_mcp_visible_element_classnames() from 164 to 151, with all ten of Ban B's elements flipping to hidden.
• Adding EssentialElements\Button to the option dropped oxygen-get-element-slugs from 164 to 163 and made get-element-schemas refuse it; removing it restored 164.

Build first, hide last. Hiding elements in Oxygen → Settings → Elements before the agent has finished building cuts the agent off from them.

The pack restores on the same filter at priority 20, i.e. after the settings page's priority-10 subtraction — which is what makes the restore win.

Ten-second check that the ten are still hidden, because "Oxygen updated, surely it cleared that by now" is a tempting and wrong assumption: open Oxygen → Settings → Elements and type Section into Filter elements. The list is alphabetical, so scrolling from the top stops at Blockquote long before Section and tells you nothing. From the shell: wp option get oxygen_builder_hidden_elements --format=json.

The price of the restore, stated plainly

Restoring on breakdance_builder_elements is not agent-only. The builder's Add panel is driven by the same list: get_elements_for_builder() passes the filtered array to FilteredGets\addPanelRules(), which sets alwaysHide on everything missing from it. Put the elements back and the flag never gets set. Measured on the lab install:

So while the pack is active, the client sees those 13 elements too, and a human who hides one of the 13 in Oxygen → Settings → Elements is silently overruled — the pack's priority-20 restore runs after the settings page's priority-10 subtraction. That is the exact simplification Oxygen was going for, and the pack removes it.

Could it restore for MCP only? Only by sniffing the request. The two consumers are different functions (get_elements_for_builder() for the panel, breakdance_mcp_visible_element_classnames() for MCP) but they share one filter, and the filter receives no caller information. The discriminator would have to be the admin-ajax action name (breakdance_load_builder_elements, breakdance_load_document) — a string Oxygen is free to rename, at which point the guard stops matching and silently reverts to today's behaviour. We chose not to trade a visible, documented cost for an invisible, undocumented one.

The lever instead. bdox_pack_restored_elements is a filter. At handover, drop it to the code elements only — or to nothing — in a one-line mu-plugin, and the Add panel goes back to Oxygen's default while the pack's other eight abilities keep working:

add_filter( 'bdox_pack_restored_elements', '__return_empty_array' );

Handover order, and it is not the same as the build order: build → hide what the client should not see → then narrow bdox_pack_restored_elements (or deactivate the pack). Hiding while the pack still restores does nothing.

Section is the expensive one. It is the only element that renders .section-container, the wrapper that consumes --bde-section-width and the global section padding. An agent that cannot address it builds every layout on Div, the global container settings never apply, and each page ends up carrying its own width in a class — the exact outcome the global settings exist to prevent.

Why not the fundamentals, or the native Oxygen elements? On BEFO 1.1.0.beta.1 the fundamentals do not exist: class_exists() is false for EssentialElements\FText, FImage, FRichText, FTextLink, FSvgIcon2, FHtmlCode and EssentialElements\ContainerLink. The native replacements do exist but carry no Design tab — measured through oxygen-get-element-schemas:

A client-editable build needs the Design tab, so the two add_filter calls stay. The condition for deleting them is written into the plugin header: after updating BEFO to ≥ 1.1.0.beta.3, check class_exists('EssentialElements\FText') and whether its schema has a design section. Only if both hold do the filters become dead weight.

2. Selector writes replace instead of merging

Still true. .probe{margin:4px} imported over a selector already holding padding plus a custom_css block left only the margin. Global settings, on the other hand, were fixed — see wall 5.

3. There is still no cache-regeneration tool

None of the 49 tools the 6.2.0-beta.5 MCP server exposes rebuilds CSS. Oxygen's own save paths do (data/save.php calls generateCacheForPost() on a document save and generateCacheForGlobalSettings() on a settings or selector save), so this matters for data changed outside those paths, and for a cache that predates a plugin update — which renders the old default CSS and looks exactly like a specificity bug.

4. Element defaults are undocumented and some of them outrank your CSS

.bde-section .section-container is (0,2,0) and .bde-text-link > * is (0,1,1); both beat a flat project class (0,1,0) no matter what order the files load in. Without knowing that, an agent writes CSS that silently does nothing.

5. What Soflyy fixed in 6.2.0 — stop working around it

• !important survives insert-stylesheet. mcp/design/css-to-properties.php now diverts every !important declaration into custom_css with the flag intact, before the typed converters run. Measured end to end: .probe{color:#ff0000 !important;padding:8px} stored padding as a typed spacing property and custom_css as :selector {\n color: #f00 !important;\n}. bdox/merge-css-selector is no longer the only route to !important.
• set-global-settings deep-merges. breakdance_mcp_deep_merge_settings() merges assoc arrays key by key; lists and scalars still replace wholesale. Measured: sending only typography.base_font_size left colors.palette and typography.body_font intact.
• get-global-settings no longer fails on an empty install. It normalises the empty tree to {"settings":{}}.

6. get-global-settings still refuses real settings

Measured against a production site, then reproduced on the lab install by storing the same value:

output[settings][buttons][primary][corner_radius][unit] is not of type object,null

You get nothing back, not even the parts that validate. The cause is inside Oxygen: the output schema declares buttons.primary.corner_radius as a breakpoint-keyed map, while the builder stores it flat as {number, unit, style} — and buttons.button_presets[].styles.corner_radius is breakpoint-keyed, so the same control is persisted two different ways.

7. set-global-settings still rejects keys the renderer reads

buttons.primary.background_hover goes through (that object is open), but buttons.primary.typography.color_hover is rejected with color_hover is not a valid property of object, because that sub-object is additionalProperties: false. elements/macros/atom-v1-button-css.twig reads exactly that key for the button hover text colour.