Theme bridge ability reference

How the theme bridge decides which theme it is talking to

The bridge looks at two slugs, the active theme's stylesheet and its template, and picks an adapter from them. If either is blocksy, neve or woodmart, that adapter wins, so a child theme of Blocksy is handled as Blocksy. Only when neither matches does it fall back to the block-theme adapter, and only if WordPress reports a block theme. A classic theme that is none of the three gets theme_bridge_not_available with HTTP 409. A parent theme whose folder has been renamed, as white-labelled agency builds sometimes are, is not recognised by slug and lands in the same refusal.

wppilot/theme-bridge-check-setup reports the adapter, whether a child theme is active, and two counts: how many theme_mod settings the Customizer registered and how many of them the connected user may write. A low writable count on a WoodMart site does not mean something is broken: WoodMart's Theme Settings panel is outside the bridge, so only what WoodMart registers in the Customizer appears.

Theme mods are stored per active stylesheet. On a child theme the bridge reads and writes the child's row, so switching between parent and child, or activating a different child, shows a different set of values even though the settings have the same IDs.

Searching the Customizer inventory without flooding the conversation

A theme can register a great many Customizer settings, so wppilot/theme-bridge-list-customizer-settings is built to be searched rather than dumped. query takes up to 100 characters and matches anywhere in a setting ID, ignoring case; writable_only hides everything the agent may not change, and results come 50 at a time by default (up to 100) with offset, total and has_more for paging. Searching for a word such as color, header or footer with writable_only on is usually the fastest route to the right ID.

Each row explains itself. storage and transport say how the theme registered the setting; capability is what WordPress requires to change it; value_bytes and value_truncated show when a large value was left out; default gives the theme's starting value, which is what a person usually means by put it back; redacted marks a value hidden because its ID looks sensitive; and writable with write_block_reason says whether the update call will accept it. Only IDs listed as writable may be sent.

For block themes, wppilot/theme-bridge-list-block-assets takes the same query, offset and limit, plus type (all, template or template_part) and source (theme for files the theme ships, custom for copies stored in the database). Each row reports has_theme_file and, for template parts, the area such as header or footer. A custom row that also has a theme file is an edited copy overriding the shipped one, and that copy is what an edit would change. The edit itself is made with GoBuildWP Free's block theme abilities, such as wppilot/update-template, not through the bridge.

What a theme bridge save runs, and what to look at afterwards

For every key in the patch, wppilot/theme-bridge-update-customizer-settings runs the setting's own validate step and then its sanitize step, exactly as the Customizer would. A setting that returns an error is rejected with that message; one whose sanitizer returns nothing is rejected as theme_bridge_sanitize_rejected; an unregistered ID gives theme_bridge_unknown_setting and a blocked one theme_bridge_setting_read_only. Two problems stop the whole patch instead of one key: an empty settings object (theme_bridge_invalid_input) and more than 50 keys (theme_bridge_batch_too_large).

Accepted values are saved one setting at a time through the Customizer's own save routine, and the values map in the result holds what was stored after sanitising, which can differ from what was sent, for example when a sanitizer normalises a colour or clamps a number. Compare the two before reporting success. The bridge does not create a Customizer changeset, so the change is live at once and does not appear as a draft or scheduled change in the Customizer.

Some themes regenerate stylesheets or caches when the Customizer is published. Whether a given theme does that from an individual setting save has to be checked on a real site: load a page logged out after the change, and if the old styling persists, clear the theme's or host's cache before assuming the save failed.

Theme bridge permissions, profile and recovery

The update call is an ordinary write, not a destructive one, so the confirmation gate does not stop it; under the Read Only safety profile only the three reads load. Two agents writing at once queue on a per-site lock around the theme mods row, and theme_bridge_lock_busy means the other write held it for too long; retry once it has finished.

Because the change ledger snapshots the whole theme mods row before each save, a rollback restores every Customizer value of that theme to its earlier state, including values someone changed by hand in the meantime. For a single wrong value, sending the old value or the default back through the update call is the narrower fix.