The PHP class wpTrussElementRegistry (in includes/class-wpt-element-registry.php) is the engine that makes the element JS system work. Block developers do not interact with it directly, but understanding what it does explains how element scripts get to the browser.
What the PHP Class Does
Script registration. On enqueueblockeditor_assets, it registers every element file in src/elements/ as a WordPress script handle (wpt-element-{name}). Each handle depends on wpt-element-registry. WordPress then loads only the element scripts that blocks declare as dependencies.
Data localisation. It passes user defaults, the REST nonce, and the substitutions warning flag to the editor via wplocalizescript(), attached to the wpt-element-registry handle. This data lands in window.tpRegistryData and is consumed by the cascade resolver.
User defaults storage. Saves and retrieves the user defaults object from wp_options via REST endpoints.
Substitutions. On init, checks if src/registry/substitutions.json has been updated since last run. If so, scans all published posts for elementOverrides containing stale values and automatically replaces them. This handles migrations when element control options are renamed.
The Substitutions System
When you rename an option value in an element definition file (for example, renaming 'large' to 'lg' in the button size options), existing pages that have "button.primary.size": "large" stored in their block attributes would break, the old value no longer exists.
The substitutions system fixes this automatically. Add an entry to src/registry/substitutions.json:
{
"_version": "1.1.0",
"elements": {
"button": {
"size": {
"large": "lg",
"small": "sm"
}
}
}
}
On the next plugin boot, the PHP class scans all posts, finds any block with button.primary.size = 'large', replaces it with 'lg', and saves the post. A warning is logged to the debug panel listing every substitution made.