build-contract.php
Describes the accepted native page build structure, inspects code ownership and contract compliance, and exposes the contract to tooling.
Responsibility#
Describes the accepted native page build structure, inspects code ownership and contract compliance, and exposes the contract to tooling.
This is an implementation reference for the released 0.9.13 module. Internal PHP helpers are not a compatibility promise for third-party callers. Prefer the documented REST, Abilities, theme, and filter contracts.
Related modules#
conditions, dynamic, element-css, element-js, element-php, native-allowed-html, popups, responsive, theme.
WordPress hooks#
| Operation | Hook |
|---|---|
apply_filters |
cantata_edit_native_custom_properties |
add_action |
rest_api_init |
add_action and add_filter subscribe to a hook; do_action and apply_filters expose a hook. A subscription is not itself a new extension API. Dynamic hook names are not included in this literal inventory.
Function and method reference#
cantata_edit_build_contract#
function cantata_edit_build_contract(): array
Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.
Source location: includes/build-contract.php:5.
cantata_edit_build_contract_enabled#
function cantata_edit_build_contract_enabled(): bool
Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.
Implementation connections: cantata_edit_config.
Source location: includes/build-contract.php:25.
cantata_edit_build_contract_error#
function cantata_edit_build_contract_error( string $code, int $index, string $tag, string $detail )
Return an element-indexed error without storing any of the submitted HTML in logs.
Source location: includes/build-contract.php:31.
cantata_edit_build_contract_never_grandfathered#
function cantata_edit_build_contract_never_grandfathered(): array
Tags that are never accepted by source proof: they execute, embed another document or load code/styles.
Source location: includes/build-contract.php:40.
cantata_edit_build_contract_native_custom_properties#
function cantata_edit_build_contract_native_custom_properties(): array
Inline properties the editor's own native controls write that are custom properties (editor.js syncGridVar).
Implementation connections: cantata_edit_build_contract_legacy_check.
Source location: includes/build-contract.php:47.
cantata_edit_build_contract_validate#
function cantata_edit_build_contract_validate( string $html, bool $strict = true )
The normal save validator runs before kses can silently erase an unsupported implementation. Trusted developer exceptions have explicit storage and their own server-side capability checks. Unknown semantic HTML is not guessed into an interactive widget: it remains a normal native container/text element.
$strict true (CLI, imports, new builds): any element outside the supported model is refused. $strict false (the save sanitizer): an inert unsupported element is left for cantata_edit_build_contract_legacy_check(), which refuses it with a message that says whether it was already on the page (the sanitizer could not keep it). Code tags, handlers, srcdoc and executable URLs are refused in both modes.
Implementation connections: cantata_edit_build_contract_error, cantata_edit_build_contract_never_grandfathered, cantata_edit_conditions_parse, cantata_edit_dyn_parse, cantata_edit_element_js_check_submission, cantata_edit_element_js_mask, cantata_edit_native_allowed_html, cantata_edit_popup_element_problem, cantata_edit_popup_parse.
Source location: includes/build-contract.php:61.
cantata_edit_build_contract_tag_identity#
function cantata_edit_build_contract_tag_identity( WP_HTML_Tag_Processor $tags ): string
A comparable identity for an opening tag: name and attributes (sorted), without the model marker.
Source location: includes/build-contract.php:151.
cantata_edit_build_contract_legacy_check#
function cantata_edit_build_contract_legacy_check( string $html, string $stored )
Legacy markup outside the supported model, on the save path ($strict false in validate()). Kindly's sanitizer only keeps elements in its allowlist, so an element outside it cannot be preserved exactly: it would be unwrapped (its words kept, its tag lost) without anyone deciding that. So it is refused before any write, with its element number and whether it was already on the page, never "kept" and then silently changed. The fix is a native element (or its exception in Developer > Advanced); pages that are not built are not touched by this. $stored is used only to say whether the element was already there.
Implementation connections: cantata_edit_build_contract_error, cantata_edit_build_contract_tag_identity, cantata_edit_native_allowed_html.
Source location: includes/build-contract.php:170.
cantata_edit_build_contract_competes#
function cantata_edit_build_contract_competes( array $rule ): bool
Whether a rule in an element's CSS competes with its own inline style for $property: a rule for the element itself (not only for something inside it) under a state, attribute, :is()/:not(), media query or ancestor condition.
Source location: includes/build-contract.php:194.
cantata_edit_build_contract_property_family#
function cantata_edit_build_contract_property_family( string $property ): string
Same conservative shorthand/logical-alias families as element-css.js route().
Source location: includes/build-contract.php:207.
cantata_edit_build_contract_merge_base#
function cantata_edit_build_contract_merge_base( string $css, array $extra )
Move $extra declarations into the element's base rule (selector "&", no media). A property already in a base rule is replaced there (never appended as a second, stale rule), unless the stored one is !important and the new one is not (the !important one already won before). Returns canonical CSS, or a WP_Error.
Implementation connections: cantata_edit_element_css_parse, cantata_edit_element_css_stylesheet.
Source location: includes/build-contract.php:225.
cantata_edit_build_contract_normalize#
function cantata_edit_build_contract_normalize( string $html, bool $strict = false )
Automatic import/save normalization for inline presentation outside the dedicated controls. Values go through the scoped CSS parser, never string concatenation into a public stylesheet. Native properties remain inline. The caller must run CSS/JS permission checks against the normalized authoritative source as well as the input.
Faithful inline exceptions: a declaration stays in the inline style (where Developer > Advanced > CSS shows and edits it with the rest of the element's CSS) when moving it would change what wins in the cascade:
- an !important inline declaration beats every stylesheet rule, including a theme's !important ones;
- a property family the element's own CSS also sets under a state, media query or condition: inline beat that rule, a moved base rule would not. Everything else moves into the element's base rule. The element CSS scope is [data-ce-k]:not(#ke-css), specificity (1,1,0): a theme rule with two ids, or an id and more classes, could beat a moved declaration that inline beat. Kindly does not add !important to imitate inline priority.
Implementation connections: cantata_edit_build_contract_competes, cantata_edit_build_contract_error, cantata_edit_build_contract_merge_base, cantata_edit_build_contract_native_custom_properties, cantata_edit_build_contract_property_family, cantata_edit_build_contract_validate, cantata_edit_element_css_declarations, cantata_edit_element_css_parse, cantata_edit_visual_properties.
Source location: includes/build-contract.php:279.
cantata_edit_build_contract_unmigrated#
function cantata_edit_build_contract_unmigrated(): array
Deployment guard (read-only): built records and saved parts whose stored copy still has elements without the model marker. Their first save switches legacy compatibility CSS/JS off for those elements, so a site's content migration must be complete before a plugin with the contract is activated. Returns [ [ id, type, field, count ] ].
Source location: includes/build-contract.php:333.
cantata_edit_build_contract_php_audit#
function cantata_edit_build_contract_php_audit(): array
Server-code audit uses the actual owner; references in archived versions are not active authoring state.
Implementation connections: cantata_edit_build_contract, cantata_edit_build_contract_enabled, cantata_edit_build_contract_normalize, cantata_edit_build_contract_unmigrated, cantata_edit_components, cantata_edit_element_php_contract_violations, cantata_edit_element_php_values.
Source location: includes/build-contract.php:354.