STREAMVIZ DOCUMENTATION

API reference

Public React, core, and protocol exports for StreamViz 0.1.

Entry points

Entry point	Purpose
`streamviz`	Convenience entry point that re-exports React, core, and protocol APIs.
`streamviz-react/react`	React renderer and public renderer types.
`streamviz-react/core`	Provider-independent partial JSON recovery and tool-call normalization.
`streamviz-react/protocol`	Model-facing tool names, prompt builders, metadata, and authoring types.
`streamviz-react/styles.css`	Complete host renderer stylesheet. Import once.

StreamVisualization

tsx
import { StreamVisualization } from 'streamviz-react/react'
import 'streamviz-react/styles.css'

StreamVisualization renders partial HTML in a sandboxed iframe and crosses the interaction boundary only when final becomes true. VisualizeWidgetFrame remains available as a compatibility alias.

Name	Type	Required	Default	Description
`title`	`string`	Yes	—	Short artifact title; also used to derive export filenames.
`code`	`string`	Yes	—	Current HTML source. It may be incomplete while the tool call is streaming.
`exportCode`	`string`	Yes	—	Best source available for HTML export. Usually the same value as code.
`loadingMessage`	`string`	Yes	—	Primary status shown before renderable content is available.
`loadingMessages`	`string[]`	No	—	Ordered progress messages recovered from the tool call.
`final`	`boolean`	Yes	—	Enables the final document, scripts, and artifact actions.
`showActions`	`boolean`	No	`true`	Shows copy and export controls after completion.
`onSendPrompt`	`(prompt: string) => void`	No	—	Receives follow-up prompts sent through the artifact bridge.
`notify`	`(message, variant) => void`	No	—	Connects success and error notifications to the host UI.
`renderIcon`	`(name, options) => ReactNode`	No	—	Maps renderer action names to host icons.
`writeImageToClipboard`	`(dataUrl) => Promise<boolean> \| boolean`	No	—	Optional clipboard bridge for desktop shells and restricted origins.
`theme`	`StreamVisualizationTheme`	No	—	Selects light, dark, or system mode and optional semantic token overrides.
`cssVarNames`	`readonly string[]`	No	—	Advanced allowlist of host CSS variables forwarded into the iframe.

Minimal example

tsx
<StreamVisualization
  title="Revenue analysis"
  code={streamedHtml}
  exportCode={streamedHtml}
  loadingMessage="Rendering analysis"
  final={toolCall.status === 'done'}
/>

Core exports

ts
import {
  extractPartialJsonString,
  extractPartialJsonStringArray,
  extractVisualizeWidgetPayload,
  getCachedVisualizeWidgetHeight,
  setCachedVisualizeWidgetHeight,
  visualizeWidgetSourceKey,
} from 'streamviz-react/core'

extractVisualizeWidgetPayload(tool)

Normalizes running and completed tool-call shapes. It never executes artifact code and does not require the outer streaming JSON object to be complete.

ts
type VisualizeWidgetPayload = {
  title: string
  code: string
  exportCode: string
  loadingMessage: string
  loadingMessages: string[]
  final: boolean
  status: string
}

extractPartialJsonString(raw, key)

Returns the currently recoverable JSON string value. Missing keys and non-string values return an empty string.

extractPartialJsonStringArray(raw, key)

Returns all complete, non-empty string items currently recoverable from a JSON array.

Height-cache helpers

visualizeWidgetSourceKey(value) creates a stable compact cache key. getCachedVisualizeWidgetHeight(key) returns a cached height or null; setCachedVisualizeWidgetHeight(key, value) stores a bounded positive height. Storage failures are ignored because this cache is only a rendering hint.

Protocol exports

ts
import {
  VISUALIZE_TYPES,
  VISUALIZE_READ_ME_TOOL_NAME,
  VISUALIZE_SHOW_WIDGET_TOOL_NAME,
  buildVisualizeSystemPrompt,
  buildVisualizeReadMeOutput,
  buildVisualizeWidgetMetadata,
} from 'streamviz-react/protocol'

Name	Type	Required	Default	Description
`buildVisualizeSystemPrompt`	`() => string`	No	—	Builds the model instruction that routes visual requests through the two-tool protocol.
`buildVisualizeReadMeTitle`	`(type) => string`	No	—	Builds the host-visible title for a loaded authoring module.
`buildVisualizeReadMeOutput`	`({ type, content }) => string`	No	—	Wraps packaged authoring rules for the model.
`buildVisualizeReadMeMetadata`	`({ type, source }) => object`	No	—	Builds stable metadata for the read-me tool result.
`buildVisualizeShowWidgetOutput`	`(title) => string`	No	—	Builds the short assistant-facing completion output.
`buildVisualizeWidgetMetadata`	`(input) => object`	No	—	Builds the final persisted widget metadata.

Supported VisualizeType values are diagram, chart, interactive, mockup, and art. Protocol exports do not depend on React and can run in a backend, CLI, or agent runtime.

Previous← Host API