Kindly EditDocumentationTry the editor

element-js.php

Validates element-owned JavaScript envelopes, signs trusted ownership, handles code authoring and migration helpers, and prints only authorized execution payloads.

Responsibility#

Validates element-owned JavaScript envelopes, signs trusted ownership, handles code authoring and migration helpers, and prints only authorized execution payloads.

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.

build-contract, editor, render, rest, template-code, theme.

Module constants#

const CANTATA_EDIT_ELEMENT_JS_MAX = 16384;
const CANTATA_EDIT_ELEMENT_JS_COUNT = 64;
const CANTATA_EDIT_ELEMENT_JS_TOTAL = 131072;
const CANTATA_EDIT_ELEMENT_JS_REGISTRY_MAX = 262144;

These values describe this release. Defined configuration constants and generated identifiers can have different ownership; do not edit stored values directly without following the corresponding workflow.

Literal option and cache keys#

cantata_edit_element_js_key. These are direct literal keys found in this module; dynamically constructed keys and metadata constants are covered by the storage reference.

WordPress hooks#

Operation Hook
apply_filters cantata_edit_developer_mode_cap
apply_filters cantata_edit_can_author_js
apply_filters cantata_edit_element_js_conflict
apply_filters cantata_edit_element_js_key
apply_filters cantata_edit_element_js_should_run
add_action wp_print_footer_scripts
add_filter wp_insert_post_data
add_action transition_post_status
add_action wp_after_insert_post
add_filter content_save_pre
add_action load-post.php
add_action rest_api_init
add_filter rest_pre_insert_{$type}
add_filter wp_insert_post_empty_content
add_filter gettext
add_action admin_notices
apply_filters cantata_edit_native_application_behaviors

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_can_author_js#

function cantata_edit_can_author_js( int $user_id = 0 ): bool

Who may write or change element JavaScript: accounts that may already publish arbitrary HTML (unfiltered_html) and may use Developer mode. The filter can only take the permission away, never give it.

Implementation connections: cantata_edit_can_dev.

Source location: includes/element-js.php:30.

cantata_edit_element_js_normalize#

function cantata_edit_element_js_normalize( string $source ): string

The one stored form: line endings as LF, no leading or trailing space, tab or line break. Nothing else is trimmed (a NUL or other control character at either end is kept, so validation refuses it). The editor does the same.

Source location: includes/element-js.php:45.

cantata_edit_element_js_secret_patterns#

function cantata_edit_element_js_secret_patterns(): array

High-confidence credential shapes. Custom JavaScript is public, so a secret in it is published.

Source location: includes/element-js.php:50.

cantata_edit_element_js_validate#

function cantata_edit_element_js_validate( string $source ): array

Check one source. Returns [ 'ok' => bool, 'source' => canonical ('' when not ok), 'errors' => [ [ code, message ] ] ]. The server does not parse JavaScript (the editor compiles it before Apply); it checks what it can state exactly.

Implementation connections: cantata_edit_element_js_normalize, cantata_edit_element_js_secret_patterns.

Source location: includes/element-js.php:67.

cantata_edit_element_js_native_conflict#

function cantata_edit_element_js_native_conflict( string $tag, array $attrs, array $ancestors ): string

Where custom JavaScript may not go: elements whose behavior already has a native owner. Returns '' or the reason. $ancestors: lowercase tag => true for open ancestors, plus 'live-slot' when inside one.

Source location: includes/element-js.php:98.

cantata_edit_element_js_owner_for_post#

function cantata_edit_element_js_owner_for_post( $post ): string

The owner a signature is bound to: a page or post ('post:12'), or a shared part ('part:header').

Source location: includes/element-js.php:114.

cantata_edit_element_js_key#

function cantata_edit_element_js_key(): string

The server-only key. Kept in the database (not wp-config salts) so a database copy keeps code verified.

Source location: includes/element-js.php:130.

cantata_edit_element_js_signature#

function cantata_edit_element_js_signature( string $source, string $owner ): string

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_element_js_key.

Source location: includes/element-js.php:145.

cantata_edit_element_js_verify#

function cantata_edit_element_js_verify( string $source, string $sig, string $owner ): 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_element_js_signature.

Source location: includes/element-js.php:149.

cantata_edit_element_js_walk#

function cantata_edit_element_js_walk( string $html, callable $fn, ?WP_HTML_Tag_Processor $tags = null ): WP_HTML_Tag_Processor

