@cogstream/react

Plain React renderer and lifecycle bridge for CogStream dynamic surfaces.

@cogstream/react renders @cogstream/surfaces payloads in React applications without requiring CopilotKit, AG-UI, Vercel AI SDK, A2UI, or any other agent UI framework.

It is a bridge, not a replacement for React and not a design system.

Why this package exists

Generated UI still creates user journeys.

CogStream needs a way to render dynamic surfaces in ordinary React apps, attach CogStream metadata, observe user interaction inside those surfaces, and report whether the surface helped.

@cogstream/react provides that default React path.

Relationship to other packages

@cogstream/surfaces
  framework-neutral context, control, metadata, payload, and outcome contracts

@cogstream/react
  React renderer and lifecycle wrapper for those contracts

@cogstream/ui
  optional styled/headless components that can be registered with @cogstream/react

What it does

• renders SurfacePayload objects
• registers custom surface components
• wraps surfaces with CogStream lifecycle metadata
• emits surface interaction events
• records SurfaceOutcome
• applies SurfaceGenerationControl through surface policy validation
• works without AG-UI or CopilotKit

Install

npm install @cogstream/react @cogstream/surfaces

Basic usage

import {
  CogStreamSurfaceProvider,
  SurfaceRenderer,
} from '@cogstream/react';

export function JourneyAssistSurface({ context, control, payload }) {
  return (
    <CogStreamSurfaceProvider
      context={context}
      control={control}
      onInteraction={(event) => console.log('surface event', event)}
      onOutcome={(outcome) => console.log('surface outcome', outcome)}
    >
      <SurfaceRenderer payload={payload} />
    </CogStreamSurfaceProvider>
  );
}

Register a custom surface component

import {
  registerSurfaceComponent,
  SurfaceRenderer,
  type SurfaceComponentProps,
} from '@cogstream/react';

function IdentityRepairCard({ payload, complete, dismiss }: SurfaceComponentProps) {
  return (
    <section>
      <h3>{String(payload.content.title ?? 'Fix identity upload')}</h3>
      <button onClick={() => complete({ result: 'completed', delta_progress: 1 })}>
        Done
      </button>
      <button onClick={() => dismiss({ reason: 'not_relevant' })}>
        Dismiss
      </button>
    </section>
  );
}

registerSurfaceComponent('identity_repair_card', IdentityRepairCard);

<SurfaceRenderer
  componentName="identity_repair_card"
  payload={{
    mode: 'static',
    surface_type: 'card',
    content: { title: 'Fix identity upload' },
  }}
/>;

Default surface types

The package includes minimal default renderers for:

• cue
• card
• checklist
• form
• comparison
• confirmation
• handoff_panel
• inline_guide
• workspace
• custom

These are intentionally plain. Product-quality styling should come from the host app or from registered components, possibly using @cogstream/ui.

Provider API

<CogStreamSurfaceProvider
  context={surfaceGenerationContext}
  control={surfaceGenerationControl}
  generatedSurface={generatedSurfaceContext}
  onInteraction={handleSurfaceInteraction}
  onOutcome={handleSurfaceOutcome}
>
  {children}
</CogStreamSurfaceProvider>

Core exports

export {
  CogStreamSurfaceProvider,
  SurfaceRenderer,
  SurfaceSlot,
  CogStreamSurfaceFrame,
  registerSurfaceComponent,
  getSurfaceComponent,
  hasSurfaceComponent,
  clearSurfaceComponents,
  createSurfaceRegistry,
  registerDefaultSurfaceComponents,
  useSurfaceContext,
  useSurfaceControl,
  useGeneratedSurface,
  useSurfaceEvents,
  useSurfaceOutcome,
};

Design principles

1. React renders. CogStream observes.

The package renders a surface and reports lifecycle events. It does not decide the full intervention strategy.

2. @cogstream/surfaces owns the contract.

The React package consumes surface contracts; it does not define them.

3. Components are replaceable.

The host app can register custom components for any surface type.

4. Outcomes matter.

A surface is not successful because it rendered. It is successful only if it helped the journey.