API Reference

This is the full API reference for @prototyperai/stream-ui, organized by import path.

Main Entry

import { ... } from "@prototyperai/stream-ui"

The main entry re-exports everything from core, catalog, and react, plus:

Core

import { ... } from "@prototyperai/stream-ui/core"

Types

Spec & Elements

UIElement

Expression Types

All 8 expression types that can appear in prop values:

The union type Expression includes all 8. DynamicValue<T> is T | Expression. Convenience aliases: DynamicString, DynamicNumber, DynamicBoolean.

VisibilityCondition

type VisibilityCondition =
  | boolean
  | SingleCondition
  | SingleCondition[]           // implicit AND
  | { $and: VisibilityCondition[] }
  | { $or: VisibilityCondition[] }

SingleCondition is StateCondition | ItemCondition | IndexCondition, each supporting comparison operators: eq, neq, gt, gte, lt, lte, not.

RepeatBinding

ComparisonValue

A numeric comparison value used in visibility conditions. Can be a literal number or a dynamic state reference:

type ComparisonValue = number | { $state: string }

Used by the gt, gte, lt, and lte operators on visibility conditions and in the visibility helper functions.

ActionBinding

ActionOnSuccess

Follow-up action to run on success. One of three variants:

type ActionOnSuccess =
  | { navigate: string }                                      // Redirect to a URL
  | { set: Record<string, unknown> }                          // Set state values
  | { action: string; params?: Record<string, DynamicValue<unknown>> }  // Chain another action

ActionOnError

Follow-up action to run on error. One of two variants:

type ActionOnError =
  | { set: Record<string, unknown> }                          // Set state values
  | { action: string; params?: Record<string, DynamicValue<unknown>> }  // Chain another action

FlatElement

A UIElement enriched with its own key and optional parent key. Useful for tree traversal and debugging:

interface FlatElement extends UIElement {
  key: string
  parentKey?: string | null
}

ActionConfirm

ValidationCheck

ValidationConfig

StateStore

JsonPatch

Path Utilities

Patch Utilities

State

Store Adapter

Bridge an external state store (Zustand, Redux, Jotai, etc.) to the StateStore interface:

StoreAdapterConfig

Prop Resolution

PropResolutionContext

Type guard functions are exported for each expression type: isStateExpression, isItemExpression, isIndexExpression, isBindStateExpression, isBindItemExpression, isCondExpression, isComputedExpression, isTemplateExpression.

Visibility

VisibilityContext

Type guards: isStateCondition, isItemCondition, isIndexCondition, isAndCondition, isOrCondition, isSingleCondition.

visibility.item

Convenience helpers for building ItemCondition objects inside repeat contexts:

visibility.index

Convenience helpers for building IndexCondition objects inside repeat contexts:

Actions

ActionExecutionContext

Built-in Actions

Action Helpers

The actionBinding object provides convenience constructors for building ActionBinding objects:

Check Helpers

The check object provides convenience constructors for building ValidationCheck objects with sensible default messages:

Validation

ValidationResult

Streaming

StreamCompiler

React

import { ... } from "@prototyperai/stream-ui/react"
// or from the main entry:
import { ... } from "@prototyperai/stream-ui"

Renderer

The top-level component that renders a spec.

<Renderer
  spec={spec}
  registry={registry}
  handlers={customHandlers}
  functions={computedFunctions}
  navigate={(url) => router.push(url)}
  onConfirm={(confirm) => window.confirm(confirm.message)}
  onStateChange={(state) => console.log(state)}
  loading={isStreaming}
/>

StreamUIProvider

Composes all context providers. Use this when you need to render elements manually or access hooks outside the Renderer.

<StreamUIProvider spec={spec} registry={registry} handlers={handlers}>
  <ElementRenderer elementKey={spec.root} />
</StreamUIProvider>

Props are the same as RendererProps plus children, minus loading.

ElementRenderer

Renders a single element by its key. Must be used inside a StreamUIProvider.

<ElementRenderer elementKey="myElement" loading={false} />

ComponentRenderProps

Props passed to each component renderer function:

Hooks

useUIStream

Connect to a streaming JSONL endpoint:

const { spec, isStreaming, error, send, clear } = useUIStream({
  url: "/api/generate-ui",
  method: "POST",
  autoStart: false,
})

Returns:

useBoundProp

Two-way binding for a single prop value:

const [value, setValue] = useBoundProp<string>(propValue, bindingPath)

When bindingPath is provided and the component is inside a StreamUIProvider, reads/writes go through the state store. Otherwise, falls back to local state.

useStateBinding

Direct two-way binding to a state path:

const [value, setValue] = useStateBinding<number>("/counter")

Must be used inside a StreamUIProvider.

useFieldValidation

Client-side field validation tied to a state path:

const { errors, validate, touch, clear } = useFieldValidation("/form/email", {
  checks: [
    { validator: "required", message: "Required" },
    { validator: "email", message: "Invalid email" },
  ],
  validateOn: "change",
})

See the Validation page for full documentation.

DevTools

StreamUIDevTools

Debug overlay with spec tree, state inspector, and action log.

<StreamUIDevTools defaultOpen={false} actionLog={externalLog} />

See the DevTools page for full documentation.

useDevToolsActionLog

Hook for external action logging:

const { log, record, clear } = useDevToolsActionLog()

Context Hooks

Catalog

import { ... } from "@prototyperai/stream-ui/catalog"

Builder Functions

Schema Utilities

Type Inference

Type-level utilities for extracting TypeScript types from catalog definitions:

import type {
  InferCatalogComponents,
  InferCatalogActions,
  InferComponentProps,
  InferActionParams,
} from "@prototyperai/stream-ui/catalog"

Spec Builder

import { createSpecBuilder } from "@prototyperai/stream-ui/catalog"

const builder = createSpecBuilder(catalog)

const { key, element } = builder.element("submitBtn", "Button", { label: "Submit" }, {
  on: { press: { action: "submitForm" } },
})

const spec = builder.spec("root", { root: rootElement, submitBtn: element })

Prompt Generation

UserPromptOptions

PromptOptions

Options for customizing prompt generation:

PromptTemplate

A function that generates a prompt string from context:

type PromptTemplate = (context: PromptContext) => string

PromptContext

Context passed to a prompt template function:

CatalogValidationResult

Result of catalog.validate(spec):

SpecIssue

A single issue found during spec validation:

See the Catalog page for full documentation.

Codegen

import { specToJSX } from "@prototyperai/stream-ui"
// or
import { specToJSX } from "@prototyperai/stream-ui/codegen"

CodegenOptions

See the Code Export page for full documentation.

Components

import { prototyperComponents } from "@prototyperai/stream-ui/components"

prototyperComponents is a ComponentRegistry containing renderers for 20 Prototyper UI components:

Button, Card, CardContent, CardHeader, CardTitle, CardDescription, CardFooter, Heading, Text, Input, Textarea, Select, Checkbox, Switch, RadioGroup, Tabs, TabsList, TabsTrigger, TabsContent, Dialog, Accordion, Slider, Avatar, Separator, Progress, Tooltip, Badge, Alert.

Each renderer wraps the corresponding Prototyper UI component, mapping the ComponentRenderProps interface to the component's native props, handling two-way bindings, and forwarding events.