Add element live users and update APIs

[spencerc99]

Summary

• add live, users, setLive, getLive, and getUsers for element-scoped per-user data
• add update as the preferred imperative renderer and run it for shared data and live-user changes
• keep the awareness and updateElement spellings as deprecated compatibility aliases, with errors when both alias names are supplied
• expose the same live-user model through React render props
• update public docs, both starters, the element-building skill, tests, and changesets

Why

Element-scoped presence previously required separate awareness callbacks and raw value collections. The new API gives each renderer one model: live is my ephemeral value, users joins every current value with its user identity, and update renders both shared data and user changes.

This is the core element naming/render slice from #289. Page-level Users live channels, cursor renderer changes, data/useData, read tracking, drag/onClick cleanup, awareness fallback removal, and teardown renames remain out of scope.

Verification

• bun run -C packages/playhtml test equivalent from the package directory: 538 tests passed
• bun run -C packages/react test equivalent from the package directory: 57 tests passed, including type and real-core integration tests
• bun run build-packages
• bun run lint
• bun run -C apps/docs build equivalent from the docs directory
• bunx vite build in templates/react-starter
• real-browser verification of the docs, React starter, and a temporary HTML starter using the locally built unreleased package
• both starter hover examples changed from 0 here to 1 here; fresh starter tabs had no console errors

Part of #289.

[pkg-pr-new]

Open in StackBlitz

bun add https://pkg.pr.new/@playhtml/common@430

bun add https://pkg.pr.new/playhtml@430

bun add https://pkg.pr.new/@playhtml/react@430

commit: c6708d1

[spencerc99]

Preview evidence

Element live/users documentation and both starters use one per-user rendering model.

Open preview · Review all evidence · Commit 25829f5

Vanilla live users guide

The custom-elements guide now explains live, users, setLive, and one update renderer with a complete vanilla HTML example.

Open captured page · 1280×720

React starter live hover

Hovering the React reaction button publishes live state and renders one current user.

Open captured page · 1280×720

Vanilla starter live hover

The vanilla starter uses the same live/users API and renders one current user while hovered.

Open captured page · 1280×720

_{Published by PR Evidence. Media is temporary and is removed after retention expires.}

[cloudflare-workers-and-pages]

Deploying playhtml with    Cloudflare Pages

Latest commit:	c6708d1
Status:	✅  Deploy successful!
Preview URL:	https://1e1d9b07.playhtml.pages.dev
Branch Preview URL:	https://cx-element-live-users-update.playhtml.pages.dev

View logs

[cloudflare-workers-and-pages]

Deploying we-were-online-website with    Cloudflare Pages

Latest commit:	c6708d1
Status:	✅  Deploy successful!
Preview URL:	https://51c6c99b.we-were-online-website.pages.dev
Branch Preview URL:	https://cx-element-live-users-update.we-were-online-website.pages.dev

View logs

[spencerc99]

Code review

• High: Element users can stay empty or stale when identity arrives after live data (packages/playhtml/src/index.ts:1971): getElementUsers joins the live-value map against usersAPI.getAll() only while an element-awareness update is rendering. The users module receives Yjs identity changes independently, and this PR does not subscribe element renderers to usersAPI.onChange. The presence socket can therefore deliver a remote element value before the Yjs identity state. That render omits the user, and the later identity arrival does not render the element again, so the user stays missing until some unrelated live value changes. The same ordering can leave a changed name or color stale. Refresh the element render path when the users snapshot changes, or join identity and live data from one authoritative feed. Add coverage where socket live data arrives before the Yjs identity.

[spencerc99]

Code review

No issues found. Verified the changes addressing the previous review findings.