Skip to content
Next Next commit
docs: ItemsRenderer supplies session items to useSessionItems
Document that ItemsRenderer puts its items array in scope for nested
useSessionItems consumers, and that SessionItemsProvider is only for
cards rendered outside that helper.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
  • Loading branch information
cursoragent and jhoffner committed Sep 23, 2026
commit 813b1983fc3f77cdccfd56189b940da9b2af2cc7
19 changes: 17 additions & 2 deletions apps/docs/docs/api/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ See the [Voice guide](/docs/advanced/voice) for full usage details.

### `ItemRenderer`

Render a single item using the registered renderer.
Render a single item using the registered renderer. Does not put a list in scope for `useSessionItems()`.

```tsx
import { ItemRenderer } from "@flow-state-dev/react";
Expand All @@ -185,7 +185,7 @@ import { ItemRenderer } from "@flow-state-dev/react";

### `ItemsRenderer`

Render a list of items. By default, conversational items with `history: false` visibility (sub-agent output) are filtered out — they're available in `session.items` but hidden from the default conversation view so orchestrator chatter doesn't crowd the UI. Pass `showSubAgents` to surface them inline, or render a per-agent view via `session.getItemsByAgent(name)`.
Render a list of items. Nested `useSessionItems()` consumers receive the same `items` array you pass. By default, conversational items with `history: false` visibility (sub-agent output) are filtered out of the rendered stream — they're available in `session.items` but hidden from the default conversation view so orchestrator chatter doesn't crowd the UI. Pass `showSubAgents` to surface them inline, or render a per-agent view via `session.getItemsByAgent(name)`.

```tsx
import { ItemsRenderer } from "@flow-state-dev/react";
Expand All @@ -197,6 +197,21 @@ import { ItemsRenderer } from "@flow-state-dev/react";
<ItemsRenderer items={session.items} showSubAgents />
```

### `SessionItemsProvider` / `useSessionItems`

`ItemsRenderer` mounts this for its subtree. Use it when you render a stream-aware card outside that helper.

```tsx
import { SessionItemsProvider } from "@flow-state-dev/react";
import { TaskPlan } from "@/components/flow-state/task-plan";

<SessionItemsProvider value={session.items}>
<TaskPlan collectionId="research-board" />
</SessionItemsProvider>
```

`useSessionItems()` returns `[]` when no provider is mounted, including under `ItemRenderer` alone.

### Custom Renderers

```tsx
Expand Down
2 changes: 2 additions & 0 deletions apps/docs/docs/client/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,8 @@ import { ItemRenderer, ItemsRenderer } from "@flow-state-dev/react";
<ItemRenderer item={item} />
```

`ItemsRenderer` puts its `items` array in scope for nested `useSessionItems()` consumers. `ItemRenderer` does not. When you render a stream-aware card outside `ItemsRenderer`, wrap it in `<SessionItemsProvider value={items}>`.

### Custom Renderers

All custom renderers receive `{ item }` as their prop:
Expand Down
12 changes: 9 additions & 3 deletions apps/docs/docs/ui/flow-aware-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Human-in-the-loop approval card for `suspension` items. Shows the gate's message
fsdev ui add approval
```

The card is presentation over the `useApproval` hook from `@flow-state-dev/react`, which owns the resume call and resolved state. It reads the resolution from `SessionItemsProvider`, so wrap your item list in one for the receipt to show on reload. For the full server-to-UI walkthrough, see the [Human-in-the-Loop guide](/guides/human-in-the-loop).
The card is presentation over the `useApproval` hook from `@flow-state-dev/react`, which owns the resume call and resolved state. It finds the matching `suspension_resume` item via `useSessionItems()`. Under `<ItemsRenderer items={session.items} />`, that list is in scope. Mount `<SessionItemsProvider value={session.items}>` only when you render the card outside `ItemsRenderer`. For the full server-to-UI walkthrough, see the [Human-in-the-Loop guide](/guides/human-in-the-loop).

## ModelBadge

Expand All @@ -71,7 +71,9 @@ fsdev ui add audit-annotation

## SessionItemsContext

