From ae23c8f58bfa77a7cfefe028d594085eb3290b22 Mon Sep 17 00:00:00 2001
From: Tim Carr <tim@n7studios.co.uk>
Date: Mon, 25 May 2026 15:02:27 +0800
Subject: [PATCH 1/3] Abilities API: Restructure Content Helper

---
 includes/blocks/class-convertkit-block.php    |   8 +-
 .../class-convertkit-content-post-helper.php  | 310 ++++++++++++++++++
 ...convertkit-mcp-ability-content-delete.php} |  24 +-
 ...convertkit-mcp-ability-content-insert.php} |  28 +-
 ...s-convertkit-mcp-ability-content-list.php} |  29 +-
 ...convertkit-mcp-ability-content-update.php} |  31 +-
 .../class-convertkit-mcp-ability-content.php} |  17 +-
 wp-convertkit.php                             |  11 +-
 8 files changed, 385 insertions(+), 73 deletions(-)
 create mode 100644 includes/blocks/helpers/class-convertkit-content-post-helper.php
 rename includes/mcp/abilities/{blocks/class-convertkit-mcp-ability-block-delete.php => content/class-convertkit-mcp-ability-content-delete.php} (70%)
 rename includes/mcp/abilities/{blocks/class-convertkit-mcp-ability-block-insert.php => content/class-convertkit-mcp-ability-content-insert.php} (67%)
 rename includes/mcp/abilities/{blocks/class-convertkit-mcp-ability-block-list.php => content/class-convertkit-mcp-ability-content-list.php} (74%)
 rename includes/mcp/abilities/{blocks/class-convertkit-mcp-ability-block-update.php => content/class-convertkit-mcp-ability-content-update.php} (67%)
 rename includes/mcp/abilities/{blocks/class-convertkit-mcp-ability-block.php => content/class-convertkit-mcp-ability-content.php} (87%)

