# Introduction
URL: /generative-frame/docs

Render model-generated HTML and SVG widgets in a sandboxed frame while they stream.

> For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths.

`generative-frame` renders HTML and SVG that a model writes, chunk by chunk, inside a [Safe Content Frame](/safe-content-frame) on its own site. The frame loads once, and code streams into it over a private `MessagePort`, so partial markup renders as it arrives and scripts run once the code is complete.

The package also ships the model side (tool definitions, prompts, a repair loop), a spec mode that renders your own components from JSONL patches, and bindings for React and assistant-ui. The core is framework-agnostic; React and `@assistant-ui/react` are optional peers.

## Install

```bash
npm install generative-frame
```

## Render a streamed widget

```
import { createWidget, readThemeTokens } from "generative-frame";

const widget = createWidget({
  container: document.getElementById("widget")!,
  tokens: readThemeTokens(),
  onPrompt: (text) => sendChatMessage(text),
});

for await (const chunk of modelStream) widget.write(chunk);
await widget.end();
```

`createWidget` returns immediately. Writes made before the frame connects are queued, and the iframe grows to the height of its content.

## Entry points

The package has two halves that never import each other: the frame half renders HTML and SVG widgets, and the spec half renders your own components from a spec. You compose them by passing values from one into the other, so an app ships only the half it uses.

| Entry                                | Contents                                                                                       |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `generative-frame`                   | `createWidget`, `previewWidget`, theme helpers, `buildCsp`, the in-frame runtime               |
| `generative-frame/react`             | `<Widget>`, `useWidget`, `useThemeTokens`                                                      |
| `generative-frame/tools`             | `createWidgetTools`, `toAISDKTools`, `getToolDeclarations`, `buildWidgetInstructions`          |
| `generative-frame/prompts`           | `buildWidgetGuidance`                                                                          |
| `generative-frame/repair`            | `repairLoop`, `buildRepairFeedback`                                                            |
| `generative-frame/assistant-ui`      | `createWidgetToolkit`, `useWidgetInstructions`, `useAssistantUiThemeTokens`                    |
| `generative-frame/spec`              | `defineCatalog`, `createSpecStream`, `applyPatch`, `validateSpec`, expressions, state, actions |
| `generative-frame/spec/react`        | `<SpecRenderer>`, `<SpecPlaceholder>`, `useSpecStream`                                         |
| `generative-frame/spec/tools`        | `createSpecTools`, `specGuidanceModule`                                                        |
| `generative-frame/spec/assistant-ui` | `createSpecToolkit`                                                                            |

## Pages

- [Quickstart](/generative-frame/docs/quickstart) —

  Stream a widget into a page with plain TypeScript.

- [React](/generative-frame/docs/react) —

  The `Widget` component, `useWidget`, and `useThemeTokens`.

- [With assistant-ui](/generative-frame/docs/assistant-ui) —

  Render widget tool calls in a thread as their arguments stream.

- [Tools and prompts](/generative-frame/docs/tools) —

  The model-facing tools, their inputs and results, and the guidance text.

- [Spec mode](/generative-frame/docs/spec-mode) —

  Let the model build UI from your own components with JSONL patches.

- [Delegate to a sub-agent](/generative-frame/docs/delegation) —

  Keep widget code out of the main agent's context with one tool and the repair loop.

- [Repair loop and screenshots](/generative-frame/docs/repair) —

  Render, collect errors, and feed them back to the model.

- [Theming](/generative-frame/docs/theming) —

  How your page's theme becomes CSS variables inside the frame.

- [Security model](/generative-frame/docs/security) —

  What the frame isolates, the default policy, and what the host decides.

- [API reference](/generative-frame/docs/api-reference) —

  Signatures and options for every entry point.