Implement a lock mechanism for Site Editor templates (wp_template, wp_template_part) similar to the existing Heartbeat-based post locking system.

[sparshie]

Currently, the WordPress Heartbeat API provides a reliable post locking mechanism for standard post types (e.g., post, page, article) where a postID is available. This prevents concurrent editing and ensures content integrity.

However, this mechanism does not function correctly for Site Editor entities such as wp_template and wp_template_part. Since these are managed through the Site Editor and do not follow the traditional post editing flow, the default locking behavior fails, leading to potential conflicts when multiple users edit the same template simultaneously.

This creates a gap in collaborative editing workflows, especially for teams working extensively with Full Site Editing (FSE).

A custom solution has been identified to address this limitation by introducing a lock mechanism tailored for Site Editor entities. The proposed approach ensures:

Proper identification and locking of wp_template and wp_template_part entities
Prevention of simultaneous edits across multiple users
Consistent behavior aligned with the existing Heartbeat-based locking system

Further implementation details and validation of the solution can be provided.

[sparshie]

Docs for the Lock Mechanism

[westonruter]

And I presume this post locking should not be enforced in favor of real-time collaboration (RTC) when that is enabled. See ​https://github.com/WordPress/gutenberg/issues/76985

Since I also assume this will be part of the next major release, I'm milestoning accordingly.

[sparshie]

Replying to westonruter:

And I presume this post locking should not be enforced in favor of real-time collaboration (RTC) when that is enabled. See ​https://github.com/WordPress/gutenberg/issues/76985

Since I also assume this will be part of the next major release, I'm milestoning accordingly.

Thanks for the feedback and for updating the milestone.

I wanted to provide more context on why this change is needed.

On our implementation, we transitioned certain editorial workflows from a custom post type to wp_template (Site Editor). In this setup, the existing post locking mechanism does not apply, as it relies on traditional postId-based locking. As a result, multiple users can edit the same template simultaneously without any warning, which has led to unintended overwrites and loss of changes.

To address this, I implemented a lock mechanism similar to the existing Heartbeat-based post locking, adapted for entity-based editing used by the Site Editor. This ensures:

• Users are notified when another user is editing the same template
• A soft-lock experience with options to either take over or exit
• Prevention of silent overwrites in non-collaborative scenarios

Regarding real-time collaboration (RTC):
I agree that locking should not be enforced when RTC is enabled. The implementation is designed to be conditional, so locking is disabled when collaborative editing is active and only applied as a fallback where RTC is not available.

I’ve attached a patch to this ticket with the proposed approach and would appreciate feedback on:

• Whether this aligns with the intended direction for entity-based editing
• The approach for detecting and deferring to RTC
• UX expectations (soft lock vs strict enforcement)

This solution is currently being validated in production on our end.

Thanks again for the guidance.

[sparshie]

Adds a lock mechanism for wp_template and wp_template_part in the Site Editor, where traditional post locking does not apply. Includes conditional disabling when real-time collaboration (RTC) is active.

Implements post locking for Site Editor template entities (wp_template, wp_template_part) using the same Heartbeat flow as the classic editor: wp-refresh-post-lock on send, existing wp_refresh_post_lock handling on the server, and the shared #post-lock-dialog markup from _admin_notice_post_locked().

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

## Approach

• REST: On rest_prepare_wp_template / rest_prepare_wp_template_part with context=edit, acquire a lock via wp_set_post_lock() when allowed.
• Opt-out: New filter wp_apply_site_editor_post_lock (documented in wp-admin/includes/post.php) so real-time collaboration can disable locking consistently.
• Site Editor screen: Resolve the edited template from URL params; handle get-post-lock + nonce for take-over; enqueue Heartbeat + site-editor-post-lock and localize lock/takeover data.
• JS: site-editor-post-lock.js tracks the active template via core/edit-site, sends the same Heartbeat payload as wp-admin/js/post.js, and shows/refreshes the lock dialog on tick.