Kindly EditDocumentationTry the editor

Native scoped styles

Integrate generated styles without breaking repeated lists, tables, or document order.

An application that repeats native presentation parts must not insert a generated stylesheet node before every li, tr or other semantic child. That changes first-child, adjacent-sibling and table/list behavior. Keep generated styles in an authorized native head asset, while leaving the repeated markup structurally intact.

cantata_edit_compile_scoped_styles(string $trusted_html): array is a pure compiler. It returns html with the existing render-only scope annotations and styles, an ordered list of {kind, css, sha256}. Kinds are element-css and responsive; hashes are SHA256 of the exact CSS bytes. List order matches the existing prefix stylesheet order. Calling it twice on identical source yields identical output. It does not render linked components, breadcrumbs, shortcodes, JavaScript or PHP, create keys, sanitize arbitrary markup, or grant executable authority. Use trusted native presentation sources, not lower-trust generated record HTML.

Precompile the actual published part sources the current visitor may receive during wp_enqueue_scripts. A manager's private appearance workspace can compile that manager's native draft sources after its existing permission checks. Protect private/member source sets through the same native authorization rules, including CSS content strings. Deduplicate entries by kind/hash and add their exact CSS through the owning native stylesheet with wp_add_inline_style. Include public/guest parts actually used by unauthorized portal views. No footer callback is required for REST previews.

cantata_edit_render($html, $owner, $style_sink) optionally accepts a trusted PHP callable. Each CSS renderer sends only its own validated generated entry to this sink before lower-trust live content fills the slots. Returning strict true accepts that entry and suppresses only that generated prefix; every other return retains the existing prefix output. This is a server integration API, not an HTML attribute or browser approval endpoint. The two pure renderers also accept the optional sink directly.

A native application can accept only entries already present in its authorized head plan. A miss must retain safe output and be reported/tested, rather than silently discarding presentation. Do not regex-strip style nodes from a completed native/live result: they may come from a different owner or lower-trust application data. Passing a sink to a parent does not automatically propagate authority into nested live output; each independently rendered native child must use its own approved integration.

Existing callers without a sink retain their byte-compatible prefix behavior. Existing editor CSS reactivity, save sanitizers, signature checks and role permissions are unchanged. Neither compiler nor sink signs JavaScript, approves PHP, or creates source/record access rights. Render-only scope attributes remain outside persisted content.

Verification: scoped-style-compiler-test.php checks exact legacy output, stable ordering/hashes, empty/invalid source, no live execution, no signing-key changes, explicit acceptance/fallback and lower-trust provenance. scoped-style-browser.mjs uses actual native WordPress REST role gates and Chromium list/table sibling, first-child and responsive checks. The application's own acceptance must additionally prove its preload permissions, fresh REST requests, all source families, no misses, repeated instances and draft/public reload behavior.

Ordered capture for complete application pages and fresh live previews#

A trusted installed owner may opt a frontend into cantata_edit_capture_scoped_styles with strict true. This buffers the complete response. At the existing validated core prefix-generation sites, the core emits unpredictable request-owned comment markers. Finalization reads only these exact markers, keeps actual document order, and emits the associated typed CSS at the head marker supplied by wp_head. It never extracts arbitrary HTML style tags or promotes remote CSS. All core-owned scopes participate, including authored page scopes surrounding native applications. Child-first PHP rendering therefore preserves parent-before-child document order. Discarded render strings contribute no CSS. Capture takes precedence over an explicit render sink while active; the pure compiler suspends and restores capture, so it remains side-effect free. Duplicate markers or a missing frontend head marker keep legacy prefixes.

The existing authorized /live route uses the same capture only when the trusted owner explicitly enables that filter and the client sends scoped_styles: true, returns ordered typed styles separately, and restores any enclosing capture on success or exception. The editor installs these in its head before parsing a fresh fragment, after its stale-response guard. Identical sheets are reused and moved in response order so repeated equal-priority declarations retain their final cascade. Head deduplication requires a matching actual head style and exact text; arbitrary body IDs cannot block installation. Ordinary frontend sites and live endpoints that do not opt in keep the previous render path. Older open editor tabs omit the capability flag and continue receiving legacy prefix styles in their HTML; the response-format flag grants no code or access permission. The first explicit output flush falls back immediately to legacy prefixes and keeps later output in that mode, preserving ordinary PHP flush/clean behavior.

The owner must verify that moving core styles after ordinary head assets is faithful for the complete page. Never opt a renderer that caches rendered HTML, escapes captured fragments into attributes/JSON, or places them in raw-text/noscript contexts into this request-bound transport. Native application caches must hold source data, with presentation rendered for the current request. For guaranteed final head order, remove the default wp_head action for cantata_edit_scoped_style_capture_head_marker and call that named function immediately after the theme's complete wp_head() call. A callback at PHP_INT_MAX alone can still precede another callback at that priority. Preserve the existing document shell. Arbitrary lower-trust body styles remain untouched and may have order-sensitive ties; capture does not promise equivalence for such documents.

Run tests/scoped-style-order-browser.mjs and tests/live-style-transport-browser.mjs against isolated WordPress. Cover important ties, authored parents, child-first render calls, repeated semantic children, six responsive widths, nested/discarded contexts, fallback, fresh settings, roles, stale responses and lower-trust preservation. Native renderers should finish the trusted presentation render before pruning optional fields or inserting opaque operational values, so compile hashes do not change with availability.

About this page

Documents Kindly Edit 0.9.16. Source: docs/SCOPED-STYLES.md. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.