fix: register generated companion blocks before editor validation

AI assistance: OpenAI gpt-5.6-terra via OpenCode traced late companion activation past init, implemented immediate registration verification and missing-block editor contracts, and ran the SSI suite. Chris Huber remains responsible for every line.

Author: chubes4

includes/class-static-site-importer-plugin-materializer.php

@@ -210,6 +210,10 @@ public static function ensure_generated_plugin(
 		if ( false === $plan['activate'] ) {
 			// mu-plugins are always active; no activation call is required.
 			$plugin_file = (string) $descriptor['plugin_file'];
+			$registered  = self::register_generated_blocks( $descriptor, $plan );
+			if ( is_wp_error( $registered ) ) {
+				return self::failed_report( $report, $registered );
+			}
 			self::replace_active_generated_companion( $plugin_file, $report );
 			if ( function_exists( 'update_option' ) ) {
 				update_option( self::ACTIVE_COMPANION_OPTION, $plugin_file, false );
@@ -247,6 +251,10 @@ public static function ensure_generated_plugin(
 				)
 			);
 		}
+		$registered = self::register_generated_blocks( $descriptor, $plan );
+		if ( is_wp_error( $registered ) ) {
+			return self::failed_report( $report, $registered );
+		}
 		self::replace_active_generated_companion( $plugin_file, $report );
 		if ( function_exists( 'update_option' ) ) {
 			update_option( self::ACTIVE_COMPANION_OPTION, $plugin_file, false );
@@ -256,6 +264,53 @@ public static function ensure_generated_plugin(
 		return $report;
 	}
 
+	/**
+	 * Register a newly materialized companion in this request.
+	 *
+	 * WordPress activation sandbox-loads a plugin after `init` has usually run.
+	 * Generated companions register their metadata blocks on `init`, so invoke that
+	 * exact callback now and verify every emitted block is available to the editor.
+	 *
+	 * @param array<string,mixed> $descriptor Generated companion descriptor.
+	 * @param array<string,mixed> $plan       Generated companion install plan.
+	 * @return true|WP_Error
+	 */
+	private static function register_generated_blocks( array $descriptor, array $plan ) {
+		$slug        = isset( $descriptor['slug'] ) && is_string( $descriptor['slug'] ) ? $descriptor['slug'] : '';
+		$plugin_file = isset( $descriptor['plugin_file'] ) && is_string( $descriptor['plugin_file'] ) ? $descriptor['plugin_file'] : '';
+		$base_dir    = isset( $plan['base_dir'] ) && is_string( $plan['base_dir'] ) ? $plan['base_dir'] : '';
+		$callback    = str_replace( '-', '_', $slug ) . '_register_blocks';
+		$path        = '' === $base_dir || '' === $plugin_file ? '' : rtrim( $base_dir, '/\\' ) . '/' . $plugin_file;
+
+		if ( '' === $slug || '' === $path || ! is_readable( $path ) ) {
+			return new WP_Error( 'static_site_importer_companion_plugin_registration_unavailable', 'Generated companion block registration file is unavailable.' );
+		}
+		if ( ! function_exists( $callback ) ) {
+			require_once $path;
+		}
+		if ( ! is_callable( $callback ) ) {
+			return new WP_Error( 'static_site_importer_companion_plugin_registration_unavailable', sprintf( 'Generated companion %s does not expose its block registration callback.', $slug ) );
+		}
+
+		call_user_func( $callback );
+		$registry = class_exists( 'WP_Block_Type_Registry' ) ? WP_Block_Type_Registry::get_instance() : null;
+		$missing  = array();
+		foreach ( $descriptor['block_names'] ?? array() as $block_name ) {
+			if ( ! is_string( $block_name ) || '' === $block_name || ! $registry || ! $registry->is_registered( $block_name ) ) {
+				$missing[] = $block_name;
+			}
+		}
+		if ( ! empty( $missing ) ) {
+			return new WP_Error(
+				'static_site_importer_companion_plugin_registration_incomplete',
+				'Generated companion blocks were not registered before editor use.',
+				array( 'missing_block_names' => $missing )
+			);
+		}
+
+		return true;
+	}
+
 	/** Preflight registered block names before generated files are written. */
 	private static function generated_block_name_collision( array $block_names, array $descriptor ) {
 		$registry = class_exists( 'WP_Block_Type_Registry' ) ? WP_Block_Type_Registry::get_instance() : null;

lib/fixture-matrix/collectors/editor-validation.mjs

@@ -134,10 +134,18 @@ function pickCount(value, fallback) {
 }
 
 function isInvalidEditorBlock(block) {
-  if (!block || typeof block !== 'object') {
-    return false;
-  }
-  if (block.isValid === false || block.is_valid === false || block.valid === false) {
+	if (!block || typeof block !== 'object') {
+		return false;
+	}
+	// Gutenberg preserves the unavailable block's intended name on core/missing.
+	// validateBlock considers that fallback structurally valid, but it cannot be
+	// edited as the generated companion block that the import declared.
+	if ((block.name === 'core/missing' || block.block_name === 'core/missing' || block.blockName === 'core/missing')
+		&& typeof (block.originalName || block.original_name) === 'string'
+		&& (block.originalName || block.original_name).length > 0) {
+		return true;
+	}
+	if (block.isValid === false || block.is_valid === false || block.valid === false) {
     return true;
   }
   // A `validateBlock`-style result: [isValid, issues] or { isValid }.
@@ -148,7 +156,9 @@ function isInvalidEditorBlock(block) {
 }
 
 function editorInvalidBlockDiagnostic(block) {
-  const name = block.name || block.block_name || block.blockName || '';
+	const observedName = block.name || block.block_name || block.blockName || '';
+	const originalName = block.originalName || block.original_name || '';
+	const name = observedName === 'core/missing' && originalName ? originalName : observedName;
   const clientId = block.clientId || block.client_id || '';
   const selector = block.selector || (clientId ? `[data-block="${clientId}"]` : '');
   const detail = firstString([
@@ -160,13 +170,14 @@ function editorInvalidBlockDiagnostic(block) {
   ]);
   return {
     kind: EDITOR_BLOCK_INVALID_KIND,
-    block_name: name,
-    observed_block_name: name,
+		block_name: name,
+		observed_block_name: observedName,
+		...(originalName ? { original_block_name: originalName } : {}),
     selector,
     source_path: block.source_path || block.source || '',
     observed_output: firstString([block.originalContent, block.expectedContent, block.html_excerpt]),
-    message: `Editor reported block "${name || 'unknown'}" as invalid: ${detail}.`,
-  };
+		message: `Editor reported block "${name || 'unknown'}" as invalid: ${detail}.`,
+	};
 }
 
 function collectEditorCanvasInvalidGroups(payload) {

test-manifest.json

@@ -7,6 +7,7 @@
   "tests": [
     { "path": "tests/form-materializer-smoke.php", "environment": "standalone-php" },
     { "path": "tests/provider-adapter-runtime-smoke.php", "environment": "standalone-php" },
+    { "path": "tests/editor-validation-contract.test.mjs", "environment": "node" },
     { "path": "tests/host-dependency-resolver.test.mjs", "environment": "node" },
     { "path": "tests/smoke-ability-error-report-summary.php", "environment": "standalone-php" },
     { "path": "tests/smoke-ability-import-success-diagnostics.php", "environment": "standalone-php" },

tests/editor-validation-contract.test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  collectEditorValidation,
+  collectEditorValidationDiagnostics,
+} from '../lib/fixture-matrix/collectors/editor-validation.mjs';
+
+test('fails editor validation when Gutenberg substitutes core/missing for a companion block', () => {
+  const payload = {
+    schema: 'wp-codebox/editor-validate-blocks/v1',
+    results: [
+      { name: 'blocks-engine/form-select', isValid: true },
+      { name: 'core/missing', originalName: 'blocks-engine/form-input', isValid: true },
+    ],
+  };
+
+  assert.deepEqual(collectEditorValidation(payload), {
+    validation_method: 'wp.blocks.validateBlock',
+    validation_provider: 'wordpress-block-editor',
+    total_blocks: 2,
+    valid_blocks: 1,
+    invalid_blocks: 1,
+  });
+  assert.deepEqual(collectEditorValidationDiagnostics(payload), [
+    {
+      kind: 'editor_block_invalid',
+      block_name: 'blocks-engine/form-input',
+      observed_block_name: 'core/missing',
+      original_block_name: 'blocks-engine/form-input',
+      selector: '',
+      source_path: '',
+      observed_output: '',
+      message: 'Editor reported block "blocks-engine/form-input" as invalid: This block contains unexpected or invalid content.',
+    },
+  ]);
+});

tests/smoke-companion-plugin.php

@@ -150,6 +150,7 @@ function is_plugin_active( string $plugin_file ): bool {
 	function activate_plugin( string $plugin_file ) {
 		$GLOBALS['ssi_companion_active'][]    = $plugin_file;
 		$GLOBALS['ssi_companion_activated'][] = $plugin_file;
+		require_once WP_PLUGIN_DIR . '/' . $plugin_file;
 		return null;
 	}
 }
@@ -436,17 +437,16 @@ function update_option( string $name, mixed $value, bool $autoload = false ): bo
 $assert( file_exists( WP_PLUGIN_DIR . '/ssi-example-site/blocks/custom-hero/render.php' ), 'install-writes-render-php-to-disk' );
 $assert( file_exists( WP_PLUGIN_DIR . '/ssi-example-site/blocks/custom-hero/block.json' ), 'install-emits-block-json' );
 $assert( file_exists( WP_PLUGIN_DIR . '/ssi-example-site/blocks/custom-hero/editor.js' ), 'install-emits-declared-editor-asset' );
+$assert( in_array( 'example/custom-hero', WP_Block_Type_Registry::$registered, true ), 'install-registers-generated-block-before-editor-use' );
+$assert( isset( $GLOBALS['static_site_importer_companion_block_owners']['example/custom-hero'] ), 'install-records-generated-block-owner-before-editor-use' );
 $written_main = file_exists( WP_PLUGIN_DIR . '/ssi-example-site/ssi-example-site.php' ) ? (string) file_get_contents( WP_PLUGIN_DIR . '/ssi-example-site/ssi-example-site.php' ) : '';
 $assert( str_contains( $written_main, 'register_block_type' ), 'written-main-file-registers-blocks' );
 
 // A foreign registration that wins before generated plugin init must never be
 // marked as companion-owned, so a later materialization still fails closed.
 WP_Block_Type_Registry::$registered[] = 'example/custom-hero';
 $GLOBALS['static_site_importer_companion_block_owners'] = array();
-require WP_PLUGIN_DIR . '/ssi-example-site/ssi-example-site.php';
-foreach ( $GLOBALS['ssi_companion_actions']['init'] ?? array() as $callback ) {
-	call_user_func( $callback );
-}
+ssi_example_site_register_blocks();
 $assert( ! isset( $GLOBALS['static_site_importer_companion_block_owners']['example/custom-hero'] ), 'foreign-registration-before-generated-init-records-no-owner' );
 $foreign_init_collision = Static_Site_Importer_Plugin_Materializer::ensure_generated_plugin( $payload, static fn (): bool => true );
 $assert( 'failed' === ( $foreign_init_collision['status'] ?? '' ) && 'runtime_block_name_collision' === ( $foreign_init_collision['diagnostics'][0]['reason_code'] ?? '' ), 'foreign-registration-before-generated-init-blocks-refresh' );
@@ -522,12 +522,39 @@ function update_option( string $name, mixed $value, bool $autoload = false ): bo
 
 // A new site replaces the previous regular companion so document-global
 // scripts from separate imports cannot execute together.
+$GLOBALS['static_site_importer_companion_block_owners'] = array();
+WP_Block_Type_Registry::$registered = array();
 $replacement_payload = array_merge( $payload, array( 'site_slug' => 'replacement-site' ) );
 $replacement_report  = Static_Site_Importer_Plugin_Materializer::ensure_generated_plugin( $replacement_payload );
 $assert( in_array( 'ssi-example-site/ssi-example-site.php', $GLOBALS['ssi_companion_deactivated'], true ), 'replacement-deactivates-previous-companion' );
 $assert( in_array( 'replaced:ssi-example-site/ssi-example-site.php', $replacement_report['actions'] ?? array(), true ), 'replacement-reports-previous-companion' );
 $assert( 'ssi-replacement-site/ssi-replacement-site.php' === get_option( Static_Site_Importer_Plugin_Materializer::ACTIVE_COMPANION_OPTION ), 'replacement-records-current-companion-plugin' );
 
+$control_payload = array_merge(
+	$payload,
+	array(
+		'site_slug' => 'editor-controls',
+		'blocks'    => array(
+			array(
+				'name'       => 'form-select',
+				'block_json' => array( 'name' => 'blocks-engine/form-select', 'title' => 'Form Select', 'editorScript' => 'file:./editor.js' ),
+				'render'     => '<select><option>One</option></select>',
+				'assets'     => array( 'editor.js' => 'window.SSIFormSelect = true;' ),
+			),
+			array(
+				'name'       => 'form-input',
+				'block_json' => array( 'name' => 'blocks-engine/form-input', 'title' => 'Form Input', 'editorScript' => 'file:./editor.js' ),
+				'render'     => '<input type="text">',
+				'assets'     => array( 'editor.js' => 'window.SSIFormInput = true;' ),
+			),
+		),
+	)
+);
+$control_report = Static_Site_Importer_Plugin_Materializer::ensure_generated_plugin( $control_payload );
+$assert( 'installed_activated' === ( $control_report['status'] ?? '' ), 'control-companion-materializes' );
+$assert( in_array( 'blocks-engine/form-select', WP_Block_Type_Registry::$registered, true ), 'form-select-registers-before-editor-use' );
+$assert( in_array( 'blocks-engine/form-input', WP_Block_Type_Registry::$registered, true ), 'form-input-registers-before-editor-use' );
+
 // Cleanup generated fixtures.
 $cleanup = static function ( string $dir ) use ( &$cleanup ): void {
 	if ( ! is_dir( $dir ) ) {