Commit 6650dac7ca7 for woocommerce

commit 6650dac7ca7c72b6caf2077f8bd0aa8e7f3bbd6b
Author: Thomas Roberts <5656702+opr@users.noreply.github.com>
Date:   Thu Oct 1 20:45:31 2026 +0100

    Document Checkout inner block registration requirements (#69219)

    * Document Checkout inner block registration

    * Add changelog entries for Checkout inner block documentation

diff --git a/docs/block-development/getting-started/faq.md b/docs/block-development/getting-started/faq.md
index 4690de6c566..9b4fa1e831e 100644
--- a/docs/block-development/getting-started/faq.md
+++ b/docs/block-development/getting-started/faq.md
@@ -233,4 +233,6 @@ The recommended approach to rendering fields in the Checkout block is to use the

 #### Rendering a custom block

-To render a custom block in the Checkout block, the recommended approach is to create a child block of one of the existing Checkout inner blocks. We have an example template that can be used to set up and study an inner block. To install and use it, follow the instructions in [`@woocommerce/extend-cart-checkout-block`](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/extend-cart-checkout-block/README.md). Please note that this example contains multiple other examples of extensibility, not just inner blocks.
+To render a custom block in the Checkout block, the recommended approach is to create a child block of one of the existing Checkout inner blocks. Register the block on both the server and the client. WooCommerce uses the server-registered `parent` metadata to make the block's saved attributes available to its frontend component; a block registered only in JavaScript may work in the editor but lose its attributes on the frontend.
+
+The [`@woocommerce/extend-cart-checkout-block`](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/extend-cart-checkout-block/README.md) template demonstrates the complete registration path. Please note that this example contains multiple other examples of extensibility, not just inner blocks. See the [Checkout Blocks Registry documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/blocks-registry/README.md#registering-a-block) for registration details and frontend attribute handling.
diff --git a/packages/js/extend-cart-checkout-block/README.md b/packages/js/extend-cart-checkout-block/README.md
index 9bcf4c7cc30..bf3fcfdb39b 100644
--- a/packages/js/extend-cart-checkout-block/README.md
+++ b/packages/js/extend-cart-checkout-block/README.md
@@ -20,11 +20,20 @@ When this has completed, go to your WordPress plugins page and activate the plug

 Add some items to your cart and visit the Checkout block, notice there is additional data on the block that this template has added.

-### Linting
+## Inner block registration
+
+The generated extension registers its Checkout inner block on both the server and the client. Keep both registrations when adapting the example:
+
+- Server registration allows WooCommerce to inspect the block's `parent` metadata, add the HTML `data-*` attributes used by the frontend component, and load translations.
+- Client registration makes the block available in the editor and connects its frontend component through `registerCheckoutBlock`.
+
+Registering the block only in JavaScript can appear to work in the editor while leaving the frontend component without the block's saved attributes. See the [Checkout Blocks Registry documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/blocks-registry/README.md#registering-a-block) for details.
+
+## Linting

 You can lint the project according to the [WordPress coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/) by running `npm run lint:js`. The configuration is ultimately read from the [WooCommerce recommended eslint config](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/eslint-plugin/configs/recommended.js). To modify the rules edit the `eslint.config.mjs` file.

-### Installing `wp-env` (optional)
+## Installing `wp-env` (optional)

 `wp-env` lets you easily set up a local WordPress environment for building and testing your extension. If you want to use `wp-env`, you will need to run the following command:

diff --git a/packages/js/extend-cart-checkout-block/changelog/wooplug-972-inner-block-registration-docs b/packages/js/extend-cart-checkout-block/changelog/wooplug-972-inner-block-registration-docs
new file mode 100644
index 00000000000..d628d1c04b6
--- /dev/null
+++ b/packages/js/extend-cart-checkout-block/changelog/wooplug-972-inner-block-registration-docs
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Clarify server and client registration requirements for Checkout inner blocks.
diff --git a/plugins/woocommerce/changelog/wooplug-972-inner-block-registration-docs b/plugins/woocommerce/changelog/wooplug-972-inner-block-registration-docs
new file mode 100644
index 00000000000..65dd0ae0c0e
--- /dev/null
+++ b/plugins/woocommerce/changelog/wooplug-972-inner-block-registration-docs
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Clarify how server registration makes Checkout inner block attributes available on the frontend.
diff --git a/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/blocks-registry/README.md b/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/blocks-registry/README.md
index b9a7325c3ef..82e39cbf6a4 100644
--- a/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/blocks-registry/README.md
+++ b/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/blocks-registry/README.md
@@ -48,10 +48,9 @@ See the [`innerBlockAreas`](https://github.com/woocommerce/woocommerce-blocks/bl

 ## Registering a Block

-To register a checkout block, first, register your Block Type with WordPress using <https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/>. We recommend using the `blocks.json` method to avoid
-repetition.
+Register a checkout block on both the server and the client. Client-side registration alone may make the block work in the editor, but WooCommerce cannot inspect its metadata when rendering the frontend. This can prevent saved attributes and translations from reaching the frontend component.

-When registering your block, you should also define the `parent` property to include a list of areas where your block will be available. For example:
+Define the block in `block.json` to keep the server and client registrations consistent. Include the `parent` property with the areas where the block will be available. For example:

 ```json
 {
@@ -64,6 +63,19 @@ When registering your block, you should also define the `parent` property to inc
 }
 ```

+Register the metadata on the server during `init`:
+
+```php
+add_action(
+	'init',
+	function () {
+		register_block_type_from_metadata( __DIR__ . '/build/namespace-block-name' );
+	}
+);
+```
+
+Register the same metadata on the client with [`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#registration-on-the-client). The [`@woocommerce/extend-cart-checkout-block`](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/extend-cart-checkout-block) template demonstrates both registrations.
+
 ### Registering a Forced Block

 If you want your block to appear within the layout of the Checkout without merchant intervention, you can implement locking as follows:
@@ -97,9 +109,16 @@ For your block to dynamically render on the frontend and have access to its own
 -   To render the block on the frontend, you need a `data-block-name` attribute on the HTML with your block name `namespace/block-name`.
 -   To access your attributes on frontend, you need to save them as `data-*` attributes on the HTML.

-Blocks whose namespace is `woocommerce` or `woocommerce-checkout` will have this applied to them automatically, but you can also add this behaviour to your own namespace or individual blocks.
+WooCommerce applies these attributes automatically to blocks that:
+
+- use the `woocommerce` or `woocommerce-checkout` namespace; or
+- are registered on the server with a WooCommerce block in their `parent` metadata.
+
+Server registration with accurate `parent` metadata is the recommended approach for extension blocks. No filter is needed in that case.
+
+The following experimental filters are compatibility options for blocks that cannot be registered on the server. They should not replace normal server-side block registration.

-To add this behavior to your namespace, you can use the `__experimental_woocommerce_blocks_add_data_attributes_to_namespace` filter:
+To opt in an entire namespace, use the `__experimental_woocommerce_blocks_add_data_attributes_to_namespace` filter:

 ```php
 add_filter(
@@ -113,7 +132,7 @@ add_filter(
 );
 ```

-To add just a single block, you can use `__experimental_woocommerce_blocks_add_data_attributes_to_block` filter:
+To opt in a single block, use the `__experimental_woocommerce_blocks_add_data_attributes_to_block` filter:

 ```php
 add_filter(