Rest API/Gutenberg: Alert when an admin screen goes stale due to another user's save

[Intenzi]

Closes: #28
Follow-up to: #22

How?

This PR implements the stale-screen detection enhancements by introducing a new client-side API and a supporting REST route to handle non-redirecting, JS-driven saves:

Server-Side Changes

• Refactored the screen access gating logic from wp_presence_screen_heartbeat_received() into a new shared helper function: wp_presence_current_user_can_access_screen().
• Added a new POST endpoint /wp-presence/v1/presence/screen-revisions/stale to WP_REST_Presence_Controller.
  • It verifies permissions using the extracted helper and calls wp_presence_bump_screen_revision() to increment the revision.
• Extended the script configuration in wp_presence_enqueue_stale_screen_banner() to pass down the restUrl and the nonce to the client.

Client-Side Changes

• wp.presence.markScreenStale(): Added this new global method on the window.wp.presence namespace.
  • It performs a POST request to the new REST endpoint.

Additionally added unit tests for the bump wrapper methods success, failure and updated README with info on Stale Screen Detection.

Demo Video

8mb.video-Stale.Screen.Detection.API.mp4

Use of AI Tools

AI assistance: Yes
Tool(s): Antigravity IDE
Model(s): Gemini 3.1 Pro (Low)
Used for: Identifying relevant code files, deciding on implementation and architecture for enhancement. Unit tests were implemented via it. Final implementation and tests were reviewed and edited by me.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props intenzi, joefusco.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

▶ Preview in WordPress Playground

Boots a fresh WordPress with this PR's presence-api build, seeds 5 demo users, and drops you on the dashboard.

_{Stress-test variant: 40 demo users · Built from e6481389b0832d58975571f761705d4bd0afcd81. Auto-updates when you push.}