Block Hooks currently do not respect the "multiple": false setting: If this is set in a prospective hooked block's block.json, and there's already an instance of that block present in a given context (i.e. template, template part, pattern, or navigation menu), then Block Hooks should not insert another instance of that block.

In a similar vein, if no other instance of that block is present in the given context, then Block Hooks should insert only one instance of that block -- i.e. the first time a matching anchor block is encountered, but not for any other matching anchor blocks.

This will help extenders avoid checking for the presence of another instance of their hooked block inside of the hooked_block_types filter, which is called for every block found in a given context -- thus introducing an unnecessary performance overhead.

Implementation notes

This is implemented in apply_block_hooks_to_content -- which as of 59101 is the main entrypoint for applying Block Hooks to block markup -- as follows:

First, we iterate over all "statically" registered hooked blocks (i.e. via a block.json's blockHooks field) and check for each of them if it has multiple set to false. If it does, and if there's already an instance of the block present in the markup, then we remove the block from the list of hooked blocks passed to the Block Hooks logic. Otherwise (i.e. if multiple is true, or if the block is not present in the markup), we cache the value of its multiple field in the $block_allows_multiple_instances array.

We then create an anonymous function for use with the hooked_block_types filter, with PHP_INT_MAX as its priority. This allows us to keep track if we've already inserted one instance of a hooked block that has "multiple": false, and to also "intercept" hooked blocks that are "dynamically" added, i.e. via the hooked_block_types filter.

Architectural notes

The chosen architecture has several benefits. One, unlike most other Block Hooks related functions, apply_block_hooks_to_content gets $content as an argument (i.e. a block markup string), which means we don't have to awkwardly extract it from the $context variable (that's conteXt, not conteNt), as seen e.g. here in this alternative PR.

Two, using the hooked_block_types filter (at maximum priority) allows us to communicate both the aforementioned $content string further "down" (so we can check for the presence of the hooked block in the markup), as well as the $block_allows_multiple_instances cache. Otherwise, we'd likely have to add those as arguments to all functions along the call stack from apply_block_hooks_to_content all the way down to insert_hooked_blocks (thus also diluting separation of concerns). The present approach OTOH keeps things neatly separated.

Testing instructions

You can use the Like Button block plugin to test; the latest version (0.9.0) has "multiple": false set in its block.json.

However, note that you need to modify the plugin prior to activating it:

1. You need to disable the hooked_block_types filter that would normally auto-insert the block. (You can also do this manually via Tools > Plugin File Editor after installing the plugin -- just make sure it's before activating it!)

diff --git a/like-button.php b/like-button.php
index 67c41ca..09ef0a7 100644
--- a/like-button.php
+++ b/like-button.php
@@ -26,7 +26,7 @@ function add_like_button_block_after_post_content_block( $hooked_block_types, $r
        }
        return $hooked_block_types;
 }
-add_filter( 'hooked_block_types', 'add_like_button_block_after_post_content_block', 10, 4 );
+//add_filter( 'hooked_block_types', 'add_like_button_block_after_post_content_block', 10, 4 );
 
 function set_like_button_block_layout_attribute_based_on_adjacent_block( $hooked_block, $hooked_block_type, $relative_position, $anchor_block ) {
        // Is the hooked block adjacent to the anchor block?

2. Now activate the plugin, and use the Site Editor to insert the Like Button block into the Single template. Choose a position where the plugin would normally auto-insert it, i.e. not directly below the Post Content block. However, it needs to be inside the actual Single template, and not inside an area that's actually handled by a template part or Navigation menu. Then, save the template and verify on the frontend that the block is present where it should be.
3. Now re-enable auto-insertion, i.e. revert step 1.
4. Reload the frontend to verify that the block is indeed not auto-inserted, as it respects the `"multiple": false" setting.
5. Bonus points if you remove the "multiple": false line from block.json to verify that it will auto-insert the block if that line is not present.

Trac ticket: https://core.trac.wordpress.org/ticket/61902