@cloudflare/realtimekit-react 1.2.4 → 1.2.5-staging.3

package/AGENTS.md

@@ -0,0 +1,45 @@
+# react/ — @cloudflare/realtimekit-react
+
+Thin React wrapper (~2 source files) around `@cloudflare/realtimekit` providing a context provider, lifecycle hook, selector hook, and media pre-init utility.
+
+## PUBLIC API
+
+| Export | File | Purpose |
+|--------|------|---------|
+| `RealtimeKitProvider` | `src/context.tsx` | Context provider; renders `fallback` when `value` is falsy |
+| `useRealtimeKitMeeting()` | `src/context.tsx` | Returns `{ meeting: RTKClient }`; throws outside provider |
+| `useRealtimeKitClient(params?)` | `src/index.ts` | Manages client lifecycle; returns `[client, initClient]` |
+| `useRealtimeKitSelector(selector)` | `src/index.ts` | Extracts + subscribes to a slice of `RTKClient` state |
+| `initRTKMedia(options?, skipAwaits?, cachedUserDetails?)` | `src/index.ts` | Pre-inits media before `RTKClient.init`; wraps `RTKClient.initMedia` |
+
+## REACTIVITY MODEL
+
+`RealtimeKitProvider` creates an `RTKUpdates` instance (internal class, `src/context.tsx:12`) that attaches wildcard `'*'` listeners to every major SDK sub-module (`self`, `meta`, `participants`, `participants.joined/active/waitlisted`, `stage`, `livestream`, `chat`, `plugins.all`, `recording`, `connectedMeetings`, `polls`). Any event on any sub-module fans out to all registered `RTKUpdates` listeners.
+
+`useRealtimeKitSelector` has two subscription modes:
+1. **Direct** — if `selector(meeting)` returns an object with `addListener`, subscribes `'*'` on that object directly (e.g. `meeting.participants.joined`).
+2. **Global fallback** — otherwise subscribes to the `RTKUpdates` bus.
+
+Re-renders use a `useReducer` counter (`forceUpdate`) to bypass React's shallow-equality bailout when the same object reference is mutated.
+
+`shouldUpdate` (`src/index.ts:125`) gates re-renders: fires if reference differs, or if both sides are arrays with different lengths.
+
+## WHERE TO LOOK
+
+| Task | Location |
+|------|---------|
+| Provider + `useRealtimeKitMeeting` | `src/context.tsx` |
+| `useRealtimeKitClient`, `useRealtimeKitSelector`, `initRTKMedia` | `src/index.ts` |
+| All re-exported core types | `src/index.ts:177–238` |
+| Demo app (Chat, Meeting, Participants) | `example/` |
+| Publish-time `package.json` rewrite | `prepublish.js` |
+
+## GOTCHAS
+
+- **100ms null-flash on `meetingChanged`** (`src/index.ts:108`): `useRealtimeKitClient` sets `client` to `undefined` then restores the new client after 100ms via `setTimeout`. This is intentional — React won't re-render when an object reference changes to a same-shape new object. Any UI reading `client` will briefly see `undefined`.
+
+- **`cachedUserDetails` is experimental** (`src/index.ts:61`): The third param to `initRTKMedia` skips blocking network calls (chat, polls, etc.) using cached data. Not production-hardened; may silently miss fresh data.
+
+- **`prepublish.js` rewrites `package.json`** before npm publish: pins `@cloudflare/realtimekit` dependency to the exact build version, strips dev scripts, sets `private: false`, and rewrites `publishConfig.tag` based on the `ENVIRONMENT` env var (`staging` → `tag: "staging"`, else `latest`). Never manually edit the published `package.json`.
+
+- **`RTKUpdates.clean()` is called on provider unmount** but only via `updatesRef.current` — note `updatesRef` is never assigned in `context.tsx` (the `useRef` is unused). `setUpdates` state is what propagates `updates` to context; the `clean()` call on unmount uses the stale ref and is a no-op. Wildcard listeners are not removed on `value` change.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cloudflare/realtimekit-react",
-    "version": "1.2.4",
+    "version": "1.2.5-staging.3",
     "description": "A real-time video and audio SDK for building custom, collaborative communication experiences.",
     "main": "./dist/index.cjs.js",
     "module": "./dist/index.es.js",
@@ -17,14 +17,13 @@
     },
     "private": false,
     "dependencies": {
-        "@cloudflare/realtimekit": "1.2.4"
+        "@cloudflare/realtimekit": "1.2.5-staging.3"
     },
     "peerDependencies": {
         "react": ">=16.8.6"
     },
     "publishConfig": {
-        "access": "public",
-        "tag": "latest"
+        "tag": "staging"
     },
     "scripts": {
         "postpublish": "mv package.json.bak package.json"