feat(documents): live-cursor presence heartbeat is unbuilt

[Adron]

Deferred from PR #70 (G24), recorded during the 2026-09-13 tracker reconciliation.

Scope

Two routes the Documents feature does not call:

• POST /api/documents/{id}/presence — announce/refresh presence
• DELETE /api/documents/{id}/presence — clear it

These back the web's live-collaborator indicator on a shared document.

Why it was deferred

G24's acceptance criteria were the tree, public documents, create-in-folder and move-to-folder. Presence is a genuinely separate feature with its own lifecycle problems, and bolting it onto that PR would have widened the review for no gain.

What makes this more than two calls

The routes are trivial; the lifecycle is where the work is:

• Heartbeat cadence — how often to POST, and what the server's expiry window is. Unknown; needs a probe or a backend answer.
• Teardown on every exit path — closing the editor, closing the window, quitting, sleeping, losing the network. A missed DELETE leaves a ghost collaborator on other people's screens, which is worse than showing nobody.
• App lifecycle — presence should stop when the app is backgrounded or the machine sleeps, not keep announcing a user who walked away.
• Read model — presence is only useful if the client can also read who else is present; confirm which route supplies that before building the write half alone.

Suggested sequencing

Worth doing after the account cluster (#44/#47/#46/#45), not before. It is polish on a collaboration surface whose more basic gaps are already tracked, and it is the kind of feature that looks broken when half-built.

Acceptance

• Presence announced on open, refreshed on a confirmed cadence, cleared on every exit path including crash-adjacent ones.
• Other collaborators render from the read side.
• A ghost-presence regression test: force-quit mid-session, assert the entry expires.

[Adron]

Recon done — the read-side worry is resolved, and one capture is all that is left

This issue's main hesitation was: "presence is only useful if the client can also read who else is present; confirm which route supplies that before building the write half alone."

Answered, and the answer is good. Probed 2026-09-15:

GET     /api/documents/{id}/presence  → 405
OPTIONS /api/documents/{id}/presence  → Allow: DELETE, OPTIONS, POST

There is no GET — and there does not need to be. The POST's own summary in the live spec is:

"Combined heartbeat + poll for the self-hosted live-cursor feature."

The POST is the read side. It writes your heartbeat and returns the peers in one round trip. So there is no write-half-alone risk and nothing to wait for on that front. DELETE is "Explicit 'leave' so the caller's caret disappears for peers immediately."

Both ops: x-auth-type: sync-token, x-subscription-tier: free. Bearer-reachable, ungated.

The cadence question is answered too — by the list-grid twin

This issue notes the heartbeat cadence and expiry window are unknown. Neither appears anywhere in the documents-presence spec entry. But there is a sibling route, POST /api/lists/{id}/data/versions — "Combined freshness poll and presence heartbeat for the grid" — which is documented in /help/api/lists, and states a policy:

"The first-party grid polls every 10s while the tab is visible and something is changing, backs off to 60s when nothing is, stops after 10 minutes without interaction, and stops entirely on a list nobody shares."

"The database behind this bills for being awake and does not autosuspend while anything polls it. A client that ignores those is a standing cost on someone else's bill."

That last line should govern the implementation. It is the strongest argument for getting the teardown-on-every-exit-path right that this issue already worries about — a ghost collaborator is not just ugly, it is billable.

The DocumentPresence schema exists

id · documentId · userId (all required)
cursorAnchor: [integer, null]  ·  cursorHead: [integer, null]
updatedAt · createdAt (required)

Cursor position is a flat integer offset pair, not line/column. Useful to know before designing the read model.

What we need from you — one sanctioned write

The POST's request and response bodies are unmodelled in the spec ({"type":"object"}, "not individually modelled yet") and cannot be read from a GET, because there is no GET. The DocumentPresence schema and the list-grid analogue are hints, not observed wire shapes — building fixtures from them is precisely what produced the G21, G25 and #85 silent-decode defects.

I did not POST presence during recon because it would announce a phantom collaborator on a real document.

So: may I make one deliberate presence POST against a test-account document, immediately followed by the DELETE leave? It would be visible to nobody — the account has 5 documents, all private and unshared — and it is the only way to capture the two shapes this needs. Say yes and this becomes buildable in one pass.

Alternatively, paste a captured request/response pair from the web client's own presence call and I will build against that.

[Adron]

Probed the write half (2026-09-17) — envelopes confirmed, one unknown left

I made the sanctioned POST + immediate leave against a private, unshared test-account document. Here is everything it settled, and the one thing it could not.

Confirmed live

POST   /api/documents/{id}/presence   → 200 {"users":[],"version":1}
DELETE /api/documents/{id}/presence   → 200 {"ok":true}

Both x-auth-type: sync-token, x-subscription-tier: free.

The request body is ignored. {}, {"cursorAnchor":12,"cursorHead":20} and {"since":1} all return 200 with an identical response. So the DocumentPresence schema's cursorAnchor/cursorHead are not settable through this route as named — or the route accepts and discards them. Either way, a client cannot currently publish a caret position, which is most of what "live-cursor" means.

version did not move across repeated calls on an unedited document. Whether it is a poll cursor (as the list-grid twin's versions route uses) or a static schema version is unresolved — distinguishing them needs a concurrent edit.

The one blocker that remains

users[] is always empty for the caller. That is not a bug — it matches the list-grid twin's documented behaviour: "Others currently present, never including you."

So a single account can never observe a populated row, and the users[] element shape — the thing the read half renders — stays unobserved.

Why I did not build the write half anyway

This issue says it plainly: "it is the kind of feature that looks broken when half-built." I agree, and the probe reinforces it rather than softening it:

• A heartbeat with no readable peer list means the macOS user sees nothing at all. The feature would be invisible to the person who enabled it and only observable by web users.
• The caret position — the actual point of live cursors — cannot be published through this route as it currently behaves.
• Decoding users[] against a guessed row shape is exactly the failure that produced G21 link metadata, G25 org members and bug(lists): the schema wire contract is a DSL string client-side and an object server-side — create, read and save are all broken #85. Three is enough.

What we need from you — the same second account #76 and #77 need

One other account open on a shared document at the same time produces the populated users[] row, and with it the whole read half.

That is now the third issue blocked on one thing:

Issue	Needs
#76	a populated DM items[]
#77	a DM notification row
#78	a populated presence users[]

A second recon account resolves all three. It is the highest-leverage thing on the entire blocked list.

Also worth asking the backend, alongside #58

Two questions the probe raised that only the API owner can answer:

1. Is there a way to publish a caret position? DocumentPresence declares cursorAnchor/cursorHead, and the POST appears to ignore both.
2. Is version a poll cursor? If it is, the client should send it back and back off when unchanged — the list-grid twin's route documents exactly that pattern, and its help page warns that "the database behind this bills for being awake and does not autosuspend while anything polls it."

Without answer 2, any cadence this client picks is a guess against someone else's bill.