Walk the opening tags of some HTML, with the open ancestors that matter for placement (form, live slot). $fn( WP_HTML_Tag_Processor $tags, array $ancestors ) is called for every opening tag.

Source location: includes/element-js.php:161.

cantata_edit_element_js_values#

function cantata_edit_element_js_values( string $html ): array

Every element with code, in document order: [ 'tag', 'source' (decoded, as written), 'sig', 'conflict' ]. A data-ke-js-sig without data-ke-js is reported with source null.

Implementation connections: cantata_edit_element_js_native_conflict, cantata_edit_element_js_walk.

Source location: includes/element-js.php:195.

cantata_edit_element_js_trusted_counts#

function cantata_edit_element_js_trusted_counts( string $html, string $owner ): array

Canonical sources stored in some HTML that verify for this owner, counted: source => occurrences.

Implementation connections: cantata_edit_element_js_normalize, cantata_edit_element_js_values, cantata_edit_element_js_verify.

Source location: includes/element-js.php:221.

cantata_edit_element_js_counts#

function cantata_edit_element_js_counts( string $html ): array

Canonical sources present in some HTML, verified or not, counted.

Implementation connections: cantata_edit_element_js_normalize, cantata_edit_element_js_values.

Source location: includes/element-js.php:234.

cantata_edit_element_js_check_submission#

function cantata_edit_element_js_check_submission( string $html, string $stored, ?bool $can_author = null, bool $legacy = true )

The save endpoints' check, before anything is cleaned or written. Invalid or misplaced code is refused with its reason. An account that may not author code (and every AI path: pass $can_author false) may keep or delete stored code exactly as stored, but not add, change or duplicate it: per source, the count may not grow.

Implementation connections: cantata_edit_build_contract_enabled, cantata_edit_build_contract_legacy_check, cantata_edit_can_author_js, cantata_edit_element_js_counts, cantata_edit_element_js_finish, cantata_edit_element_js_validate, cantata_edit_element_js_values, cantata_edit_template_code_elements.

Source location: includes/element-js.php:249.

cantata_edit_element_js_mask#

function cantata_edit_element_js_mask( string $html ): array

Take every data-ke-js value out of the HTML before the sanitizer runs, so no regex, kses pass or attribute filter can touch the source. Returns [ 'html' => with random tokens, 'map' => token => source ]. Signatures sent by the browser are dropped here: only cantata_edit_element_js_finish() writes them.

Implementation connections: cantata_edit_element_js_normalize.

Source location: includes/element-js.php:321.

cantata_edit_element_js_attr#

function cantata_edit_element_js_attr( string $source ): string

Escape a source for a double-quoted attribute value: the result has no < > " ' and no ambiguous &.

Source location: includes/element-js.php:347.

cantata_edit_element_js_unmask#

function cantata_edit_element_js_unmask( string $html, array $map ): string

Put masked sources back, escaped. A token the sanitizer removed stays missing (finish() then refuses the save).

Implementation connections: cantata_edit_element_js_attr.

Source location: includes/element-js.php:352.

cantata_edit_element_js_finish#

function cantata_edit_element_js_finish( string $submitted, string $clean, string $stored, string $owner, ?bool $can_author = null, string $stored_owner = '', string $grant_owner = '' )

