Document the existing Presence API extension points

[raftaar1191]

Rewritten 2026-07-26. The original framing, that presence is backend and editor only and needs opt-in front-end extension points, is stale: includes/heartbeat.php:41-62 reports front-end presence with page titles for logged-in users whenever the admin bar shows. #17 was closed as not planned but the capability landed anyway.

@mindctrl's position on the original issue stands and is the project's: build something reliable and performant, let it soak, open it up once real use cases exist. #122 is the first of those arriving.

What is actionable now is that the extension points which already exist are undocumented:

• wp_presence_default_ttl filter (includes/functions.php:190-197)
• post_type_supports( $type, 'presence' ) as the opt-in for per-post rooms (includes/functions.php:169, registered for post and page at presence-api.php:102-105)
• wp_presence_screen_revision_bumped action (includes/screen-revisions.php:120)
• The six public functions listed at includes/functions.php:5-11, versus the private helpers below the divider at :176-181

Document these in README.md with the public/private boundary made explicit. Broader extensibility architecture stays deferred.

[mindctrl]

Good thoughts, thanks for sharing. A couple of my own thoughts:

providing structured extension points so developers can define their own presence contexts, data handling, and exposure rules.

By prioritizing extensibility over built-in features

In the long term I agree, but the initial implementation should focus on reliability and performance, not extensibility. I think extensibility architecture should be informed by real world use cases with sufficient demand. I would encourage us to build something reliable and performant first, let it soak for a bit, and then start opening it up for extensibility when we know it's suited for WP scale and have requests for real world use cases.

[westonruter]

I thought that frontend presence wasn't being reported: #17

But it turns out that presence is reported, but it takes 60 seconds for Heatbeat to tick. I think a beacon should be sent as soon as a logged-in user arrives at a page and also when the user leaves a page (#14 & #15). Otherwise, I'm finding the presence data is too stale.

[josephfusco]

Closed by #175, releasing in v0.1.14.