Real-time SSE sync: handle annotation.created & annotation.deleted (from upstream #116)

[raimannma]

Concept

The SSE listener currently only consumes annotation.updated. Expand it so multiple users viewing the same page see each other's changes live: handle annotation.created (add remote annotation with dedup against our own create), keep/extend annotation.updated (existing resolved/dismissed removal + merge field edits), and add annotation.deleted (remove with exit animation). Fire the existing onAnnotationAdd / onAnnotationUpdate / onAnnotationDelete callbacks for remote events. No new props, no new API, no new deps. From upstream benjitaylor#116 by the original author.

Value

Enables real-time multi-user annotation on shared pages (the author's use case: a shared git-diff viewer). Small, self-contained, high-leverage.

Why feasible to land soon

The actual SSE change is only ~50 lines. It is the cleanest part of the PR.

Blockers in the current PR (why not cherry-pick)

• The PR's diff is ~1144 additions, of which the overwhelming majority is draw-mode code that is ALREADY MERGED on main (IconPencil, isDrawMode, drawStrokes, stroke gesture classification, marker-stagger timing tweaks). Cherry-picking re-introduces/duplicates merged code and conflicts heavily.
• The PR was authored against an older SSE handler. Current main (package/src/components/page-toolbar-css/index.tsx, ~line 1010-1075) has since grown kind-aware logic for placement and rearrange annotations inside the annotation.updated handler. A naive cherry-pick would clobber that.

Recommended clean approach

Reimplement the ~50-line concept directly against the current handler:

1. Add a handleCreated listener for annotation.created: dedup via an annotations ref AND inside the state setter (guard races), append, fire onAnnotationAdd.
2. Add a handleDeleted listener for annotation.deleted: exit animation + removal, fire onAnnotationDelete only when found.
3. Extend the existing annotation.updated handler to also merge non-removal field updates (comment edits, status transitions) while PRESERVING the current placement/rearrange kind-aware reverse-lookup logic.
4. Register/cleanup all three listeners in the existing useEffect.
   Credit: reimplements the concept from feat: handle all SSE annotation events for real-time multi-user sync benjitaylor/agentation#116.

Acceptance

• pnpm build succeeds; pnpm --filter agentation test passes (add a test that a created event with a new id appends once and a duplicate id is ignored).
• Existing placement/rearrange removal behavior on annotation.updated is preserved.

Upstream PR: benjitaylor#116

[raimannma]

Resolved by #24 (merged). Real-time SSE sync for annotation.created and annotation.deleted landed, reimplemented against the current handler per this issue's recommended approach:

• created: dedup-aware add (guards the optimistic-create echo race in addAnnotation).
• deleted: shared removeAnnotationLocally helper with exit animation; annotation.updated behavior (incl. placement/rearrange kind-aware logic) preserved.
• pnpm build and tests pass (3 new tests for dedup-on-created).

All acceptance criteria are met. One deliberate deviation to flag: the merged PR does not fire onAnnotationAdd/onAnnotationDelete for remote events (those callbacks stay scoped to local user actions, avoiding a stale-closure annotationsRef). The original concept here mentioned firing them for remote events too — if you want that, it's a small, clean follow-up. Closing as completed since the acceptance criteria are satisfied; reopen if you'd prefer to track the callback behavior here.

— automated maintenance pass