@urun-sh/react 0.2.23 → 0.2.24

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## Unreleased
+## 0.2.24
+
+- Docs-only release: README accuracy pass against the 0.2.23+ surface — the quick start now
+  composes `<SessionScope>` + `<Camera>`/`<Video>` (the prebaked components) instead of
+  hand-rolled track plumbing, the API section documents the component/hook surface, and the
+  retired "generative UI" framing is replaced by the component registry. No runtime changes.
+
+## 0.2.23
 
 - **Prebaked media I/O, bare-name canonical exports** (owner mandate 2026-07-13 — the UrunX
   component convention is dead): the declarative send/show surface, keyed on session stream

package/README.md

@@ -12,26 +12,21 @@ npm install @urun-sh/react @urun-sh/core
 
 ```tsx
 import '@urun-sh/react/styles.css'
-import { UrunProvider, useApp } from '@urun-sh/react'
+import { UrunProvider, useApp, SessionScope, Camera, Video } from '@urun-sh/react'
 import { UrunWorkOSProvider } from '@urun-sh/react/workos'
-import { useEffect, useRef } from 'react'
 
-function VideoPlayer() {
+function Restyle() {
   const app = useApp()
   const session = app.generate({ prompt: 'A sunset' })
-  const video = session.stream('video')
-  const videoRef = useRef<HTMLVideoElement>(null)
-
-  useEffect(() => {
-    if (video.track && videoRef.current) {
-      videoRef.current.srcObject = new MediaStream([video.track])
-    }
-  }, [video.track])
 
   return (
-    <button onClick={() => session.doc('control').set({ desired: { prompt: { text: 'A forest' } } })}>
-      Generate
-    </button>
+    <SessionScope session={session}>
+      <Camera stream="cam" front /> {/* publish the webcam → the runtime's ctx.stream("cam") */}
+      <Video stream="video" />      {/* render the runtime's video output */}
+      <button onClick={() => session.doc('control').set({ desired: { prompt: { text: 'A forest' } } })}>
+        Restyle
+      </button>
+    </SessionScope>
   )
 }
 
@@ -44,7 +39,7 @@ export default function App() {
         authProvider="workos"
         appId="my-app"
       >
-        <VideoPlayer />
+        <Restyle />
       </UrunProvider>
     </UrunWorkOSProvider>
   )
@@ -71,12 +66,33 @@ For other auth providers, use `UrunAuthProvider` with a `getAccessToken` functio
 
 ## API
 
-- `UrunProvider` — configures the app proxy.
+- `UrunProvider` — configures the app proxy (and is the auth onramp).
 - `useApp()` — returns the deployed app proxy configured by `appId`.
 - `app.<function>(args?)` — starts or reconnects a running function call and returns a render-safe session proxy.
 - `session.stream(name)` — returns a render-safe named symmetric stream (first use decides direction) with `.track`, `.attach(track)`, `.detach()`, `.seek(seconds | 'live')`, and lifecycle events.
 - `session.doc(name)` — returns a render-safe synced document with `.get()`, `.set(patch)` (write `desired.*` state), and lifecycle events.
-- `registerComponent()` and built-in components — optional generative UI support.
+
+### Prebaked media components
+
+The declarative send/show surface, keyed on the runtime's stream names. Bind one session for
+a whole subtree with `<SessionScope session={session}>` (every component also takes an
+explicit `session` prop). They own capture, the persistent `srcObject`, iOS attributes, the
+autoplay unlock, and front/back switching — hand-rolled `getUserMedia` / `.track` →
+`srcObject` effects in app code are the anti-pattern.
+
+- Send: `<Camera stream="cam" front|back visible />` (viewless unless `visible`), `<Mic stream="mic" />`.
+- Show: `<Video stream="video" />` (live inbound video), `<Image stream="image" />` (the platform image lane — H.264 intra frames), `<Audio stream="audio" controls? />`, `<Voice stream="audio" />` (full-duplex voice loop on one name).
+- VOD/recordings playback (seek/scrub): `VideoPlayer` from `@urun-sh/react/video` — video.js is an optional peer, deliberately not in the root export.
+- The `UrunAudio` / `UrunVoice` / `UrunCamera` (root) and `UrunVideo` (`/video` subpath) aliases are deprecated and removed next minor — write the bare names.
+
+### Hooks and building blocks
+
+- Session doc/data: `useDocStore`, `useSessionDoc`, `useStreamMessages`, `useSessionTrack`.
+- Continuous input (keyboard/mouse/pointer riding awareness presence): `useInputPresence(session)`.
+- Request/response over the session doc: `useRequest`, `useCompletion`, `useChat`.
+- Session honesty: `UrunSessionStatus`, `UrunSessionGate`, `UrunSessionClock`, `UrunSessionEnded`, `UrunIdleWarning`, `UrunSessionWaking`, `UrunActivationOverlay` (+ `useSessionPhase`, `useSessionEndsAt`, `useSessionIdle`, `useSessionWake`, `useActivation`).
+- Session debug workbench: `UrunStreamTail`, `UrunDocPanel`, `UrunControlSender`, `UrunEventSpine` (see `docs/session-workbench-building-blocks.md`).
+- Component registry: `registerComponent()` / `ComponentRenderer` plus the schema-validated built-ins (`ProgressCard`, `StatusBadge`, `TextStream`, `ImageFrame`, `MetricsPanel`) rendered from app-defined named data streams.
 
 ## Session docs as a zustand store
 
@@ -138,4 +154,4 @@ import '@urun-sh/react/styles.css'
 
 ## Peer dependencies
 
-`@urun-sh/react` supports React 18 and 19 and expects `@urun-sh/core` of the same release line. WorkOS React and Next.js integrations are optional peers used only by `@urun-sh/react/workos` and `@urun-sh/react/next-workos`.
+`@urun-sh/react` supports React 18 and 19 and expects `@urun-sh/core` of the same release line. WorkOS React and Next.js integrations are optional peers used only by `@urun-sh/react/workos` and `@urun-sh/react/next-workos`; video.js is an optional peer used only by `@urun-sh/react/video`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urun-sh/react",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "description": "React bindings for the urun TypeScript SDK",
   "repository": {
     "type": "git",
@@ -53,7 +53,7 @@
     "dev": "tsup --watch"
   },
   "peerDependencies": {
-    "@urun-sh/core": "^0.2.23",
+    "@urun-sh/core": "^0.2.24",
     "@workos-inc/authkit-nextjs": "^3.0.0",
     "@workos-inc/authkit-react": "^0.15.0 || ^0.16.0",
     "next": "^15.0.0 || ^16.0.0",