WIP: Abilities API rejects link: "lightbox" on image elements, blocking all writes to the page

Bugs
1

Environment

  • Tool: Claude Code (MCP client), via MCP Adapter

  • OS: Windows 11

  • Browser: Chrome (only relevant for step 2, setting the lightbox in the builder)

  • URL: staging site, access can be provided on request

Component Version
Bricks 2.4-beta2
Bricks child theme 1.1
Bricks abilities contract 1.0.0
WordPress MCP Adapter 0.5.0
WordPress 7.0.2
PHP 8.1.34 (fpm-fcgi)
MySQL 8.0.36
Memory limit 256M
Bricks CSS loading inline

Abilities API and MCP adapter both active and working; all other abilities behave as expected.

Description

For the image and image-gallery elements, link is a select control with the valid options lightbox, attachment, media and custom. The abilities validator, however, treats link as a link-object control for every element type and rejects any string value:

Element 'v0a0f4' has a `link` setting that is not an object.

Bricks expects `link` to be an object like { type: 'external', url: 'https://example.com' }.

Two consequences:

  1. Lightboxes cannot be set through the API at all.

  2. More importantly: once a lightbox has been set in the builder, every subsequent write to that page fails, including updates to completely unrelated elements. The validator walks the whole element tree on write and trips over the existing, perfectly valid link: "lightbox".

So a normal builder setting renders the page uneditable through the API.

Steps to reproduce

  1. Add an image or image-gallery element to a page.

  2. In the builder, set Link to → Lightbox. Save.

  3. Call bricks/update-element on any element of that page, for example changing a heading’s text.

  4. The call fails with the error above, naming the image element rather than the one being updated.

Setting link: "lightbox" directly via bricks/update-element fails the same way, so there is no API-side workaround.

Expected

link should be validated per element type: as an object where the control is of type link, and as a select value where the control is a select (image, image-gallery). A pre-existing valid value should never block writes to other elements.

Impact

Any page using a lightbox is locked out of the abilities API. Since lightboxes are common on gallery pages, this affects a lot of real sites. Current workaround is to remove the lightbox, write, then set it again, or to patch the database directly.

Possibly related: the pattern resembles 39777 (global class _cssCustom cleared when the class is inspected in the builder): in both cases a valid state that one layer cannot represent gets rejected or destroyed by that layer.

3

Hey @j410,

thank you for the report and welcome to the forum! :slight_smile:

I was able to replicate the issue locally as well and I’ve added it to our internal bug tracker. Once we resolve the issue, we will update this forum topic.

Thank you,
Matej

4

Same here.

I’ve hit what looks like a validation bug in the Bricks Abilities API (the AI/MCP integration) related to the image-gallery Lightbox link.

Environment

  • Bricks 2.4-beta, Abilities API 1.0.0
  • WordPress 7.0.2
  • Occurs via the Abilities API only (the visual builder itself works fine)

What happens
As soon as an image-gallery element has its “Link to” set to “Lightbox”, its link setting is stored as the string "lightbox". After that, calling update-element or batch-update-elements on any element on that page/template fails validation — even elements completely unrelated to the gallery:

Element 'gxbyka' has a `link` setting that is not an object.Bricks expects `link` to be an object like { type: 'external', url: 'https://example.com' }.

(gxbyka is the gallery’s ID; the same error is thrown when editing other elements, because the validator checks the whole page tree on every write.)

Steps to reproduce

  1. Add an image-gallery element to a page.
  2. Set Link to → Lightbox.
  3. Via the Abilities API, run update-element / batch-update-elements on any element on that page.
  4. → It fails with the error above.

Expected
Being able to edit elements on the page normally, since link: "lightbox" is a legitimate value the builder itself produces.

Likely cause
The element-tree validator requires every element’s link to be an object { type, url }. But for image and image-gallery elements, “Link to” is a select whose valid values include the strings "lightbox", "lightboxImage", "lightboxVideo", "media", etc. The validator rejects those strings, and because it validates the entire tree on each write, one lightbox-enabled gallery locks editing of the whole page.

Workaround
Temporarily switch the gallery’s “Link to” away from Lightbox, edit via the API, then re-enable Lightbox. Re-enabling has to be done in the builder, because the API can’t write link: "lightbox" back — the same validator rejects it.

Suggested fix
Allow string link values for elements whose “Link to” is a select (image, image-gallery) — e.g. accept "lightbox", "lightboxImage", "lightboxVideo", "media" — or skip the object-shape validation of link for those element types.

Thanks!