Announcements SDK: clean up watch ergonomics and document scan→watch composition

[marcomariscal]

Problem

The SDK now has the right low-level primitives for announcement sync (getAnnouncementsPageUsingSubgraph, streamed scan, and watchAnnouncementsForUser), but the frontend story is still awkward.

Right now watchAnnouncementsForUser is usable as a low-level primitive, but it is not especially clean in React/TanStack usage:

• the callback contract is not clearly async-friendly
• the package does not document the clean scan → watch handoff boundary
• there is no canonical React/TanStack example showing how to compose paged history with live watch without inventing a new SDK abstraction

This makes app consumers more likely to either avoid the watch helper entirely or build one-off orchestration around it.

Desired direction

Keep the SDK primitive surface small and honest:

• getAnnouncementsPageUsingSubgraph(...)
• scanAnnouncementsForUserUsingSubgraph(...)
• watchAnnouncementsForUser(...)

Do not add a phaseful follow(...) abstraction yet. The clean move here is to tighten the existing watch primitive and document composition, not introduce a mini framework into the SDK.

Scope

1) Clean up watchAnnouncementsForUser handler ergonomics

• type the handler as void | Promise<void>
• internally await handler completion
• document/define what happens on handler rejection
• add tests for async handler usage

2) Document the clean scan → watch handoff

• historical scan is pinned to a snapshotBlock
• live watch should start at snapshotBlock + 1
• docs should explicitly describe the expected no-gap/no-dup handoff shape

3) Add a React/TanStack example

Add a canonical example showing:

• local persisted announcements/accounts as the durable base
• paged history via useInfiniteQuery
• live watch patching cache after catch-up completes
• no primary refresh-button requirement in the normal UX

Non-goals

• no followAnnouncementsForUser(...) abstraction yet
• no SDK-owned storage layer
• no TanStack/Zustand/reducer-specific coupling in core primitives

Acceptance criteria

• watchAnnouncementsForUser supports async handlers cleanly
• handler completion/rejection behavior is explicit and tested
• docs define the scan → watch boundary using snapshotBlock / fromBlock
• repo includes one clean React/TanStack composition example

Related

• builds on feat: batched/streaming user announcement scan API #91, feat: explicit bounded subgraph announcement fetch API #92, and feat: support Ponder-style GraphQL pagination for subgraph announcement queries #103