React context for passing session items down to nested components. Required by any component that needs to subscribe to the item stream without prop drilling — `TaskPlan`, `RequestGroup`, and registry components that watch their own items.
React context that holds the session item list for `useSessionItems()`. `ItemsRenderer` mounts the provider. Add this file and wrap a card yourself when you render it outside `ItemsRenderer`.

The file re-exports `SessionItemsProvider` and `useSessionItems` from `@flow-state-dev/react`.

```bash
fsdev ui add session-items-context
Expand All @@ -80,11 +82,13 @@ fsdev ui add session-items-context
```tsx
import { SessionItemsProvider } from "@/components/flow-state/session-items-context";

<SessionItemsProvider items={session.items}>
<SessionItemsProvider value={session.items}>
<TaskPlan collectionId="research-board" />
</SessionItemsProvider>
```

`useSessionItems()` returns `[]` when no provider is mounted.

## RequestGroup

Groups items by request id. Renders a streaming indicator while a request is in flight, surfaces sources at the bottom, and collapses consecutive tool calls into a single summary.
Expand All @@ -107,6 +111,8 @@ import { TaskPlan } from "@/components/flow-state/task-plan";
<TaskPlan collectionId="research-board" />
```

Under `ItemsRenderer`, `useSessionItems()` sees the list you passed. Outside it, pass `items` or wrap the card in `<SessionItemsProvider value={...}>`.

For a board-style horizontal layout, build a `TaskCollection` consumer of the same item streams rather than forking this renderer.

## Artifact
Expand Down
14 changes: 5 additions & 9 deletions apps/docs/guides/human-in-the-loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,6 @@ import {
ItemsRenderer,
} from "@flow-state-dev/react";
import { chatAssistantRenderers } from "@/components/flow-state/chat-assistant";
import { SessionItemsProvider } from "@/components/flow-state/session-items-context";
import { Conversation } from "@/components/flow-state/conversation";