After cleaning, before writing: every submitted source must still be there, unchanged and in order, or the save is refused (nothing is written). Then signatures are set for $owner. A source is signed when:

  • the stored copy already had it verified (for $stored_owner, default $owner; 'theme' for a theme file's default): for a non-author only as many copies as were stored, for an author any number (duplicating);
  • or the account may author code and applied it explicitly in this request: data-ke-js-approve on the element (set by the Custom JavaScript panel's Apply; a request-only marker, never stored). Nothing else is signed: code planted through another path, or pasted or copied in from elsewhere, stays unverified (visible, inert) when an administrator saves the page for some other reason, until it is reviewed and applied.

Implementation connections: cantata_edit_can_author_js, cantata_edit_element_js_counts, cantata_edit_element_js_normalize, cantata_edit_element_js_signature, cantata_edit_element_js_trusted_counts, cantata_edit_element_js_values, cantata_edit_template_code_elements, cantata_edit_template_code_honoured.

Source location: includes/element-js.php:373.

cantata_edit_element_js_sign_html#

function cantata_edit_element_js_sign_html( string $html, string $owner ): string

Migration helper for root (operator trust): sign every valid source for $owner. Review the code before calling.

Implementation connections: cantata_edit_element_js_signature, cantata_edit_element_js_validate.

Source location: includes/element-js.php:444.

cantata_edit_element_js_strip_unverified#

function cantata_edit_element_js_strip_unverified( string $html, string $owner ): string

Remove signatures that do not verify for $owner (and any approval marker). The code stays; it just does not run.

Implementation connections: cantata_edit_element_js_verify.

Source location: includes/element-js.php:460.

cantata_edit_element_js_should_run#

function cantata_edit_element_js_should_run(): bool

Whether code may run on this response: public views only. A WordPress preview runs it only when asked.

Implementation connections: cantata_edit_is_editing.

Source location: includes/element-js.php:479.

cantata_edit_element_js_token#

function cantata_edit_element_js_token(): string

One random token per response. It is public (it is in the page) and only says "this response's renderer marked this element"; it is never what admits code. What admits code is the exact-source allowlist below.

Implementation connections: cantata_edit_element_js_render.

Source location: includes/element-js.php:502.

cantata_edit_element_js_registry#

function cantata_edit_element_js_registry( string $op = 'all', string $source = '' )

The response's allowlist of exact sources the runtime may compile: only cantata_edit_element_js_render() adds to it, and only sources whose signature verified for their owner. $op: 'add' (returns bool), 'all', 'pending' (added since the last emission, and marks them emitted), 'emitted' (bool: has a config/registration been printed), 'reset' (tests).

Source location: includes/element-js.php:515.

cantata_edit_element_js_json#

function cantata_edit_element_js_json( array $data ): string

JSON for an inline script: < > & ' " and every non-ASCII character (U+2028/2029 included) are \u escapes, "/" is "/", so no source text can end the script element, open a comment (<!--) or change how the script is parsed.

Source location: includes/element-js.php:545.

cantata_edit_element_js_config_script#

function cantata_edit_element_js_config_script( array $sources ): string

The runtime's configuration: this response's token and the exact sources it may compile.

Implementation connections: cantata_edit_element_js_json, cantata_edit_element_js_token.

Source location: includes/element-js.php:551.

cantata_edit_element_js_late_script#

function cantata_edit_element_js_late_script( array $sources ): string

Registration for code rendered after the configuration was printed (a part rendered late in the footer).

Implementation connections: cantata_edit_element_js_json, cantata_edit_element_js_token.

Source location: includes/element-js.php:556.

cantata_edit_element_js_render#

function cantata_edit_element_js_render( string $html, string $owner, ?bool $run = null ): string

Rendering stored HTML for $owner. Signatures never leave the server, and any data-ce-js / data-ce-js-state already in the HTML (forged or stale) is removed: only this function marks elements. Public (should_run): verified code gets data-ce-js="", its exact source joins the response's allowlist and the runtime is enqueued; unverified, misplaced or over-limit code is removed from the output. When the runtime's configuration was already printed (a late part), a registration script for the new sources follows the HTML. Not running (editor, revision, preview, feed, REST): the code stays as inert text; while editing, a render-only data-ce-js-state of verified, unverified or blocked tells the panel which it is. Call it on authored markup BEFORE live slots are filled: generated output must not acquire the owner's authority.

Implementation connections: cantata_edit_element_js_enqueue_runtime, cantata_edit_element_js_native_conflict, cantata_edit_element_js_registry, cantata_edit_element_js_should_run, cantata_edit_element_js_token, cantata_edit_element_js_validate, cantata_edit_element_js_verify, cantata_edit_element_js_walk, cantata_edit_is_editing.

Source location: includes/element-js.php:570.

cantata_edit_element_js_enqueue_runtime#

function cantata_edit_element_js_enqueue_runtime(): string

The public runtime, once, in the footer, with its configuration added when the footer scripts are printed (so it holds every source rendered before then). Returns HTML to print after the caller's output when the footer scripts were already printed: the runtime itself if it was not out yet, or a registration script for the new sources.

Implementation connections: cantata_edit_asset_ver, cantata_edit_element_js_config_script, cantata_edit_element_js_late_script, cantata_edit_element_js_registry.

Source location: includes/element-js.php:619.

cantata_edit_element_js_contract_violations#

function cantata_edit_element_js_contract_violations( string $html, string $owner = '' ): array

The build/import contract's view of hidden or out-of-system code in some HTML. Root's validator decides what to refuse; every item here is code a visitor could run without it being visible on its element in the editor. Each: [ 'code', 'tag', 'message' ].

Implementation connections: cantata_edit_element_js_native_conflict, cantata_edit_element_js_validate, cantata_edit_element_js_verify, cantata_edit_element_js_walk.

Source location: includes/element-js.php:653.

cantata_edit_element_js_current_counts#

function cantata_edit_element_js_current_counts( int $id, string $owner ): array

Verified copies of each source that a post (or part) currently holds: the larger count of its published content and any of its editor drafts. A write by an account that may not author code may keep up to this many, no more.

Implementation connections: cantata_edit_element_js_publishing_draft, cantata_edit_element_js_trusted_counts.

Source location: includes/element-js.php:708.

cantata_edit_element_js_limit_signed#

function cantata_edit_element_js_limit_signed( string $html, string $owner, array $allowed ): string

Remove signatures beyond $allowed (source => count), in document order. The code stays as inert, visible text.

Implementation connections: cantata_edit_can_author_js, cantata_edit_element_js_current_counts, cantata_edit_element_js_finish, cantata_edit_element_js_internal, cantata_edit_element_js_owner_for_post, cantata_edit_element_js_strip_unverified, cantata_edit_element_js_verify, cantata_edit_without_kses.

Source location: includes/element-js.php:721.

cantata_edit_element_js_internal#

function cantata_edit_element_js_internal( int $delta = 0 ): int

Kindly's own prepared writes (the REST save, build, new page, editor mode and AI store paths, all inside cantata_edit_without_kses() in rest.php) run at depth > 0. It is a server-side counter, never a request value: those paths already ran the full save pipeline (contract, capability, signature rules) on what they write. $delta: +1 to enter, -1 to leave, 0 to read.

Source location: includes/element-js.php:775.

cantata_edit_element_js_publishing_draft#

function cantata_edit_element_js_publishing_draft( int $id, ?string $html = null ): string

The editor draft a status transition is about to publish (render.php copies it into post_content after deleting the meta). Remembered at priority 5 of transition_post_status so the core-write limit counts it as current: a developer's verified draft stays verified when someone else presses Publish on WordPress's own screen.

Source location: includes/element-js.php:786.

cantata_edit_element_js_hidden_identities#

function cantata_edit_element_js_hidden_identities( string $html ): array

Hidden code in markup, as countable identities: code elements (script, style, noscript, template, object, embed, applet, frames) by tag, attributes and text; and any other element carrying an inline handler, srcdoc or an executable URL by its tag and attributes. JSON-LD data is not code. Custom JavaScript (data-ke-js) is not hidden.

Source location: includes/element-js.php:809.

cantata_edit_element_js_core_write_refusal#

function cantata_edit_element_js_core_write_refusal( int $id, string $content ): string

The built-page core-write guard: '' when $content may be written to built post $id, else the reason. Outside Kindly's internal writes, a built page may keep hidden code it already has (content or its editor draft), but not gain or multiply any, whoever writes (administrators included: new behavior goes through Developer > Advanced or the explicit Advanced code API). Pages that are not built keep their WordPress owner and are never checked here.

Implementation connections: cantata_edit_element_js_hidden_identities, cantata_edit_element_js_internal, cantata_edit_element_js_publishing_draft.

Source location: includes/element-js.php:848.

cantata_edit_element_js_raw_content#

function cantata_edit_element_js_raw_content( ?string $set = null ): ?string

The raw content of the write in progress, before kses can strip what it would refuse (content_save_pre, first).

Implementation connections: cantata_edit_element_js_contract_violations, cantata_edit_element_js_core_write_refusal, cantata_edit_element_js_values, cantata_edit_element_js_verify.

Source location: includes/element-js.php:866.

cantata_edit_native_application_behavior_sources#

function cantata_edit_native_application_behavior_sources(): array

Installed application PHP may register its public plugin JavaScript for read-only provenance. Unlike the theme configuration, this list comes only from trusted native PHP, never page content or a browser request. A source is relative to wp-content (plugins//.js), resolves inside that installed plugin and is already public. No source is read or executed here, and registration grants no Custom JavaScript or server-code authority.

Source location: includes/element-js.php:959.

cantata_edit_native_behavior_sources#

function cantata_edit_native_behavior_sources(): array

Registered native behavior uses public theme or application code and native controls, never executable authority.

Implementation connections: cantata_edit_config, cantata_edit_native_application_behavior_sources.

Source location: includes/element-js.php:981.

About this page

Documents Kindly Edit 0.9.16. Source: includes/element-js.php. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.