Editorial AI
Editorial AI lets you register AI-powered actions that appear inside the Gutenberg editor — in toolbars and alongside MediaPress Fields fields. Each action declares where it renders, which WordPress Ability it calls, and how it gathers input, presents results, and applies the accepted output.
For domain vocabulary (Action, Extension Point, Ability, etc.) see CONTEXT.md.
Extension Points
Section titled “Extension Points”An extension point is the location in the editor where an action renders. Use select( 'mediapress/editorial-ai' ).getExtensionPoints() to retrieve the EXTENSION_POINTS constants when registering actions.
| Constant | Value | Where it renders | Context extras |
|---|---|---|---|
EXTENSION_POINTS.TOOLBAR_TOP |
'toolbarTop' |
Top editor toolbar (post-level, next to Publish/Save) | — |
EXTENSION_POINTS.BLOCK_TOOLBAR |
'blockToolbar' |
Per-block toolbar | blockClientId — use to call updateBlockAttributes in applyEffect |
EXTENSION_POINTS.FORMAT_TOOLBAR |
'formatToolbar' |
Rich-text selection toolbar | — |
EXTENSION_POINTS.FIELD_COMPONENT |
'fieldComponent' |
Alongside a MediaPress Fields field | fieldName, fieldMetaKey — use in applyEffect to write to the field |
Registering Actions
Section titled “Registering Actions”registerAction( action )
Section titled “registerAction( action )”Registers an action. Call it inside wp.domReady() — see Registering with the WordPress data store for why, and for the optional chaining this snippet omits for brevity.
const { dispatch, select } = wp.data;const STORE_NAME = 'mediapress/editorial-ai';const EXTENSION_POINTS = select(STORE_NAME).getExtensionPoints();
dispatch(STORE_NAME).registerAction({ id: 'my-plugin/my-action', label: 'My Action', extensionPoint: EXTENSION_POINTS.TOOLBAR_TOP, abilityName: 'my-plugin/my-ability', gatherInput, presentOutput, applyEffect,});Properties
Section titled “Properties”| Property | Type | Required | Description |
|---|---|---|---|
id |
string |
Yes | Unique identifier. Use 'namespace/slug' to avoid collisions. |
label |
string |
Yes | Text shown in the dropdown. |
extensionPoint |
string |
Yes | One of the EXTENSION_POINTS values. |
abilityName |
string |
Yes | The WordPress Ability to call, in 'namespace/slug' form. |
gatherInput |
function |
Yes | Collects the payload sent to the ability. See gatherInput. |
presentOutput |
function |
Yes | Formats the raw ability response for the approval UI. See presentOutput. |
applyEffect |
function |
Yes | Runs when the editor accepts the response. See applyEffect. |
blockNames |
string[] |
No | Limits this action to specific block types (e.g. ['core/paragraph']). Empty array (default) matches all blocks. |
condition |
function |
No | Extra visibility check beyond block-name matching. See condition. |
icon |
string|Element |
No | WordPress Dashicon name (e.g. 'edit') or a React element. |
group |
string |
No | Group slug registered via registerGroup(). Actions without a group render first. |
shouldRunAbility |
function |
No | Pre-flight guard called before gatherInput. See shouldRunAbility. |
gatherInput( context )
Section titled “gatherInput( context )”Called just before the ability request to build the payload. Return a plain object or a Promise resolving to one — the resolved value is sent to the ability as the request body.
Parameters
| Name | Type | Description |
|---|---|---|
| context | object |
See below. |
Context shape
| Property | Type | Extension points | Description |
|---|---|---|---|
blockName |
string |
BLOCK_TOOLBAR, FORMAT_TOOLBAR |
The selected block type, e.g. 'core/paragraph'. Empty string on non-block surfaces. |
blockAttributes |
object |
BLOCK_TOOLBAR, FORMAT_TOOLBAR |
Attributes of the selected block. Empty object on non-block surfaces. |
extensionPoint |
string |
All | The extension point being rendered. |
blockClientId |
string |
BLOCK_TOOLBAR |
Gutenberg block client ID. |
richTextValue |
object |
FORMAT_TOOLBAR |
The current WP RichText value (.text, .start, .end). |
onRichTextChange |
function |
FORMAT_TOOLBAR |
Callback to write back a modified rich-text value. |
fieldName |
string |
FIELD_COMPONENT |
The MediaPress field name. |
fieldMetaKey |
string |
FIELD_COMPONENT |
The post meta key backing the field. |
targetKey |
string |
Regeneration only | See below. |
targetKey — single-suggestion regeneration
When your action returns a suggestions shape from presentOutput, the approval UI lets the user regenerate individual rows. On those re-runs the framework injects context.targetKey — the SuggestionItem.key for the row being regenerated.
[!NOTE]
targetKeyis not present on the initial run or on regenerate-all. Use it to narrow the ability call to only the item being regenerated.
gatherInput( context ) { const input = { postId: wp.data.select( 'core/editor' ).getCurrentPostId() };
// Narrow to one field when regenerating a single suggestion. if ( context.targetKey ) { input.fields = [ context.targetKey ]; }
return input;},presentOutput( response )
Section titled “presentOutput( response )”Transforms the raw ability response into something the approval UI can display. The return shape determines which UI the editor sees.
Parameters
| Name | Type | Description |
|---|---|---|
| response | object |
Raw JSON response from the ability. |
Return shapes
Plain text
Section titled “Plain text”The simplest shape — the approval UI shows the string and lets the editor accept or discard it.
presentOutput( response ) { return response.summary;},Text with reasoning
Section titled “Text with reasoning”Shows the text and a collapsible reasoning section.
presentOutput( response ) { return { text: response.summary, reasoning: response.reasoning, };},Multiple choice
Section titled “Multiple choice”The editor picks one option from a list; the chosen string is passed to applyEffect as selectedOption.
presentOutput( response ) { return { options: response.title_suggestions, reasoning: response.reasoning, };},Suggestions (multi-row)
Section titled “Suggestions (multi-row)”Shows a table of suggestions, each with its own accept and regenerate controls. Use this when the ability returns results for several distinct targets (e.g. multiple SEO fields or multiple blocks).
presentOutput( response ) { return { suggestions: [ { key: 'seo_title', title: 'SEO Title', suggestion: response.seo_title }, { key: 'seo_description', title: 'SEO Description', suggestion: response.seo_description }, ], reasoning: response.reasoning, };},SuggestionItem shape
| Property | Type | Description |
|---|---|---|
key |
string |
Stable identifier for this suggestion. Serves two roles: (1) passed back as context.targetKey when the user regenerates this row; (2) passed to applyEffect as selectedOption when the user accepts this row. Choose a value meaningful in both contexts — a meta field name, a block clientId, etc. |
title |
string |
Label shown in the suggestions UI. |
suggestion |
string |
The AI-generated text. |
emptyMessage |
string |
Optional. Message shown in the row when suggestion is empty or absent. |
applyEffect( response, context, selectedOption? )
Section titled “applyEffect( response, context, selectedOption? )”Runs when the editor accepts the AI response. Write the result to the block editor, post meta, or a MediaPress field here.
Parameters
| Name | Type | Description |
|---|---|---|
| response | object |
Raw ability response (same object passed to presentOutput). |
| context | object |
The same context object passed to gatherInput. |
| selectedOption | string|undefined |
The value the editor chose. Present only for options and suggestions shapes; the accepted string or SuggestionItem.key respectively. |
// Plain text — replace a block attribute.applyEffect( response, context ) { wp.data.dispatch( 'core/block-editor' ).updateBlockAttributes( context.blockClientId, { content: response.summary }, );},
// Options — user picked one title.applyEffect( response, context, selectedOption ) { wp.data.dispatch( 'core/editor' ).editPost( { title: selectedOption } );},
// Suggestions — user accepted one meta field row.applyEffect( response, context, selectedOption ) { const meta = {}; meta[ selectedOption ] = response[ selectedOption ]; wp.data.dispatch( 'core/editor' ).editPost( { meta } );},shouldRunAbility( context )
Section titled “shouldRunAbility( context )”An optional pre-flight guard called before gatherInput. Use it to block the ability call when the editor is in a state that would make the request pointless or harmful — for example, when required post meta is missing.
Parameters
| Name | Type | Description |
|---|---|---|
| context | object |
Same context object as gatherInput. |
Return values
| Return value | Effect |
|---|---|
null / undefined / true |
Allow — proceed to gatherInput and the ability call. |
false |
Block silently — no notice shown. |
ActionNotice with status: 'error' |
Block and display the notice in the approval UI. |
ActionNotice shape
| Property | Type | Description |
|---|---|---|
status |
'error'|'warning'|'info'|'success' |
Notice severity. |
children |
string|ReactNode |
Notice message content. |
isDismissible |
boolean |
Defaults to false. |
shouldRunAbility( context ) { const title = wp.data.select( 'core/editor' ).getEditedPostAttribute( 'title' );
if ( ! title ) { return { status: 'error', children: 'Add a post title before running this action.', }; }},condition( context )
Section titled “condition( context )”An optional visibility check evaluated at render time, after extension-point and block-name matching. Return false to hide the action. Errors in condition are caught and treated as false — they will not propagate.
condition( context ) { // Only show for posts with a featured image. return !! wp.data.select( 'core/editor' ).getEditedPostAttribute( 'featured_media' );},Ability requirements
Section titled “Ability requirements”The editor always calls the ability with POST and the input as a JSON body. It does not read the ability’s annotations, so the ability must not be registered as readonly: core only allows GET for readonly abilities and reads GET input from the query string only, so a POST returns a 405. Register the ability with readonly set to false.
Registering Groups
Section titled “Registering Groups”registerGroup( group )
Section titled “registerGroup( group )”Groups let you organise related actions under a labelled section in the dropdown. Actions without a group always render first, before any grouped section. As with registerAction(), call it inside wp.domReady().
Properties
| Property | Type | Description |
|---|---|---|
name |
string |
Slug used as the group value on actions. |
label |
string |
Human-readable section heading shown in the dropdown. |
const { dispatch, select } = wp.data;const STORE_NAME = 'mediapress/editorial-ai';const EXTENSION_POINTS = select(STORE_NAME).getExtensionPoints();
dispatch(STORE_NAME).registerGroup({ name: 'content-suggestions', label: 'Content Suggestions',});
dispatch(STORE_NAME).registerAction({ // ... group: 'content-suggestions',});Registering with the WordPress data store
Section titled “Registering with the WordPress data store”Actions are registered in the 'mediapress/editorial-ai' @wordpress/data store. External packages register actions and groups via wp.data.dispatch, and retrieve the EXTENSION_POINTS constants via wp.data.select.
Register inside domReady, and use optional chaining on both select and dispatch:
const { dispatch, select } = wp.data;const STORE_NAME = 'mediapress/editorial-ai';
wp.domReady(() => { const EXTENSION_POINTS = select(STORE_NAME)?.getExtensionPoints() ?? {};
dispatch(STORE_NAME)?.registerGroup({ name: 'my-plugin', label: 'My Plugin', }); dispatch(STORE_NAME)?.registerAction({ /* ... */ });});domReady runs after every enqueued editor script has evaluated, so the editorial-ai store is registered by the time your callback fires — whatever order the scripts happen to load in. Registering later than the UI is safe: the toolbar reads actions and groups reactively, so a late registration simply re-renders.
Do not declare mediapress-editorial-ai as a wp_enqueue_script dependency. WordPress drops a script entirely when a declared dependency is not registered, so doing that would make your whole editor bundle disappear whenever Editorial AI is disabled — taking your unrelated features with it. The optional chaining above is what handles that case: when Editorial AI is off, the registration is a silent no-op and the rest of your script still runs.
wp_enqueue_script( 'my-plugin-editorial-ai-actions', plugins_url( 'build/actions.js', __FILE__ ), $asset_file['dependencies'], '1.0.0', true,);Full Example
Section titled “Full Example”A complete action that suggests values for all fields in the “Titles” fields group, uses targetKey to scope regeneration per-row, and writes accepted values to the correct target — post attributes for headline and excerpt, post meta for short_headline and standfirst.
Action
Section titled “Action”const { dispatch, select } = wp.data;const STORE_NAME = 'mediapress/editorial-ai';
// headline → post_title attribute, excerpt → post_excerpt attribute (not meta).const ATTRIBUTE_FIELDS = { headline: 'title', excerpt: 'excerpt' };
const suggestTitlesAction = { id: 'my-plugin/suggest-titles', label: 'Suggest titles', // WordPress ability which is registered in php that exposes a REST endpoint we can call. abilityName: 'my-plugin/suggest-titles', group: 'my-plugin',
gatherInput(context) { const post = wp.data.select('core/editor').getCurrentPost(); const input = { post_id: post.id, content: wp.blocks.serialize( wp.data.select('core/block-editor').getBlocks(), ), fields: ['headline', 'short_headline', 'standfirst', 'excerpt'], };
// On single-row regeneration, narrow to just that field. if (context.targetKey) { input.fields = [context.targetKey]; }
return input; },
presentOutput(response) { return { suggestions: [ { key: 'headline', title: 'Headline', suggestion: response.headline }, { key: 'short_headline', title: 'Short Headline', suggestion: response.short_headline, }, { key: 'standfirst', title: 'Standfirst', suggestion: response.standfirst, }, { key: 'excerpt', title: 'Excerpt', suggestion: response.excerpt }, ], reasoning: response.reasoning, }; },
// Called once per accepted row; selectedOption is the SuggestionItem.key for that row. // headline and excerpt are post attributes, not meta — they use different editPost keys. applyEffect(response, _context, selectedOption) { const value = response[selectedOption]; if (ATTRIBUTE_FIELDS[selectedOption]) { wp.data .dispatch('core/editor') .editPost({ [ATTRIBUTE_FIELDS[selectedOption]]: value }); } else { wp.data .dispatch('core/editor') .editPost({ meta: { [selectedOption]: value } }); } },};
wp.domReady(() => { const EXTENSION_POINTS = select(STORE_NAME)?.getExtensionPoints() ?? {};
dispatch(STORE_NAME)?.registerGroup({ name: 'my-plugin', label: 'My Plugin', });
dispatch(STORE_NAME)?.registerAction({ ...suggestTitlesAction, extensionPoint: EXTENSION_POINTS.TOOLBAR_TOP, });});