(session, 'control')\n\n // Status field read — re-renders ONLY when the selected value changes.\n const status = useControl((s) => s.doc.session?.status ?? 'idle')\n\n // Desired-state write — write-through to the doc (field-granular merge).\n const set = useControl((s) => s.set)\n\n return (\n \n {status}\n \n
\n )\n}\n```\n\nOutside React (or with a session handle you own), bind a store directly to a doc:\n\n```ts\nimport { createDocStore } from '@urun-sh/react'\n\nconst control = createDocStore(session.doc('control'))\ncontrol.getState().doc.session?.status\ncontrol.subscribe((s) => console.log(s.doc))\ncontrol.set({ desired: { prompt: { text: 'dawn' } } })\ncontrol.unbind() // detach the projection; the session still owns the doc\n```\n\nNotes:\n\n- Selectors that return objects/arrays should use zustand's `useShallow` (`zustand/react/shallow`) — each doc change produces a fresh snapshot tree.\n- Arrays in the doc are read as plain snapshots. Do not read-modify-write an array through `set` for append-only logs; use the platform's stream/text primitives for growing data.\n- `useSessionDoc(session, key, selector?)` also accepts a selector for one-off reads.\n\n## Streaming text (`Text`)\n\nPoint it at a named stream; it renders the text unstyled at whatever rate the\nwire delivers (1k+ tok/s), because the network path touches **zero React state**:\nchunks append to a plain buffer and a `requestAnimationFrame` loop drains it\ninto one bare DOM text node via `appendData` — one DOM write per frame, no\nreconciliation, no parsing in the hot loop.\n\n```tsx\nimport { Text } from '@urun-sh/react'\n\n\n```\n\nA reasoning pane is just a second `Text` on the other stream — nothing special:\n\n```tsx\n\n```\n\nProps: `session`, `stream`, `onDone(text)`, `onError(error)`, `onMeter(meter)`,\n`smooth` (typewriter drain below `smoothThreshold`, bypassed above it),\n`smoothCharsPerFrame`, `smoothThreshold`, `className`, `style`.\n\nStyling is the caller's — the container is an unstyled `` and the content\nis raw text. Apply markdown/code highlighting at block boundaries or on\ncompletion, never per token.\n\n### Headless: `useText` / `useTextMeter`\n\n```tsx\nconst { ref, meterRef, getText } = useText({ session, stream: `llm-resp:${id}` })\nconst { chars, tokens, tokensPerSecond } = useTextMeter(meterRef, 250)\n\nreturn \n```\n\n`useText` holds no React state, so a component using it renders once on mount\nregardless of chunk count. Counters are computed in the RAF loop and written\ninto `meterRef` in place; `useTextMeter` samples them on an interval so a\ntok/s readout costs O(interval) renders, never O(chunks).\n\n## Styling\n\nImport the package CSS when using built-in components:\n\n```ts\nimport '@urun-sh/react/styles.css'\n```\n\n## Peer dependencies\n\n`@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`.\n","readmeFilename":"README.md"}