export function ContentReview({ userId }: { userId: string }) {
Expand All @@ -149,11 +148,9 @@ function ReviewSurface() {

return (
<SuspensionResolverProvider resolve={session.resumeSuspension}>
<SessionItemsProvider value={session.items}>
<Conversation>
<ItemsRenderer items={session.items} />
</Conversation>
</SessionItemsProvider>
<Conversation>
<ItemsRenderer items={session.items} />
</Conversation>

<form
onSubmit={(e) => {
Expand All @@ -173,10 +170,9 @@ function ReviewSurface() {

Submitting runs the flow until the gate. The `Approval` card appears in the conversation with the gate's message and Approve / Reject buttons. Clicking one resolves the suspension, the flow's continuation streams back into `session.items`, and the card collapses to a one-line receipt (`✓ Approved`).

Two pieces make the live, in-place update work:
`SuspensionResolverProvider` hands the card the session's streaming resume (`session.resumeSuspension`). Without it, the card resolves, but the continuation only appears after the session refetches. With it, the resumed output streams onto the same request the user is watching. This matters most on serverless, where the continuation runs in a different invocation than the original stream.

- **`SuspensionResolverProvider`** hands the card the session's streaming resume (`session.resumeSuspension`). Without it, the card still resolves, but the continuation only appears after the session refetches. With it, the resumed output streams onto the same request the user is watching. This matters most on serverless, where the continuation runs in a different invocation than the original stream.
- **`SessionItemsProvider`** lets the card see the `suspension_resume` item that records the outcome, so it shows the receipt on resolve and after a reload. It's the same context `TaskPlan` and other stream-aware components use.
The `Approval` card finds the matching `suspension_resume` item through `useSessionItems()`. `ItemsRenderer` puts `session.items` in that scope, so the receipt shows on resolve and after a reload. Mount `<SessionItemsProvider value={session.items}>` only when you render the card outside `ItemsRenderer`.

### Without the ui registry

Expand Down
2 changes: 1 addition & 1 deletion apps/docs/guides/writing-ui-stories.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Compose those instead of hand-rolling item shapes in each story. If your compone

Components that read `useFlowContext().renderers` (currently `RequestGroup` and `ChatAssistant`) need a `FlowProvider` in the tree. The global `preview.tsx` already wraps every story in `<FlowProvider renderers={chatAssistantRenderers}>`, so most of the time you don't need to think about it. Override it per-story by wrapping with your own `FlowProvider` if you want a different renderer registry.

`<TaskPlan />` reads from `<SessionItemsProvider />` rather than `FlowProvider`. Wrap it manually in the story when you want to drive it from a fixture session — see `task-plan.stories.tsx` for the pattern.
`<TaskPlan />` reads session items from `useSessionItems()`, or from an `items` prop. `FlowProvider` does not supply that list. In a story, pass `items` or wrap the card in `<SessionItemsProvider value={fixtureItems}>`. See `task-plan.stories.tsx`.

## Common variants worth writing

Expand Down
15 changes: 15 additions & 0 deletions packages/react/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,21 @@ The player exposes `enqueueChunk(chunk)` for direct callers and `dispose()` for
<ItemsRenderer items={session.items} />
```

`ItemsRenderer` puts that `items` array in scope for nested `useSessionItems()` consumers. `ItemRenderer` does not.

When you render a stream-aware card outside `ItemsRenderer`, mount the provider yourself:

```tsx
import { SessionItemsProvider } from "@flow-state-dev/react";
import { TaskPlan } from "@/components/flow-state/task-plan";

<SessionItemsProvider value={session.items}>
<TaskPlan collectionId="research-board" />
</SessionItemsProvider>
```

`useSessionItems()` returns `[]` when no provider is mounted.

Custom renderers receive `{ item }` as their prop:

```tsx
Expand Down
7 changes: 4 additions & 3 deletions packages/ui/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Generic, framework-agnostic components. No dependency on `@flow-state-dev/*`.
| `shimmer` | Animated text shimmer for streaming/loading states |
| `streaming-indicator` | In-flight status indicator with a "Working..." fallback (muted "Tidying up..." during background drain) |
| `request-group` | Groups items by request ID with streaming and sources |
| `session-items-context` | React context for passing session items to nested components |
| `session-items-context` | Re-exports `SessionItemsProvider` / `useSessionItems` from `@flow-state-dev/react`. `ItemsRenderer` mounts the provider; wrap yourself only outside it |
| `task-plan` | Section-grouped renderer for a TaskCollection. Subscribes to `task-change` and `task-board-meta` |
| `artifact` | Composable artifact viewer shell with header, actions, and content areas |
| `file-tree` | Tree-structured file and folder display with expand/collapse and selection |
Expand Down Expand Up @@ -73,6 +73,8 @@ import { chatAssistantRenderers } from "@/components/flow-state/chat-assistant";
</FlowProvider>
```

`ItemsRenderer` puts `session.items` in scope for nested `useSessionItems()` consumers, including `TaskPlan` and `Approval`.

Sources are excluded from the renderer map (`source: false`) — render them grouped separately via `<SourcesGroup>` to display as a collapsed list after the message thread.

`chatAssistantRenderers` maps the `suspension` slot to a `SuspensionCard` that picks the right card by the suspension's reason and `resumeSchema` shape: the `Approval` card for `human_approval`, and the `Question` / `Selection` / `Form` cards for `human_input` (free text, a choice from an enum, or a flat-object form). All four are thin views over `useSuspensionForm` / `useApproval`. Nested or union schemas fall outside the flat-form boundary — name your own component via the suspension's `render.component` hint for those.
Expand Down Expand Up @@ -100,7 +102,6 @@ const renderers = {
```tsx
import { TaskPlan } from "@/components/flow-state/task-plan";

// inside a session-aware view (SessionItemsProvider in scope)
<TaskPlan collectionId="research-board" />

// with assignee sub-grouping
Expand All @@ -115,7 +116,7 @@ import { TaskPlan } from "@/components/flow-state/task-plan";

Sections render in canonical order (`pending → in_progress → blocked → parked → completed → errored`), empty sections hide, `cancelled` is hidden by default. Statuses outside the canonical seven trail at the end with a humanized label, so pattern wrappers that emit extended states (`planning`, `replanning`, `reviewing`) still render. Pass `statusConfig` to customize their presentation.

`TaskPlan` reads its items from `useSessionItems()` by default; pass an explicit `items` prop when rendering outside that context (tests, replayed snapshots).
`TaskPlan` reads from `useSessionItems()`. That hook sees the array `ItemsRenderer` is rendering, or the `value` of a `SessionItemsProvider` you mount. Pass `items` to use a different array.

### Generative UI

Expand Down