diff --git a/includes/blocks/class-convertkit-block.php b/includes/blocks/class-convertkit-block.php
index 1426f5e42..c308a1bd0 100644
--- a/includes/blocks/class-convertkit-block.php
+++ b/includes/blocks/class-convertkit-block.php
@@ -68,10 +68,10 @@ public function register_abilities( $abilities ) {
 		return array_merge(
 			$abilities,
 			array(
-				new ConvertKit_MCP_Ability_Block_List( $this ),
-				new ConvertKit_MCP_Ability_Block_Insert( $this ),
-				new ConvertKit_MCP_Ability_Block_Update( $this ),
-				new ConvertKit_MCP_Ability_Block_Delete( $this ),
+				new ConvertKit_MCP_Ability_Content_List( $this ),
+				new ConvertKit_MCP_Ability_Content_Insert( $this ),
+				new ConvertKit_MCP_Ability_Content_Update( $this ),
+				new ConvertKit_MCP_Ability_Content_Delete( $this ),
 			)
 		);
 
diff --git a/includes/blocks/helpers/class-convertkit-content-post-helper.php b/includes/blocks/helpers/class-convertkit-content-post-helper.php
new file mode 100644
index 000000000..96127cde6
--- /dev/null
+++ b/includes/blocks/helpers/class-convertkit-content-post-helper.php
@@ -0,0 +1,310 @@
+<?php
+/**
+ * ConvertKit Content Post Helper class.
+ *
+ * @package ConvertKit
+ * @author ConvertKit
+ */
+
+/**
+ * Mechanism-agnostic helper to find, insert, update and delete a Kit feature
+ * (form, broadcasts, product, etc.) within a WordPress Post's content.
+ *
+ * This is the entry point used by the Content MCP abilities. It decides how the
+ * given Post stores its content — Gutenberg blocks or Classic editor / shortcode
+ * markup — and delegates to the appropriate mechanism-specific helper:
+ *
+ * - ConvertKit_Block_Post_Helper     for block-based content.
+ * - ConvertKit_Shortcode_Post_Helper for Classic editor / shortcode content.
+ *
+ * Callers pass a feature name (e.g. `form`); this class applies the correct
+ * prefix for the chosen mechanism (`convertkit/form` for blocks,
+ * `convertkit_form` for shortcodes).
+ *
+ * Page builders (Elementor, etc.) store their content outside post_content and
+ * are not supported; a WP_Error is returned for posts built with one.
+ *
+ * @package ConvertKit
+ * @author  ConvertKit
+ */
+class ConvertKit_Content_Post_Helper {
+
+	/**
+	 * Finds all occurrences of the given Kit feature in a Post's content.
+	 *
+	 * @since   3.4.0
+	 *
+	 * @param   int    $post_id        Post ID.
+	 * @param   string $feature_name   Kit feature name (e.g. `form`), without prefix.
+	 * @return  WP_Error|bool|array
+	 */
+	public static function find( $post_id, $feature_name ) {
+
+		// Determine how this post stores its content.
+		$mechanism = self::detect_mechanism( $post_id );
+		if ( is_wp_error( $mechanism ) ) {
+			return $mechanism;
+		}
+
+		switch ( $mechanism ) {
+			case 'block':
+				return ConvertKit_Block_Post_Helper::find(
+					$post_id,
+					'convertkit/' . $feature_name
+				);
+
+			case 'shortcode':
+				return ConvertKit_Shortcode_Post_Helper::find(
+					$post_id,
+					'convertkit_' . $feature_name
+				);
+		}
+
+		return self::unsupported_mechanism_error( $mechanism );
+
+	}
+
+	/**
+	 * Inserts a new occurrence of the given Kit feature into a Post's content.
+	 *
+	 * @since   3.4.0
+	 *
+	 * @param   int    $post_id        Post ID.
+	 * @param   string $feature_name   Kit feature name (e.g. `form`), without prefix.
+	 * @param   array  $attrs          Feature attributes.
+	 * @param   string $position       One of 'prepend', 'append', 'index'.
+	 * @param   int    $index          Zero-based top-level index; only used when $position is 'index'.
+	 * @return  WP_Error|array
+	 */
+	public static function insert( $post_id, $feature_name, $attrs, $position = 'append', $index = 0 ) {
+
+		// Determine how this post stores its content.
+		$mechanism = self::detect_mechanism( $post_id );
+		if ( is_wp_error( $mechanism ) ) {
+			return $mechanism;
+		}
+
+		switch ( $mechanism ) {
+			case 'block':
+				return ConvertKit_Block_Post_Helper::insert(
+					$post_id,
+					'convertkit/' . $feature_name,
+					$attrs,
+					$position,
+					$index
+				);
+
+			case 'shortcode':
+				// The Form Builder feature is block-only; it has no shortcode.
+				if ( 'form-builder' === $feature_name ) {
+					return new WP_Error(
+						'convertkit_content_post_helper_feature_block_only',
+						__( 'The Form Builder can only be added to block-based content.', 'convertkit' )
+					);
+				}
+
+				return ConvertKit_Shortcode_Post_Helper::insert(
+					$post_id,
+					'convertkit_' . $feature_name,
+					$attrs,
+					$position,
+					$index
+				);
+		}
+
+		return self::unsupported_mechanism_error( $mechanism );
+
+	}
+
+	/**
+	 * Updates the attributes of an existing occurrence of the given Kit feature
+	 * in a Post's content.
+	 *
+	 * @since   3.4.0
+	 *
+	 * @param   int    $post_id            Post ID.
+	 * @param   string $feature_name       Kit feature name (e.g. `form`), without prefix.
+	 * @param   int    $occurrence_index   Zero-based occurrence index to update.
+	 * @param   array  $attrs              Feature attributes.
+	 * @return  WP_Error|array
+	 */
+	public static function update( $post_id, $feature_name, $occurrence_index, $attrs ) {
+
+		// Determine how this post stores its content.
+		$mechanism = self::detect_mechanism( $post_id );
+		if ( is_wp_error( $mechanism ) ) {
+			return $mechanism;
+		}
+
+		switch ( $mechanism ) {
+			case 'block':
+				return ConvertKit_Block_Post_Helper::update(
+					$post_id,
+					'convertkit/' . $feature_name,
+					$occurrence_index,
+					$attrs
+				);
+
+			case 'shortcode':
+				return ConvertKit_Shortcode_Post_Helper::update(
+					$post_id,
+					'convertkit_' . $feature_name,
+					$occurrence_index,
+					$attrs
+				);
+		}
+
+		return self::unsupported_mechanism_error( $mechanism );
+
+	}
+
+	/**
+	 * Deletes a specific occurrence of the given Kit feature from a Post's
+	 * content.
+	 *
+	 * @since   3.4.0
+	 *
+	 * @param   int    $post_id            Post ID.
+	 * @param   string $feature_name       Kit feature name (e.g. `form`), without prefix.
+	 * @param   int    $occurrence_index   Zero-based occurrence index to delete.
+	 * @return  WP_Error|array
+	 */
+	public static function delete( $post_id, $feature_name, $occurrence_index ) {
+
+		// Determine how this post stores its content.
+		$mechanism = self::detect_mechanism( $post_id );
+		if ( is_wp_error( $mechanism ) ) {
+			return $mechanism;
+		}
+
+		switch ( $mechanism ) {
+			case 'block':
+				return ConvertKit_Block_Post_Helper::delete(
+					$post_id,
+					'convertkit/' . $feature_name,
+					$occurrence_index
+				);
+
+			case 'shortcode':
+				return ConvertKit_Shortcode_Post_Helper::delete(
+					$post_id,
+					'convertkit_' . $feature_name,
+					$occurrence_index
+				);
+		}
+
+		return self::unsupported_mechanism_error( $mechanism );
+
+	}
+
+	/**
+	 * Determines how the given Post stores its content.
+	 *
+	 * Returns one of:
+	 * - 'block'      The Post uses Gutenberg blocks.
+	 * - 'shortcode'  The Post uses Classic editor / shortcode markup.
+	 * - WP_Error     The Post does not exist, or is built with an unsupported
+	 *                page builder.
+	 *
+	 * Page builders are checked first, because a page builder typically leaves
+	 * post_content empty (or a non-authoritative fallback) and stores its real
+	 * content in post meta. Writing a block or shortcode into post_content for
+	 * such a Post would have no visible effect, so we refuse rather than fail
+	 * silently.
+	 *
+	 * @since   3.4.0
+	 *
+	 * @param   int $post_id   Post ID.
+	 * @return  string|WP_Error
+	 */
+	private static function detect_mechanism( $post_id ) {
+
+		// Get Post.
+		$post = get_post( $post_id );
+		if ( ! $post ) {
+			return new WP_Error(
+				'convertkit_content_post_helper_post_not_found',
+				/* translators: %d: post ID */
+				sprintf( __( 'No post exists with ID %d.', 'convertkit' ), $post_id )
+			);
+		}
+
+		// Bail if the Post is built with a page builder, as these store their
+		// content outside post_content.
+		$page_builder = self::detect_page_builder( $post_id );
+		if ( $page_builder ) {
+			return new WP_Error(
+				'convertkit_content_post_helper_page_builder_unsupported',
+				sprintf(
+					/* translators: %s: page builder name */
+					__( 'This content is built with %s, which is not yet supported. Add the Kit feature using the page builder editor instead.', 'convertkit' ),
+					$page_builder
+				)
+			);
+		}
+
+		// Block-based content if the Post contains block markup; otherwise
+		// treat it as Classic editor / shortcode content. An empty Post also
+		// falls through to 'shortcode' — a shortcode renders correctly in
+		// both Classic and block editors, so this is a safe default.
+		return has_blocks( $post->post_content ) ? 'block' : 'shortcode';
+
+	}
+
+	/**
+	 * Returns the human-readable name of the page builder used to build the
+	 * given Post, or false if no supported page builder is detected.
+	 *
+	 * @since   3.4.0
+	 *
+	 * @param   int $post_id   Post ID.
+	 * @return  string|false
+	 */
+	private static function detect_page_builder( $post_id ) {
+
+		// Elementor stores its content in the _elementor_data post meta key,
+		// and flags edited posts via _elementor_edit_mode.
+		if ( 'builder' === get_post_meta( $post_id, '_elementor_edit_mode', true ) ) {
+			return 'Elementor';
+		}
+
+		/**
+		 * Filters the detected page builder for a Post.
+		 *
+		 * Return a non-empty string (the page builder's name) to mark the Post
+		 * as built with an unsupported page builder, causing the Content MCP
+		 * abilities to return an error rather than writing to post_content.
+		 *
+		 * @since   3.4.0
+		 *
+		 * @param   string|false $page_builder   Detected page builder name, or false.
+		 * @param   int          $post_id        Post ID.
+		 */
+		return apply_filters( 'convertkit_content_post_helper_detect_page_builder', false, $post_id );
+
+	}
+
+	/**
+	 * Returns a WP_Error for an unrecognised content mechanism. Acts as a
+	 * defensive fallback; detect_mechanism() should only ever return a known
+	 * mechanism or a WP_Error.
+	 *
+	 * @since   3.4.0
+	 *
+	 * @param   string $mechanism   The unrecognised mechanism.
+	 * @return  WP_Error
+	 */
+	private static function unsupported_mechanism_error( $mechanism ) {
+
+		return new WP_Error(
+			'convertkit_content_post_helper_unsupported_mechanism',
+			sprintf(
+				/* translators: %s: mechanism identifier */
+				__( 'Unsupported content mechanism: %s.', 'convertkit' ),
+				$mechanism
+			)
+		);
+
+	}
+
+}
diff --git a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-delete.php b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-delete.php
similarity index 70%
rename from includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-delete.php
rename to includes/mcp/abilities/content/class-convertkit-mcp-ability-content-delete.php
index 67531683b..fc21b383a 100644
--- a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-delete.php
+++ b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-delete.php
@@ -1,22 +1,22 @@
 <?php
 /**
- * Kit MCP Ability: Delete a block from a post.
+ * Kit MCP Ability: Delete a Kit Element from a post.
  *
  * @package ConvertKit
  * @author ConvertKit
  */
 
 /**
- * Ability that removes an occurrence of a Kit block from a WordPress post's
- * content.
+ * Ability that removes a single occurrence of a Kit element
+ * (Broadcast, Form, Form Trigger, Product) from a WordPress Post's content.
  *
- * Registered by a block opting in via the `convertkit_abilities` filter and
- * produces an ability named `kit/<block-name>-delete` (e.g. `kit/form-delete`).
+ * Registered by an element opting in via the `convertkit_abilities` filter and
+ * produces an ability named `kit/<element>-delete` (e.g. `kit/form-delete`).
  *
  * @package ConvertKit
  * @author  ConvertKit
  */
-class ConvertKit_MCP_Ability_Block_Delete extends ConvertKit_MCP_Ability_Block {
+class ConvertKit_MCP_Ability_Content_Delete extends ConvertKit_MCP_Ability_Content {
 
 	/**
 	 * Sets whether the ability is destructive.
@@ -51,7 +51,7 @@ public function get_label() {
 
 		return sprintf(
 			/* translators: %s: block title */
-			__( 'Delete an existing %s block from a post', 'convertkit' ),
+			__( 'Delete an existing %s element from a post', 'convertkit' ),
 			$this->block->get_title()
 		);
 
@@ -68,7 +68,7 @@ public function get_description() {
 
 		return sprintf(
 			/* translators: 1: block full name e.g. convertkit/form, 2: block title */
-			__( 'Removes a single occurrence of the %1$s (%2$s) block from the given post.', 'convertkit' ),
+			__( 'Removes a single occurrence of the %1$s (%2$s) element from the given post.', 'convertkit' ),
 			'convertkit/' . $this->block->get_name(),
 			$this->block->get_title()
 		);
@@ -91,12 +91,12 @@ public function get_input_schema() {
 				'post_id'          => array(
 					'type'        => 'integer',
 					'minimum'     => 1,
-					'description' => __( 'ID of the post containing the block.', 'convertkit' ),
+					'description' => __( 'ID of the post containing the element.', 'convertkit' ),
 				),
 				'occurrence_index' => array(
 					'type'        => 'integer',
 					'minimum'     => 0,
-					'description' => __( 'The zero-based occurrence index of the block to delete.', 'convertkit' ),
+					'description' => __( 'The zero-based occurrence index of the element to delete.', 'convertkit' ),
 				),
 			),
 		);
@@ -127,8 +127,8 @@ public function execute_callback( $input ) {
 		// Get occurrence index.
 		$occurrence_index = isset( $input['occurrence_index'] ) ? (int) $input['occurrence_index'] : 0;
 
-		// Delete block from post.
-		return ConvertKit_Block_Post_Helper::delete( $post_id, 'convertkit/' . $this->block->get_name(), $occurrence_index );
+		// Delete the element from the post.
+		return ConvertKit_Content_Post_Helper::delete( $post_id, $this->block->get_name(), $occurrence_index );
 
 	}
 
diff --git a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-insert.php b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-insert.php
similarity index 67%
rename from includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-insert.php
rename to includes/mcp/abilities/content/class-convertkit-mcp-ability-content-insert.php
index c76b30edd..5c14151f7 100644
--- a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-insert.php
+++ b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-insert.php
@@ -1,22 +1,22 @@
 <?php
 /**
- * Kit MCP Ability: Insert a block into a post.
+ * Kit MCP Ability: Insert a Kit Element into a post.
  *
  * @package ConvertKit
  * @author ConvertKit
  */
 
 /**
- * Ability that inserts an occurrence of a Kit block into a WordPress post's
- * content.
+ * Ability that inserts a single occurrence of a Kit element
+ * (Broadcast, Form, Form Trigger, Product) within a WordPress Post's content.
  *
- * Registered by a block opting in via the `convertkit_abilities` filter and
- * produces an ability named `kit/<block-name>-insert` (e.g. `kit/form-insert`).
+ * Registered by an element opting in via the `convertkit_abilities` filter and
+ * produces an ability named `kit/<element>-insert` (e.g. `kit/form-insert`).
  *
  * @package ConvertKit
  * @author  ConvertKit
  */
-class ConvertKit_MCP_Ability_Block_Insert extends ConvertKit_MCP_Ability_Block {
+class ConvertKit_MCP_Ability_Content_Insert extends ConvertKit_MCP_Ability_Content {
 
 	/**
 	 * Returns the verb this ability represents.
@@ -42,7 +42,7 @@ public function get_label() {
 
 		return sprintf(
 			/* translators: %s: block title */
-			__( 'Insert a %s block into a post', 'convertkit' ),
+			__( 'Insert a %s element into a post', 'convertkit' ),
 			$this->block->get_title()
 		);
 
@@ -59,7 +59,7 @@ public function get_description() {
 
 		return sprintf(
 			/* translators: 1: block full name e.g. convertkit/form, 2: block title */
-			__( 'Inserts a new %1$s (%2$s) block into the given post\'s content. The block can be appended (default), prepended, or positioned relative to an existing block using a zero-based index.', 'convertkit' ),
+			__( 'Inserts a new %1$s (%2$s) element into the given post\'s content. The element can be appended (default), prepended, or positioned relative to an existing element using a zero-based index.', 'convertkit' ),
 			'convertkit/' . $this->block->get_name(),
 			$this->block->get_title()
 		);
@@ -82,22 +82,22 @@ public function get_input_schema() {
 				'post_id'  => array(
 					'type'        => 'integer',
 					'minimum'     => 1,
-					'description' => __( 'Page / Post / Custom Post Type ID to insert the block into.', 'convertkit' ),
+					'description' => __( 'Page / Post / Custom Post Type ID to insert the element into.', 'convertkit' ),
 				),
 				'position' => array(
 					'type'        => 'string',
 					'enum'        => array( 'append', 'prepend', 'index' ),
 					'default'     => 'append',
-					'description' => __( 'Where to insert the new block. "index" requires the "index" property.', 'convertkit' ),
+					'description' => __( 'Where to insert the new element. "index" requires the "index" property.', 'convertkit' ),
 				),
 				'index'    => array(
 					'type'        => 'integer',
 					'minimum'     => 0,
-					'description' => __( 'When position is "index", the zero-based top-level block index at which to insert the new block.', 'convertkit' ),
+					'description' => __( 'When position is "index", the zero-based top-level element index at which to insert the new element.', 'convertkit' ),
 				),
 				'attrs'    => array(
 					'type'        => 'object',
-					'description' => __( 'Block attributes.', 'convertkit' ),
+					'description' => __( 'Element attributes.', 'convertkit' ),
 					'properties'  => $this->get_input_schema_properties(),
 				),
 			),
@@ -131,8 +131,8 @@ public function execute_callback( $input ) {
 		$position = isset( $input['position'] ) ? (string) $input['position'] : 'append';
 		$index    = isset( $input['index'] ) ? (int) $input['index'] : 0;
 
-		// Insert block into post.
-		return ConvertKit_Block_Post_Helper::insert( $post_id, 'convertkit/' . $this->block->get_name(), $attrs, $position, $index );
+		// Insert the element into the post.
+		return ConvertKit_Content_Post_Helper::insert( $post_id, $this->block->get_name(), $attrs, $position, $index );
 
 	}
 
diff --git a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-list.php b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-list.php
similarity index 74%
rename from includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-list.php
rename to includes/mcp/abilities/content/class-convertkit-mcp-ability-content-list.php
index 2d23b5ac8..d68e6d784 100644
--- a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-list.php
+++ b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-list.php
@@ -1,22 +1,22 @@
 <?php
 /**
- * Kit MCP Ability: List blocks in a post.
+ * Kit MCP Ability: List Kit Elements in a post.
  *
  * @package ConvertKit
  * @author ConvertKit
  */
 
 /**
- * Ability that lists all occurrences of a given Kit block within a WordPress
- * post's content.
+ * Ability that lists all occurrences of a given Kit element
+ * (Broadcast, Form, Form Trigger, Product) within a WordPress Post's content.
  *
- * Registered by a block opting in via the `convertkit_abilities` filter and
- * produces an ability named `kit/<block-name>-list` (e.g. `kit/form-list`).
+ * Registered by an element opting in via the `convertkit_abilities` filter and
+ * produces an ability named `kit/<element>-list` (e.g. `kit/form-list`).
  *
  * @package ConvertKit
  * @author  ConvertKit
  */
-class ConvertKit_MCP_Ability_Block_List extends ConvertKit_MCP_Ability_Block {
+class ConvertKit_MCP_Ability_Content_List extends ConvertKit_MCP_Ability_Content {
 
 	/**
 	 * Sets whether the ability is readonly.
@@ -60,7 +60,7 @@ public function get_label() {
 
 		return sprintf(
 			/* translators: %s: block title */
-			__( 'List %s blocks in a post', 'convertkit' ),
+			__( 'List %s elements in a post', 'convertkit' ),
 			$this->block->get_title()
 		);
 
@@ -77,7 +77,7 @@ public function get_description() {
 
 		return sprintf(
 			/* translators: 1: block full name e.g. convertkit/form, 2: block title */
-			__( 'Lists every occurrence of the %1$s (%2$s) block in the given post, including each occurrence\'s zero-based index and current attribute values.', 'convertkit' ),
+			__( 'Lists every occurrence of the %1$s (%2$s) element in the given post, including each occurrence\'s zero-based index and current attribute values.', 'convertkit' ),
 			'convertkit/' . $this->block->get_name(),
 			$this->block->get_title()
 		);
@@ -136,11 +136,11 @@ public function get_output_schema() {
 							'index' => array(
 								'type'        => 'integer',
 								'minimum'     => 0,
-								'description' => __( 'Zero-based occurrence index among this block\'s appearances in the post.', 'convertkit' ),
+								'description' => __( 'Zero-based occurrence index among this element\'s appearances in the post.', 'convertkit' ),
 							),
 							'attrs' => array(
 								'type'        => 'object',
-								'description' => __( 'Block attributes for this occurrence.', 'convertkit' ),
+								'description' => __( 'Element attributes for this occurrence.', 'convertkit' ),
 							),
 						),
 					),
@@ -171,12 +171,17 @@ public function execute_callback( $input ) {
 			);
 		}
 
-		// Find blocks in post.
-		$occurrences = ConvertKit_Block_Post_Helper::find( $post_id, 'convertkit/' . $this->block->get_name() );
+		// Find element occurrences in post.
+		$occurrences = ConvertKit_Content_Post_Helper::find( $post_id, $this->block->get_name() );
 		if ( is_wp_error( $occurrences ) ) {
 			return $occurrences;
 		}
 
+		// Normalise a "no occurrences" result (false) to an empty array.
+		if ( false === $occurrences ) {
+			$occurrences = array();
+		}
+
 		// Return result.
 		return array(
 			'post_id'     => $post_id,
diff --git a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-update.php b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-update.php
similarity index 67%
rename from includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-update.php
rename to includes/mcp/abilities/content/class-convertkit-mcp-ability-content-update.php
index 5f6cc3fc0..d7c73ca47 100644
--- a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-update.php
+++ b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-update.php
@@ -1,25 +1,22 @@
 <?php
 /**
- * Kit MCP Ability: Update a block in a post.
+ * Kit MCP Ability: Update a Kit Element in a post.
  *
  * @package ConvertKit
  * @author ConvertKit
  */
 
 /**
- * Ability that updates the attributes of a single occurrence of a Kit block
- * within a WordPress post's content.
+ * Ability that updates a single occurrence of a Kit element
+ * (Broadcast, Form, Form Trigger, Product) within a WordPress Post's content.
  *
- * Registered by a block opting in via the `convertkit_abilities` filter and
- * produces an ability named `kit/<block-name>-update` (e.g. `kit/form-update`).
- *
- * By default the provided attributes are merged into the existing attributes.
- * Set `replace_all` to true to replace all attributes with the supplied set.
+ * Registered by an element opting in via the `convertkit_abilities` filter and
+ * produces an ability named `kit/<element>-update` (e.g. `kit/form-update`).
  *
  * @package ConvertKit
  * @author  ConvertKit
  */
-class ConvertKit_MCP_Ability_Block_Update extends ConvertKit_MCP_Ability_Block {
+class ConvertKit_MCP_Ability_Content_Update extends ConvertKit_MCP_Ability_Content {
 
 	/**
 	 * Sets whether the ability is idempotent.
@@ -54,7 +51,7 @@ public function get_label() {
 
 		return sprintf(
 			/* translators: %s: block title */
-			__( 'Update an existing %s block in a post', 'convertkit' ),
+			__( 'Update an existing %s element in a post', 'convertkit' ),
 			$this->block->get_title()
 		);
 
@@ -71,7 +68,7 @@ public function get_description() {
 
 		return sprintf(
 			/* translators: 1: block full name e.g. convertkit/form, 2: block title */
-			__( 'Updates the attributes of a single occurrence of the %1$s (%2$s) block in the given post. By default the provided attributes are merged into the existing attributes; set replace_all to true to replace them entirely.', 'convertkit' ),
+			__( 'Updates the attributes of a single occurrence of the %1$s (%2$s) element in the given post. By default the provided attributes are merged into the existing attributes.', 'convertkit' ),
 			'convertkit/' . $this->block->get_name(),
 			$this->block->get_title()
 		);
@@ -94,16 +91,16 @@ public function get_input_schema() {
 				'post_id'          => array(
 					'type'        => 'integer',
 					'minimum'     => 1,
-					'description' => __( 'Page / Post / Custom Post Type ID containing the existing block.', 'convertkit' ),
+					'description' => __( 'Page / Post / Custom Post Type ID containing the existing element.', 'convertkit' ),
 				),
 				'occurrence_index' => array(
 					'type'        => 'integer',
 					'minimum'     => 0,
-					'description' => __( 'The zero-based occurrence index of the block to update.', 'convertkit' ),
+					'description' => __( 'The zero-based occurrence index of the element to update.', 'convertkit' ),
 				),
 				'attrs'            => array(
 					'type'        => 'object',
-					'description' => __( 'Block attributes to update. Any attributes not provided will be left unchanged.', 'convertkit' ),
+					'description' => __( 'Element attributes to update. Any attributes not provided will be left unchanged.', 'convertkit' ),
 					'properties'  => $this->get_input_schema_properties(),
 				),
 			),
@@ -132,12 +129,12 @@ public function execute_callback( $input ) {
 			);
 		}
 
-		// Get attributes, position and index.
+		// Get attributes and occurrence index.
 		$attrs            = isset( $input['attrs'] ) && is_array( $input['attrs'] ) ? $input['attrs'] : array();
 		$occurrence_index = isset( $input['occurrence_index'] ) ? (int) $input['occurrence_index'] : 0;
 
-		// Update block into post.
-		return ConvertKit_Block_Post_Helper::update( $post_id, 'convertkit/' . $this->block->get_name(), $occurrence_index, $attrs );
+		// Update the element in the post.
+		return ConvertKit_Content_Post_Helper::update( $post_id, $this->block->get_name(), $occurrence_index, $attrs );
 
 	}
 
diff --git a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block.php b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content.php
similarity index 87%
rename from includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block.php
rename to includes/mcp/abilities/content/class-convertkit-mcp-ability-content.php
index f691e51f9..8abfcea81 100644
--- a/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block.php
+++ b/includes/mcp/abilities/content/class-convertkit-mcp-ability-content.php
@@ -1,22 +1,21 @@
 <?php
 /**
- * Kit MCP Ability: Block base class.
+ * Kit MCP Ability: Content base class.
  *
  * @package ConvertKit
  * @author ConvertKit
  */
 
 /**
- * Base class for abilities that target Kit Gutenberg blocks (e.g. convertkit/form)
- * inside a WordPress post's content.
+ * Base class for abilities that insert, update or remove a Kit element
+ * (Broadcast, Form, Form Trigger, Product) within a WordPress Post's content.
  *
- * Each subclass represents a single verb (list / insert / update / delete) and
- * works against any Kit block.
+ * Each subclass represents a single verb (list / insert / update / delete).
  *
  * @package ConvertKit
  * @author  ConvertKit
  */
-abstract class ConvertKit_MCP_Ability_Block extends ConvertKit_MCP_Ability {
+abstract class ConvertKit_MCP_Ability_Content extends ConvertKit_MCP_Ability {
 
 	/**
 	 * The block this ability operates on.
@@ -41,10 +40,10 @@ public function __construct( $block ) {
 	}
 
 	/**
-	 * Returns the ability name, derived from the block's name and the verb
+	 * Returns the ability name, derived from the Kit element's name and the verb
 	 * returned by get_verb().
 	 *
-	 * For example, the Form block's insert ability would be named `kit/form-block-insert`.
+	 * For example, the Form element's insert ability is named `kit/form-insert`.
 	 *
 	 * @since   3.4.0
 	 *
@@ -52,7 +51,7 @@ public function __construct( $block ) {
 	 */
 	public function get_name() {
 
-		return 'kit/' . $this->block->get_name() . '-block-' . $this->get_verb();
+		return 'kit/' . $this->block->get_name() . '-' . $this->get_verb();
 
 	}
 
diff --git a/wp-convertkit.php b/wp-convertkit.php
index 014ee0bcb..085628b2f 100644
--- a/wp-convertkit.php
+++ b/wp-convertkit.php
@@ -108,16 +108,17 @@
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/blocks/class-convertkit-block-form-builder-field-custom.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/blocks/class-convertkit-block-product.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/blocks/helpers/class-convertkit-block-post-helper.php';
+require_once CONVERTKIT_PLUGIN_PATH . '/includes/blocks/helpers/class-convertkit-content-post-helper.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/block-formatters/class-convertkit-block-formatter.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/block-formatters/class-convertkit-block-formatter-form-link.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/block-formatters/class-convertkit-block-formatter-product-link.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/class-convertkit-mcp-ability.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/class-convertkit-mcp.php';
-require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block.php';
-require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-list.php';
-require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-insert.php';
-require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-update.php';
-require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/blocks/class-convertkit-mcp-ability-block-delete.php';
+require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/content/class-convertkit-mcp-ability-content.php';
+require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-list.php';
+require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-insert.php';
+require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-update.php';
+require_once CONVERTKIT_PLUGIN_PATH . '/includes/mcp/abilities/content/class-convertkit-mcp-ability-content-delete.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/plugin-sidebars/class-convertkit-plugin-sidebar.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/plugin-sidebars/class-convertkit-plugin-sidebar-post-settings.php';
 require_once CONVERTKIT_PLUGIN_PATH . '/includes/pre-publish-actions/class-convertkit-pre-publish-action.php';

From 9ac58dcbda075f22e9a9def166d7c2232fd0428d Mon Sep 17 00:00:00 2001
From: Tim Carr <tim@n7studios.co.uk>
Date: Mon, 25 May 2026 15:09:56 +0800
Subject: [PATCH 2/3] PHPStan compat.

---
 .../class-convertkit-content-post-helper.php  | 55 ++++---------------
 1 file changed, 12 insertions(+), 43 deletions(-)

diff --git a/includes/blocks/helpers/class-convertkit-content-post-helper.php b/includes/blocks/helpers/class-convertkit-content-post-helper.php
index 96127cde6..68b089999 100644
--- a/includes/blocks/helpers/class-convertkit-content-post-helper.php
+++ b/includes/blocks/helpers/class-convertkit-content-post-helper.php
@@ -7,17 +7,16 @@
  */
 
 /**
- * Mechanism-agnostic helper to find, insert, update and delete a Kit feature
- * (form, broadcasts, product, etc.) within a WordPress Post's content.
+ * Mechanism-agnostic helper to find, insert, update and delete a Kit element
+ * (Broadcast, Form, Form Trigger, Product) within a WordPress Post's content.
  *
  * This is the entry point used by the Content MCP abilities. It decides how the
- * given Post stores its content — Gutenberg blocks or Classic editor / shortcode
+ * given Post stores its content — Gutenberg blocks, Classic editor / shortcode
  * markup — and delegates to the appropriate mechanism-specific helper:
  *
  * - ConvertKit_Block_Post_Helper     for block-based content.
- * - ConvertKit_Shortcode_Post_Helper for Classic editor / shortcode content.
  *
- * Callers pass a feature name (e.g. `form`); this class applies the correct
+ * Callers pass an element name (e.g. `form`); this class applies the correct
  * prefix for the chosen mechanism (`convertkit/form` for blocks,
  * `convertkit_form` for shortcodes).
  *
@@ -46,18 +45,14 @@ public static function find( $post_id, $feature_name ) {
 			return $mechanism;
 		}
 
+		// Find the element in the post, depending on the mechanism.
+		// A switch is used as shortcodes and other mechanisms will be supported in the future.
 		switch ( $mechanism ) {
 			case 'block':
 				return ConvertKit_Block_Post_Helper::find(
 					$post_id,
 					'convertkit/' . $feature_name
 				);
-
-			case 'shortcode':
-				return ConvertKit_Shortcode_Post_Helper::find(
-					$post_id,
-					'convertkit_' . $feature_name
-				);
 		}
 
 		return self::unsupported_mechanism_error( $mechanism );
@@ -84,6 +79,8 @@ public static function insert( $post_id, $feature_name, $attrs, $position = 'app
 			return $mechanism;
 		}
 
+		// Insert the element into the post, depending on the mechanism.
+		// A switch is used as shortcodes and other mechanisms will be supported in the future.
 		switch ( $mechanism ) {
 			case 'block':
 				return ConvertKit_Block_Post_Helper::insert(
@@ -93,23 +90,6 @@ public static function insert( $post_id, $feature_name, $attrs, $position = 'app
 					$position,
 					$index
 				);
-
-			case 'shortcode':
-				// The Form Builder feature is block-only; it has no shortcode.
-				if ( 'form-builder' === $feature_name ) {
-					return new WP_Error(
-						'convertkit_content_post_helper_feature_block_only',
-						__( 'The Form Builder can only be added to block-based content.', 'convertkit' )
-					);
-				}
-
-				return ConvertKit_Shortcode_Post_Helper::insert(
-					$post_id,
-					'convertkit_' . $feature_name,
-					$attrs,
-					$position,
-					$index
-				);
 		}
 
 		return self::unsupported_mechanism_error( $mechanism );
@@ -136,6 +116,8 @@ public static function update( $post_id, $feature_name, $occurrence_index, $attr
 			return $mechanism;
 		}
 
+		// Updates the existing occurrence of the element in the post, depending on the mechanism.
+		// A switch is used as shortcodes and other mechanisms will be supported in the future.
 		switch ( $mechanism ) {
 			case 'block':
 				return ConvertKit_Block_Post_Helper::update(
@@ -144,14 +126,6 @@ public static function update( $post_id, $feature_name, $occurrence_index, $attr
 					$occurrence_index,
 					$attrs
 				);
-
-			case 'shortcode':
-				return ConvertKit_Shortcode_Post_Helper::update(
-					$post_id,
-					'convertkit_' . $feature_name,
-					$occurrence_index,
-					$attrs
-				);
 		}
 
 		return self::unsupported_mechanism_error( $mechanism );
@@ -177,6 +151,8 @@ public static function delete( $post_id, $feature_name, $occurrence_index ) {
 			return $mechanism;
 		}
 
+		// Delete the element from the post, depending on the mechanism.
+		// A switch is used as shortcodes and other mechanisms will be supported in the future.
 		switch ( $mechanism ) {
 			case 'block':
 				return ConvertKit_Block_Post_Helper::delete(
@@ -184,13 +160,6 @@ public static function delete( $post_id, $feature_name, $occurrence_index ) {
 					'convertkit/' . $feature_name,
 					$occurrence_index
 				);
-
-			case 'shortcode':
-				return ConvertKit_Shortcode_Post_Helper::delete(
-					$post_id,
-					'convertkit_' . $feature_name,
-					$occurrence_index
-				);
 		}
 
 		return self::unsupported_mechanism_error( $mechanism );

From f3829e698c94959607f7fa9c3f7bbc72b291376a Mon Sep 17 00:00:00 2001
From: Tim Carr <tim@n7studios.co.uk>
Date: Mon, 25 May 2026 15:19:39 +0800
Subject: [PATCH 3/3] =?UTF-8?q?Rename=20=E2=80=98feature=E2=80=99=20to=20?=
 =?UTF-8?q?=E2=80=98element=E2=80=99=20to=20be=20consistent=20with=20other?=
 =?UTF-8?q?=20code?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../class-convertkit-content-post-helper.php  | 38 +++++++++----------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/includes/blocks/helpers/class-convertkit-content-post-helper.php b/includes/blocks/helpers/class-convertkit-content-post-helper.php
index 68b089999..cc3b867ac 100644
--- a/includes/blocks/helpers/class-convertkit-content-post-helper.php
+++ b/includes/blocks/helpers/class-convertkit-content-post-helper.php
@@ -29,15 +29,15 @@
 class ConvertKit_Content_Post_Helper {
 
 	/**
-	 * Finds all occurrences of the given Kit feature in a Post's content.
+	 * Finds all occurrences of the given Kit element in a Post's content.
 	 *
 	 * @since   3.4.0
 	 *
 	 * @param   int    $post_id        Post ID.
-	 * @param   string $feature_name   Kit feature name (e.g. `form`), without prefix.
+	 * @param   string $element_name   Kit Element name (e.g. `form`), without prefix.
 	 * @return  WP_Error|bool|array
 	 */
-	public static function find( $post_id, $feature_name ) {
+	public static function find( $post_id, $element_name ) {
 
 		// Determine how this post stores its content.
 		$mechanism = self::detect_mechanism( $post_id );
@@ -51,7 +51,7 @@ public static function find( $post_id, $feature_name ) {
 			case 'block':
 				return ConvertKit_Block_Post_Helper::find(
 					$post_id,
-					'convertkit/' . $feature_name
+					'convertkit/' . $element_name
 				);
 		}
 
@@ -60,18 +60,18 @@ public static function find( $post_id, $feature_name ) {
 	}
 
 	/**
-	 * Inserts a new occurrence of the given Kit feature into a Post's content.
+	 * Inserts a new occurrence of the given Kit Element into a Post's content.
 	 *
 	 * @since   3.4.0
 	 *
 	 * @param   int    $post_id        Post ID.
-	 * @param   string $feature_name   Kit feature name (e.g. `form`), without prefix.
-	 * @param   array  $attrs          Feature attributes.
+	 * @param   string $element_name   Kit Element name (e.g. `form`), without prefix.
+	 * @param   array  $attrs          Element attributes.
 	 * @param   string $position       One of 'prepend', 'append', 'index'.
 	 * @param   int    $index          Zero-based top-level index; only used when $position is 'index'.
 	 * @return  WP_Error|array
 	 */
-	public static function insert( $post_id, $feature_name, $attrs, $position = 'append', $index = 0 ) {
+	public static function insert( $post_id, $element_name, $attrs, $position = 'append', $index = 0 ) {
 
 		// Determine how this post stores its content.
 		$mechanism = self::detect_mechanism( $post_id );
@@ -85,7 +85,7 @@ public static function insert( $post_id, $feature_name, $attrs, $position = 'app
 			case 'block':
 				return ConvertKit_Block_Post_Helper::insert(
 					$post_id,
-					'convertkit/' . $feature_name,
+					'convertkit/' . $element_name,
 					$attrs,
 					$position,
 					$index
@@ -97,18 +97,18 @@ public static function insert( $post_id, $feature_name, $attrs, $position = 'app
 	}
 
 	/**
-	 * Updates the attributes of an existing occurrence of the given Kit feature
+	 * Updates the attributes of an existing occurrence of the given Kit Element
 	 * in a Post's content.
 	 *
 	 * @since   3.4.0
 	 *
 	 * @param   int    $post_id            Post ID.
-	 * @param   string $feature_name       Kit feature name (e.g. `form`), without prefix.
+	 * @param   string $element_name       Kit Element name (e.g. `form`), without prefix.
 	 * @param   int    $occurrence_index   Zero-based occurrence index to update.
-	 * @param   array  $attrs              Feature attributes.
+	 * @param   array  $attrs              Element attributes.
 	 * @return  WP_Error|array
 	 */
-	public static function update( $post_id, $feature_name, $occurrence_index, $attrs ) {
+	public static function update( $post_id, $element_name, $occurrence_index, $attrs ) {
 
 		// Determine how this post stores its content.
 		$mechanism = self::detect_mechanism( $post_id );
@@ -122,7 +122,7 @@ public static function update( $post_id, $feature_name, $occurrence_index, $attr
 			case 'block':
 				return ConvertKit_Block_Post_Helper::update(
 					$post_id,
-					'convertkit/' . $feature_name,
+					'convertkit/' . $element_name,
 					$occurrence_index,
 					$attrs
 				);
@@ -133,17 +133,17 @@ public static function update( $post_id, $feature_name, $occurrence_index, $attr
 	}
 
 	/**
-	 * Deletes a specific occurrence of the given Kit feature from a Post's
+	 * Deletes a specific occurrence of the given Kit Element from a Post's
 	 * content.
 	 *
 	 * @since   3.4.0
 	 *
 	 * @param   int    $post_id            Post ID.
-	 * @param   string $feature_name       Kit feature name (e.g. `form`), without prefix.
+	 * @param   string $element_name       Kit Element name (e.g. `form`), without prefix.
 	 * @param   int    $occurrence_index   Zero-based occurrence index to delete.
 	 * @return  WP_Error|array
 	 */
-	public static function delete( $post_id, $feature_name, $occurrence_index ) {
+	public static function delete( $post_id, $element_name, $occurrence_index ) {
 
 		// Determine how this post stores its content.
 		$mechanism = self::detect_mechanism( $post_id );
@@ -157,7 +157,7 @@ public static function delete( $post_id, $feature_name, $occurrence_index ) {
 			case 'block':
 				return ConvertKit_Block_Post_Helper::delete(
 					$post_id,
-					'convertkit/' . $feature_name,
+					'convertkit/' . $element_name,
 					$occurrence_index
 				);
 		}
@@ -206,7 +206,7 @@ private static function detect_mechanism( $post_id ) {
 				'convertkit_content_post_helper_page_builder_unsupported',
 				sprintf(
 					/* translators: %s: page builder name */
-					__( 'This content is built with %s, which is not yet supported. Add the Kit feature using the page builder editor instead.', 'convertkit' ),
+					__( 'This content is built with %s, which is not yet supported. Add the Kit Element using the page builder editor instead.', 'convertkit' ),
 					$page_builder
 				)
 			);