@june-ai/june-ui 0.2.7 → 0.2.9

package/README.md

@@ -1,79 +1,140 @@
-# @june-ai/june-ui
+# June UI — `@june-ai/june-ui`
 
-React SDK for rendering [OpenUI Lang](https://openui.com/docs/openui-lang) as the model streams it. June supplies the React component, streaming, themes, registered actions, and error recovery. [OpenUI](https://github.com/thesysdev/openui) parses the language and draws the components.
-
-A response can be plain OpenUI Lang, or prose with OpenUI Lang in the middle (including inside ` ``` ` fences). June separates the prose and hands the program to OpenUI.
+**June UI is a React SDK for rendering AI agent responses as real user interface.** An agent answers with Markdown, with [OpenUI Lang](https://openui.com/docs/openui-lang) (a small language for describing UI), or with both mixed together. June turns that answer into React components — while it is still streaming.
 
 ```tsx
-<JuneUI response={response} isStreaming={isStreaming} onJuneError={console.error} />
+<JuneUI response={response} isStreaming={isStreaming} />
 ```
 
+June is an independent framework around [OpenUI](https://github.com/thesysdev/openui): OpenUI parses the language and draws its built-in components; June adds the parts an application needs — streaming, Markdown, a component registry, themes, actions, tool approval, a document editor, agent adapters and structured errors — behind one public API. You never touch OpenUI internals.
+
 ## Contents
 
-- [Requirements](#requirements)
-- [Install](#install)
-- [Set up a Vite app](#set-up-a-vite-app)
-- [Set up a Next.js app](#set-up-a-nextjs-app)
-- [Render a static response](#render-a-static-response)
-- [Stream from your backend](#stream-from-your-backend)
-- [Server-sent events](#server-sent-events)
-- [Themes](#themes)
-- [Chat actions](#chat-actions)
-- [Registered actions](#registered-actions)
-- [Your own component library](#your-own-component-library)
-- [Errors and fallbacks](#errors-and-fallbacks)
-- [Smaller bundle](#smaller-bundle)
-- [Props](#props)
-- [Streaming reference](#streaming-reference)
-- [Theme tokens](#theme-tokens)
-- [Errors](#errors)
-- [Security](#security)
-
-## Requirements
-
-| Package | Range |
+1. [What the SDK does](#what-the-sdk-does)
+2. [Main features](#main-features)
+3. [Architecture overview](#architecture-overview)
+4. [Requirements and peer dependencies](#requirements-and-peer-dependencies)
+5. [Installation](#installation)
+6. [Quick start](#quick-start)
+7. [Basic chat integration](#basic-chat-integration)
+8. [Markdown rendering](#markdown-rendering)
+9. [OpenUI Lang rendering](#openui-lang-rendering)
+10. [Mixed Markdown + OpenUI responses](#mixed-markdown--openui-responses)
+11. [Streaming integration](#streaming-integration)
+12. [Custom component registration](#custom-component-registration)
+13. [Zod schema definitions](#zod-schema-definitions)
+14. [Custom theme configuration](#custom-theme-configuration)
+15. [Document editor integration](#document-editor-integration)
+16. [Actions and tool approval](#actions-and-tool-approval)
+17. [Custom feature development](#custom-feature-development)
+18. [API reference](#api-reference)
+19. [TypeScript support](#typescript-support)
+20. [Error handling](#error-handling)
+21. [Troubleshooting](#troubleshooting)
+22. [Using June UI with Claude Code and AI Coding Agents](#using-june-ui-with-claude-code-and-ai-coding-agents)
+23. [Security](#security)
+24. [Migrating from 0.2.x](#migrating-from-02x)
+25. [Development setup](#development-setup)
+26. [Build and test commands](#build-and-test-commands)
+27. [Contribution guidelines](#contribution-guidelines)
+28. [License](#license)
+
+## What the SDK does
+
+Your backend asks a model for an answer. The model writes text such as:
+
+````text
+Revenue grew **12%** this quarter.
+
+root = Stack([title, chart])
+title = TextContent("Q4 Revenue", "large-heavy")
+chart = BarChart(["Oct", "Nov", "Dec"], [Series("Product A", [120, 150, 180])])
+````
+
+June receives that text chunk by chunk, separates the prose from the OpenUI program, renders the prose (as plain text or Markdown), validates every component call against its schema, and draws the components — updating as more text arrives. Buttons and forms in the generated UI call back into your app through whitelisted actions.
+
+## Main features
+
+| Feature | What you get |
 | :--- | :--- |
-| `react` | `^18.3.1` or `^19.0.0` |
-| `react-dom` | `^18.0.0` or `^19.0.0` |
-| `@openuidev/react-lang` | `>=1.0.0 <2.0.0` |
-| `@openuidev/react-headless` | `>=0.14.0 <0.19.0` |
-| `zod` | `^3.25.0` or `^4.0.0` |
-| `zustand` | `^4.5.5` |
+| **Rendering** | One `<JuneUI>` component for Markdown, OpenUI Lang, or both mixed. |
+| **Streaming** | `useJuneStream` for fetch, SSE, OpenAI-style deltas and LangGraph runs; frame-batched updates, abort, cleanup. |
+| **Component registry** | `defineComponent` + Zod schema → the model can use your React component. Add, override or remove components, even at runtime. |
+| **Prompt generation** | `june.prompt()` builds the model's system prompt from exactly the components you render. |
+| **Themes** | CSS-variable tokens, light/dark/system, per-mode overrides. Inherits your app's look by default. |
+| **Actions** | Whitelisted, schema-validated handlers for buttons and forms; confirmation for sensitive actions. |
+| **Tool approval** | `<ToolApproval>` + `useToolApproval` for human-in-the-loop approve / reject / edit. |
+| **Document editor** | A Tiptap editor the model can open with `DocumentEditor(...)`: autosave, AI merge, DOCX/PDF/HTML/Markdown export. |
+| **Adapters** | LangGraph stream and interrupt helpers. |
+| **Errors** | One `JuneError` type with stable codes, an error boundary, and safe fallbacks. |
+
+## Architecture overview
+
+```mermaid
+flowchart LR
+  A[Agent / model] -->|text stream| S[Streaming<br/>features/streaming]
+  S -->|accumulated response| P[Parser<br/>engine/parser]
+  P -->|prose segments| M[Markdown / text]
+  P -->|OpenUI program| R[OpenUI Renderer<br/>engine/renderer]
+  G[Component registry<br/>engine/registry] -->|library| R
+  R --> UI[React UI]
+  M --> UI
+  UI -->|actions| X[Actions + tool approval<br/>features]
+```
 
-`@openuidev/react-ui` is a direct dependency. You do not install it yourself. Component styles still have to be imported once (see below).
+**Data flow:** agent response → **streaming** (bytes → text, batched per frame) → **parser** (split prose from statements, hold back half-typed lines, repair common model mistakes once complete) → **component registry** (the OpenUI library: names, schemas, React components) → **renderer** (OpenUI parses incrementally and validates props; June adds theme, runtime context, documents, error boundary) → **React UI**.
 
-The browser calls your backend. The backend calls the model. Do not put model API keys in the client.
+| Folder | Responsibility | Depends on |
+| :--- | :--- | :--- |
+| `src/core/` | Public composition: `JuneUI`, `createJuneUI`, `JuneUIProvider`, the default library and registry. | engine, features, themes |
+| `src/engine/parser/` | Pure text functions: `splitResponse`, `resolveMixedContent`, `normalizeProgram`. No React. | — |
+| `src/engine/renderer/` | `JuneRenderer`, error boundary, Markdown text. Renders; never fetches. | parser, themes, features (actions, document bridge) |
+| `src/engine/registry/` | `defineComponent`, `ComponentRegistry`, `createJuneLibrary`. Knows no app components. | OpenUI |
+| `src/features/` | Self-contained features: `streaming`, `actions`, `document-editor`, `tool-approval`. | utils |
+| `src/adapters/` | External agent frameworks (`langgraph`). Pure functions. | feature types |
+| `src/themes/` | Tokens, palettes, `JuneThemeProvider`, `createTheme`. | — |
+| `src/utils/` | `JuneError`. | — |
 
-## Install
+More: [docs/architecture.md](docs/architecture.md).
+
+## Requirements and peer dependencies
+
+| Package | Range | Why |
+| :--- | :--- | :--- |
+| `react` | `^18.3.1` or `^19.0.0` | |
+| `react-dom` | `^18.0.0` or `^19.0.0` | |
+| `@openuidev/react-lang` | `>=1.0.0 <2.0.0` | OpenUI Lang parser and renderer (one shared copy). |
+| `@openuidev/react-headless` | `>=0.14.0 <0.19.0` | Used by OpenUI's components. |
+| `zod` | `^3.25.0` or `^4.0.0` | Component and action schemas. |
+| `zustand` | `^4.5.5` | Used by OpenUI's components. |
+
+`@openuidev/react-ui` (OpenUI's component library), Tiptap and `docx` are regular dependencies and install automatically.
+
+The browser calls **your backend**; your backend calls the model. Never put model API keys in client code.
+
+## Installation
 
 ```bash
 npm install @june-ai/june-ui @openuidev/react-lang @openuidev/react-headless zod zustand
 ```
 
-`react` and `react-dom` are already in a Vite or Next.js app. pnpm and yarn use the same package names.
-
-Import both stylesheets once, at the app entry:
+pnpm and yarn use the same package names. Then import the two stylesheets **once**, at your app entry:
 
 ```ts
-import "@openuidev/react-ui/components.css";
-import "@june-ai/june-ui/styles.css";
+import "@openuidev/react-ui/components.css"; // OpenUI components: cards, forms, charts, tables
+import "@june-ai/june-ui/styles.css";        // June: root layout, prose, document editor, approval cards
 ```
 
-`components.css` is the OpenUI component library (cards, forms, charts, tables). `styles.css` is June's root layout and, when you opt into a theme, its text color.
+## Quick start
 
-## Set up a Vite app
-
-### 1. Create the project
+### Vite
 
 ```bash
 npm create vite@latest my-june-app -- --template react-ts
 cd my-june-app
-npm install
 npm install @june-ai/june-ui @openuidev/react-lang @openuidev/react-headless zod zustand
 ```
 
-### 2. Import styles
-
 `src/main.tsx`:
 
 ```tsx
@@ -90,544 +151,716 @@ createRoot(document.getElementById("root")!).render(
 );
 ```
 
-### 3. Point `/api` at your backend during development
-
-`vite.config.ts`:
-
-```ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-
-export default defineConfig({
-  plugins: [react()],
-  server: {
-    proxy: { "/api": "http://localhost:8000" },
-  },
-});
-```
-
-### 4. Render
-
 `src/App.tsx`:
 
 ```tsx
 import { JuneUI } from "@june-ai/june-ui";
 
-const response = `root = Stack([title])
+const response = `Hello from **June**.
+
+root = Stack([title])
 title = TextContent("Hello", "large-heavy")`;
 
 export default function App() {
-  return <JuneUI response={response} isStreaming={false} />;
+  return <JuneUI response={response} textFormat="markdown" />;
 }
 ```
 
-```bash
-npm run dev
-```
-
-Open the local URL Vite prints. The page shows the text "Hello".
+Run `npm run dev` and open the URL Vite prints: you see the Markdown sentence and a large "Hello".
 
-## Set up a Next.js app
+During development, proxy `/api` to your backend in `vite.config.ts`: `server: { proxy: { "/api": "http://localhost:8000" } }`.
 
-June uses hooks and the browser, so the component that renders `JuneUI` is a Client Component.
-
-```bash
-npx create-next-app@latest my-june-app --ts --app --eslint
-cd my-june-app
-npm install @june-ai/june-ui @openuidev/react-lang @openuidev/react-headless zod zustand
-```
+### Next.js (App Router)
 
-`app/june-preview.tsx`:
+June uses hooks and the browser, so the component that renders `JuneUI` is a Client Component:
 
 ```tsx
+// app/june-preview.tsx
 "use client";
 
 import "@openuidev/react-ui/components.css";
 import "@june-ai/june-ui/styles.css";
 import { JuneUI } from "@june-ai/june-ui";
 
-const response = `root = Stack([title])
-title = TextContent("Hello", "large-heavy")`;
-
-export function JunePreview() {
-  return <JuneUI response={response} isStreaming={false} />;
+export function JunePreview({ response }: { response: string }) {
+  return <JuneUI response={response} />;
 }
 ```
 
-`app/page.tsx`:
+Render `<JunePreview response={...} />` from any server or client page.
 
-```tsx
-import { JunePreview } from "./june-preview";
+## Basic chat integration
 
-export default function Page() {
-  return <JunePreview />;
-}
-```
+One `<JuneUI>` per assistant message. Share configuration with `createJuneUI` + `JuneUIProvider` instead of repeating props on every message:
 
-Import the two CSS files from one client module. Importing them again from other routes is harmless, but one import is enough for the app.
+```tsx
+import { useState } from "react";
+import { createJuneUI, JuneUI, JuneUIProvider, useJuneStream, type OpenUIActionEvent } from "@june-ai/june-ui";
 
-## Render a static response
+const june = createJuneUI({
+  defaults: { theme: "system", textFormat: "markdown", onJuneError: (e) => console.warn(e.code, e.message) },
+});
 
-`response` is the full string. `null` or `""` renders nothing unless you pass `emptyFallback`.
+export function Chat() {
+  const [messages, setMessages] = useState<{ role: "user" | "assistant"; content: string }[]>([]);
+  const stream = useJuneStream({
+    onComplete: (text) => setMessages((m) => [...m, { role: "assistant", content: text }]),
+  });
 
-```tsx
-import { JuneUI } from "@june-ai/june-ui";
+  const send = (text: string) => {
+    const next = [...messages, { role: "user" as const, content: text }];
+    setMessages(next);
+    void stream.startFetch("/api/chat", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ messages: next }),
+    });
+  };
+
+  const onAction = (event: OpenUIActionEvent) => {
+    if (event.type === "continue_conversation" && event.humanFriendlyMessage) send(event.humanFriendlyMessage);
+  };
 
-export function Dashboard() {
   return (
-    <JuneUI
-      response={`root = Stack([title, chart])
-title = TextContent("Q4 Revenue", "large-heavy")
-chart = BarChart(labels, [series])
-labels = ["Oct", "Nov", "Dec"]
-series = Series("Product A", [120, 150, 180])`}
-      isStreaming={false}
-    />
+    <JuneUIProvider june={june}>
+      {messages.map((m, i) =>
+        m.role === "user" ? <p key={i}>{m.content}</p> : <JuneUI key={i} response={m.content} onAction={onAction} />,
+      )}
+      {stream.isStreaming && <JuneUI response={stream.response} isStreaming loadingFallback={<p>Thinking…</p>} />}
+    </JuneUIProvider>
   );
 }
 ```
 
-Prose around the program is rendered as paragraphs. This is the default (`mixedContent`):
+Generated buttons produce two built-in action types a chat should handle:
+
+| `event.type` | Produced by | What to do |
+| :--- | :--- | :--- |
+| `"continue_conversation"` | `Button("Submit", @ToAssistant("Submit"))` | Send `event.humanFriendlyMessage` as the next user turn. `event.formState` holds form fields. |
+| `"open_url"` | `Button("Docs", @OpenUrl("https://example.com"))` | Open `event.params.url` after checking the scheme. |
+
+Full example: [examples/basic-chat](examples/basic-chat/App.tsx).
+
+## Markdown rendering
+
+Prose is drawn as plain paragraphs by default (`<p class="june-text">`). Set `textFormat="markdown"` to render it as Markdown — headings, emphasis, lists, links, tables and code blocks:
 
 ```tsx
-<JuneUI
-  response={`Sales rose this quarter.
+<JuneUI response={"## Summary\n\n- **Revenue** up 12%\n- Churn down"} textFormat="markdown" />
+```
 
-root = Stack([title])
-title = TextContent("Sales", "large-heavy")
+Markdown is rendered with OpenUI's `MarkDownRenderer` (react-markdown), loaded on first use. Raw HTML in model output is **not** rendered. In Markdown mode line breaks are kept, and fenced code blocks in other languages (```` ```python ````) stay intact as prose.
+
+Need a different renderer? `renderText={(text, index) => <MyMarkdown source={text} />}` overrides both formats.
+
+## OpenUI Lang rendering
+
+OpenUI Lang is a list of statements. `root` is what gets drawn; other names are referenced from it. Arguments are positional, in the order of the component's schema.
 
-Compared with last year.`}
+```tsx
+<JuneUI
+  response={`root = Stack([title, chart])
+title = TextContent("Q4 Revenue", "large-heavy")
+chart = BarChart(labels, [series])
+labels = ["Oct", "Nov", "Dec"]
+series = Series("Product A", [120, 150, 180])`}
 />
 ```
 
-Pass `mixedContent={false}` when the string is already pure OpenUI Lang and must be given to OpenUI unchanged. A sentence with no `name = ...` statement will not render in that mode.
-
-`isStreaming` tells OpenUI the program is still arriving. Leave it `true` until the stream finishes so a half-written statement is not treated as the final UI. Forms stay non-interactive while it is `true`.
+The default library contains OpenUI's built-in components (`Stack`, `Card`, `TextContent`, `Form`, `Table`, `BarChart`, …) plus June's `DocumentEditor`, plus anything you register. Pass `mixedContent={false}` when the string is pure OpenUI Lang that must reach OpenUI unchanged.
 
-A few shapes the built-in library does not draw directly are rewritten before render, and only when `mixedContent` is on and the stream has finished:
+Once a response has finished streaming, June repairs a few shapes models often get wrong (only with `mixedContent` on; disable with `repair={false}`):
 
 - `Grid([a, b])` becomes a stack of those children.
 - `Card("Total Revenue", "$43,000")` becomes a title-and-value card.
-- A chart or table that was declared but left off `root` is attached so it still appears.
+- A chart or table declared but left off `root` is attached so it still appears.
 
 A program that is already valid is left as it was.
 
-## Stream from your backend
+## Mixed Markdown + OpenUI responses
+
+Prose before, between and after statements is rendered around the UI. Statements may also sit inside ```` ``` ```` or ```` ```openui ```` fences:
+
+````tsx
+<JuneUI
+  textFormat="markdown"
+  response={`Sales rose this quarter.
+
+```openui
+root = Stack([title])
+title = TextContent("Sales", "large-heavy")
+```
+
+Compared with **last year**.`}
+/>
+````
+
+All statements are joined into one program so references resolve across the whole answer. To teach a model this format, generate the prompt with OpenUI's `inlineMode`: `june.prompt({ inlineMode: true })`.
 
-`useJuneStream` collects chunks into one string, about once per frame. Starting a new stream cancels the one in progress. Unmount cancels it too.
+## Streaming integration
 
-The backend should write the OpenUI Lang (or prose plus OpenUI Lang) as a plain text body. Chunked `fetch` is enough. No special framing.
+`useJuneStream` reads a stream into one string, batching React updates to about one per frame. Starting a new stream cancels the current one; unmounting cancels too. Keep `isStreaming` true until the end so half-written statements never count as final (forms stay non-interactive meanwhile).
 
 ```tsx
 import { JuneUI, useJuneStream } from "@june-ai/june-ui";
-import { useState } from "react";
 
 export function Generator() {
-  const [prompt, setPrompt] = useState("Show a signup form");
   const stream = useJuneStream({
-    onComplete: (text) => console.log("finished", text.length),
+    onComplete: (text) => console.log("done", text.length),
     onError: (error) => console.error(error.code, error.message),
   });
 
-  const send = () => {
-    void stream.startFetch("/api/generate", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ prompt }),
-    });
-  };
-
   return (
-    <div>
-      <input value={prompt} onChange={(e) => setPrompt(e.target.value)} />
-      <button type="button" onClick={send} disabled={stream.isStreaming}>
+    <>
+      <button
+        onClick={() =>
+          void stream.startFetch("/api/generate", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ prompt: "Show a signup form" }),
+          })
+        }
+        disabled={stream.isStreaming}
+      >
         Generate
       </button>
-      <button type="button" onClick={stream.abort} disabled={!stream.isStreaming}>
-        Stop
-      </button>
-      <p>status: {stream.status}</p>
-      {stream.error && (
-        <p role="alert">
-          {stream.error.code}: {stream.error.message}
-        </p>
-      )}
+      <button onClick={stream.abort} disabled={!stream.isStreaming}>Stop</button>
       <JuneUI response={stream.response} isStreaming={stream.isStreaming} />
-    </div>
+    </>
   );
 }
 ```
 
-`stream.status` is `"idle"`, `"streaming"`, `"done"`, `"error"`, or `"aborted"`. Stop keeps the text received so far and sets `error` to `null`. A network or HTTP failure sets `error` and also keeps the partial text.
+`stream.status` is `"idle" | "streaming" | "done" | "error" | "aborted"`. Stop keeps the partial text with `error: null`; network and HTTP failures set `error` and keep the partial text. `startFetch` returns the full text, or `null` when aborted, superseded or failed.
 
-`startFetch` returns the full string, or `null` if the run was aborted, superseded, or failed.
+| Backend sends | Option |
+| :--- | :--- |
+| Plain chunked text | none |
+| SSE, `data:` = next text, `data: [DONE]` ends | `sse: true` |
+| OpenAI-style SSE JSON | `sse: { extract: jsonFieldExtractor("choices.0.delta.content") }` |
+| LangGraph run stream | `...langGraphStreamOptions({ nodes: ["agent"] })` |
+| Your own `ReadableStream` / async iterable | `stream.start(async (signal) => body)` |
 
-If you already have a `ReadableStream` or an async iterable, use `start` instead of `startFetch`:
+**LangGraph** (server API, `stream_mode: ["messages-tuple"]` or `"messages"`):
 
-```tsx
-await stream.start(async (signal) => {
-  const response = await fetch("/api/generate", { method: "POST", body, signal });
-  if (!response.ok || !response.body) throw new Error(String(response.status));
-  return response.body;
+```ts
+import { langGraphStreamOptions } from "@june-ai/june-ui";
+
+void stream.startFetch(`${API}/threads/${threadId}/runs/stream`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ assistant_id: "agent", input, stream_mode: ["messages-tuple"] }),
+  ...langGraphStreamOptions({ nodes: ["agent"] }), // only text from the "agent" node; call per run
 });
 ```
 
-Prefer `startFetch` unless you need that control. It maps network failures, non-2xx responses, and an empty body to a `JuneError`.
+Only AI message text is kept (tool and human messages are skipped); cumulative `messages/partial` events are turned into deltas. `readLangGraphInterrupts` and `interruptToApprovalRequests` help with human-in-the-loop interrupts — see [Actions and tool approval](#actions-and-tool-approval).
+
+Outside React: `const text = await consumeStream(await fetchStream(url, { method: "POST", body, sse: true }))`.
 
-## Server-sent events
+More: [docs/streaming.md](docs/streaming.md) · [examples/streaming](examples/streaming/App.tsx).
 
-Pass `sse: true` when each event's `data` field is the next piece of text. A `data: [DONE]` frame ends the stream. An `event: error` frame fails it.
+## Custom component registration
+
+Register a React component and the model can use it like a built-in. Four steps.
+
+**1. Write a normal React component.**
 
 ```tsx
-void stream.startFetch("/api/generate", {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ prompt }),
-  sse: true,
-});
+function KpiCardView({ label, value, trend }: { label: string; value: string; trend?: "up" | "down" }) {
+  return (
+    <section className="kpi-card">
+      <small>{label}</small>
+      <strong>{value}</strong>
+      {trend && <span>{trend === "up" ? "▲" : "▼"}</span>}
+    </section>
+  );
+}
 ```
 
-OpenAI-style streams put the token under a JSON path. `jsonFieldExtractor` reads that path and skips frames that do not have a string there:
+**2. Define it: name, description for the model, Zod schema for the props.**
 
 ```tsx
-import { jsonFieldExtractor, useJuneStream } from "@june-ai/june-ui";
-
-void stream.startFetch("/api/generate", {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ prompt }),
-  sse: { extract: jsonFieldExtractor("choices.0.delta.content") },
+import { z } from "zod/v4";
+import { defineComponent } from "@june-ai/june-ui";
+
+export const KpiCard = defineComponent({
+  name: "KpiCard",
+  description: "One key metric with an optional trend arrow. Use for headline numbers.",
+  schema: z.object({
+    label: z.string().describe("What the number measures"),
+    value: z.string().describe("Formatted value, e.g. $43,000"),
+    trend: z.enum(["up", "down"]).optional(),
+  }),
+  component: KpiCardView,
 });
 ```
 
-`extract` receives the raw `data` string and the event name. Return `""` or `null` to ignore a frame. Set `doneSentinel: null` if the server never sends `[DONE]` and just closes the response.
+**3. Register it** — on an instance (recommended), or on the default registry:
 
-Outside React, the same helpers work in a script or a test:
+```tsx
+import { createJuneUI, JuneUI, registerComponent } from "@june-ai/june-ui";
 
-```ts
-import { consumeStream, fetchStream } from "@june-ai/june-ui";
+// a) isolated instance: <JuneUI june={june} … /> or <JuneUIProvider june={june}>
+const june = createJuneUI({ components: [KpiCard] });
 
-const source = await fetchStream("/api/generate", { method: "POST", body, sse: true });
-const text = await consumeStream(source, {
-  onText: (_delta, full) => process.stdout.write(full),
-});
+// b) or globally, once at startup: every plain <JuneUI> can draw it
+registerComponent(KpiCard);
 ```
 
-## Themes
-
-June does not paint a background, a font, or a radius. With no `theme` prop it also does not set a text color, so the UI inherits the page.
+**4. The model refers to it by name**, with arguments in schema key order:
 
 ```tsx
-<JuneUI response={response} />
+<JuneUI
+  june={june}
+  response={`root = Stack([revenue])
+revenue = KpiCard("Revenue", "$43,000", "up")`}
+/>
 ```
 
-Pass `theme` when you want June's own text colors:
+**How it is validated and rendered.** OpenUI parses each statement and checks the arguments against your schema. A valid call renders your component with typed props. An invalid call (wrong type, missing required argument) is **not rendered**; OpenUI reports it and June raises `onJuneError` with `code: "PARSE_ERROR"` and the details. Built-in components keep working.
 
-| Value | Result |
-| :--- | :--- |
-| omitted | Host color, font, and `color-scheme` are left alone. |
-| `"light"` | Dark text on the assumption of a light page. |
-| `"dark"` | Light text on the assumption of a dark page. |
-| `"system"` | Follows `prefers-color-scheme`, and updates when the OS changes. |
+**Teach the model.** Generate the system prompt from the same instance, on your server:
 
-```tsx
-<JuneUI response={response} theme="system" />
+```ts
+const system = june.prompt({ preamble: "You are an analytics assistant." }); // includes KpiCard
 ```
 
-`theme` colors June prose (`.june-text`) and the root. Cards, charts, inputs, and tables still use OpenUI's own tokens from `components.css`. To restyle those, wrap the tree in OpenUI's `ThemeProvider` (`@openuidev/react-ui`) and point its tokens at your CSS variables. June's `theme` does not replace that.
+**More options:**
+
+| Need | How |
+| :--- | :--- |
+| Child nodes / statement id | Use `render: ({ props, renderNode, statementId }) => …` instead of `component`. |
+| Allow it inside a parent | `slots: ["Card"]` (needs Zod 4.1+; skipped with a dev warning otherwise). |
+| Replace a built-in | `createJuneUI({ overrides: [MyTextContent] })` or `registry.override(c)`. |
+| Remove a built-in | `createJuneUI({ remove: ["Modal"] })` or `registry.unregister("Modal")`. |
+| Add at runtime | `june.register(c)` / `registerComponent(c)` — mounted `<JuneUI>`s re-render. |
+| Your own library from scratch | `createComponentRegistry({ root: "Stack", components: [...] })` or `createJuneLibrary`. |
+| Tooling metadata | `metadata: {...}` → `registry.getMeta(name)`. |
+
+Names are PascalCase and unique; duplicates throw `JuneError("LIBRARY_ERROR")` with a fix in the message, and the registry is left unchanged. Create definitions and instances at module scope — the library reference must stay stable between renders.
 
-Override individual tokens with `themeVars`. They are written as inline custom properties and win over the built-in palette:
+More: [docs/component-registration.md](docs/component-registration.md) · [examples/custom-component](examples/custom-component/App.tsx).
+
+## Zod schema definitions
+
+Component schemas are **Zod 4** objects (OpenUI requires them). On Zod 4, `import { z } from "zod"`; on Zod 3.25, `import { z } from "zod/v4"` (works on both).
+
+- **Key order is argument order:** `z.object({ title, body })` ↔ `Card("Title", "Body")`.
+- **`.describe()` every field** — descriptions go into the generated prompt.
+- **`.optional()`** for trailing optional arguments; required ones first.
+- **Enums** (`z.enum([...])`) constrain the model to valid values.
+- **Child components:** `z.array(OtherComponent.ref)` (with a `render` function that calls `renderNode`).
+- Props types are inferred: `type Props = ComponentProps<typeof KpiCard>`.
+
+Action payload schemas (`defineJuneAction({ schema })`) accept any object with `safeParse` — Zod 3 or 4.
+
+## Custom theme configuration
+
+June never sets fonts, backgrounds or radii. Without `theme`, it doesn't set colors either: the UI inherits your page.
+
+| `theme` | Result |
+| :--- | :--- |
+| omitted | Host color, font and `color-scheme` are left alone. |
+| `"light"` / `"dark"` | June's palette for that mode; `color-scheme` is set. |
+| `"system"` | Follows `prefers-color-scheme`, live. |
+
+Override tokens with `themeVars` — one map for both modes, or one per mode:
 
 ```tsx
-<JuneUI
-  response={response}
-  theme="system"
-  themeVars={{
-    "--june-foreground": "var(--text)",
-    "--june-accent": "var(--brand)",
-    "--june-danger": "#b91c1c",
-  }}
-  className="assistant-ui"
-/>
+import { createTheme, JuneUI } from "@june-ai/june-ui";
+
+const brand = createTheme({
+  light: { "--june-accent": "#0ea5e9" },
+  dark: { "--june-accent": "#38bdf8" },
+});
+
+<JuneUI response={response} theme="system" themeVars={brand} className="assistant" />;
+<JuneUI response={response} themeVars={{ "--june-accent": "var(--brand)" }} />; // flat map, both modes
 ```
 
-`className` and `style` land on the `.june-ui-root` element. `useJuneTheme()` inside that tree returns `{ mode, theme }` where `theme` is the resolved `"light"` or `"dark"`.
+| Token | Light | Dark | Used by |
+| :--- | :--- | :--- | :--- |
+| `--june-foreground` | `#111827` | `#f3f4f6` | root text (when a theme is set) |
+| `--june-muted` | `#6b7280` | `#9ca3af` | secondary text |
+| `--june-border` | `#e5e7eb` | `#1f2937` | borders, approval cards |
+| `--june-accent` | `#4f46e5` | `#818cf8` | primary buttons |
+| `--june-danger` | `#b91c1c` | `#f87171` | errors, high-risk approvals |
 
-`lightTheme` and `darkTheme` are the palettes June applies. Read them if you need the same colors elsewhere. Do not mutate them.
+`className` and `style` land on `.june-ui-root`. Inside, `useJuneTheme()` returns `{ mode, theme }` (`theme` resolved to `"light"`/`"dark"`). OpenUI's own components (cards, charts, inputs) use OpenUI's tokens from `components.css`; restyle them with OpenUI's `ThemeProvider` from `@openuidev/react-ui`.
 
-## Chat actions
+More: [docs/theming.md](docs/theming.md) · [examples/custom-theme](examples/custom-theme/App.tsx).
 
-Buttons and forms call `onAction` with OpenUI's event. June does not run those for you. Two built-in types matter for a chat:
+## Document editor integration
 
-| `event.type` | Produced by | What to do |
-| :--- | :--- | :--- |
-| `"continue_conversation"` | `Button("Submit", @ToAssistant("Submit"))` | Send `event.humanFriendlyMessage` as the next user turn. `event.formState` holds the form fields. |
-| `"open_url"` | `Button("Docs", @OpenUrl("https://example.com"))` | Open `event.params.url` after you check the scheme. |
+The default library includes `DocumentEditor`. When the model writes
+
+```text
+root = Stack([doc])
+doc = DocumentEditor("proposal-1", "Website Proposal", "## Summary\n\nWe propose…", "proposal", "draft")
+```
+
+June shows an editable document (Tiptap): toolbar, find & replace, pagination, autosave, and export to DOCX, PDF, HTML, Markdown and text. While the response streams it shows a lightweight draft placeholder; the editor mounts when the stream ends. A new AI version with the same `documentId` is merged with the user's edits (conflicts are reported).
 
 ```tsx
-<JuneUI
-  response={stream.response}
-  isStreaming={stream.isStreaming}
-  onAction={(event) => {
-    if (event.type === "open_url") {
-      const url = String(event.params?.url ?? "");
-      if (/^https?:\/\//i.test(url)) window.open(url, "_blank", "noopener,noreferrer");
-      return;
-    }
-    if (event.type === "continue_conversation" && event.humanFriendlyMessage) {
-      send(event.humanFriendlyMessage);
-    }
-  }}
-/>
+import { useMemo, useState } from "react";
+import { createDocumentStore, JuneUI, type JuneDocumentOptions } from "@june-ai/june-ui";
+
+const store = createDocumentStore();
+
+export function Reply({ initial }: { initial: string }) {
+  const [response, setResponse] = useState(initial);
+  const documents = useMemo<JuneDocumentOptions>(
+    () => ({ store, onSave: async (doc) => save(doc.documentId, doc.markdown), onConflict: console.warn }),
+    [],
+  );
+  // User edits are written back into the DocumentEditor(...) call: keep the program in sync.
+  return <JuneUI response={response} documents={documents} onResponseChange={setResponse} />;
+}
 ```
 
-`onAction` runs for every event, including ones you also handle with the `actions` map below.
+Teach the model when to use it, and give it the user's current text on the next turn:
 
-Form values can be restored on the next render with `initialState`, and read as the user types with `onStateUpdate`. Both are forwarded to OpenUI:
+```ts
+import { getDocumentEditorInstructions, documentPromptOptions, serializeDocumentsForAgent } from "@june-ai/june-ui";
 
-```tsx
-<JuneUI
-  response={response}
-  initialState={saved}
-  onStateUpdate={(state) => setSaved(state)}
-/>
+const system = june.prompt({ ...documentPromptOptions() }); // or append getDocumentEditorInstructions()
+const context = await serializeDocumentsForAgent({ store });  // attach to the next user message
 ```
 
-`Query()` and `Mutation()` in a program call `toolProvider`. Pass `toolProvider={null}` to disable them. If you supply a provider, it must call your backend. A tool that talks to a model or a database from the browser will leak credentials.
+The editor is also a standalone component: `<DocumentEditor documentId="x" title="Notes" content="# Hi" />`. Custom export formats: `registerDocumentExporter(...)`. Remove it from the library with `createJuneUI({ remove: ["DocumentEditor"] })`.
 
-## Registered actions
+Example: [examples/document-editor](examples/document-editor/App.tsx).
 
-`onAction` is a callback. The `actions` prop is a whitelist. A handler runs only when `event.type` matches a name you registered. Model text is never evaluated as code.
+## Actions and tool approval
 
-A custom OpenUI action step arrives as `event.type` equal to the action name and `event.params` equal to its parameters. Register that name:
+**Registered actions.** `onAction` sees every event; the `actions` prop is a **whitelist** — a handler runs only when `event.type` matches a registered name. Model text is never evaluated as code.
 
 ```tsx
-import { defineJuneAction, JuneUI } from "@june-ai/june-ui";
 import { z } from "zod";
+import { defineJuneAction, JuneUI } from "@june-ai/june-ui";
 
 const actions = {
   place_order: defineJuneAction({
     description: "Place an order",
-    sensitive: true,
-    schema: z.object({
-      sku: z.string(),
-      qty: z.number().int().positive(),
-    }),
+    sensitive: true, // needs approval first
+    schema: z.object({ sku: z.string(), qty: z.number().int().positive() }),
     handler: async ({ sku, qty }) => {
-      const response = await fetch("/api/orders", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ sku, qty }),
-      });
-      if (!response.ok) throw new Error(`Order failed (${response.status})`);
+      const res = await fetch("/api/orders", { method: "POST", body: JSON.stringify({ sku, qty }) });
+      if (!res.ok) throw new Error(`Order failed (${res.status})`);
     },
   }),
 };
 
-export function Checkout({ response }: { response: string }) {
+<JuneUI response={response} actions={actions} confirmAction={({ description }) => window.confirm(description ?? "")} />;
+```
+
+The runner: unknown names are ignored → `schema.safeParse` (failure: `ACTION_VALIDATION_ERROR`) → sensitive actions need `confirm`/`confirmAction` (none: `ACTION_REJECTED`; a user's "no" is not an error) → handler (a throw: `ACTION_ERROR`). Create the map once at module scope.
+
+**Tool approval.** Replace `window.confirm` with an approval card, and reuse it for agent tool calls:
+
+```tsx
+import { interruptToApprovalRequests, JuneUI, ToolApprovalList, useToolApproval } from "@june-ai/june-ui";
+
+// `actions` as above; `resumeRun` is your call that resumes the agent with the decision.
+function Assistant({ response }: { response: string }) {
+  const approvals = useToolApproval();
+
+  // Agent tool calls (e.g. a LangGraph interrupt) use the same UI:
+  async function onInterrupt(value: unknown) {
+    for (const request of interruptToApprovalRequests(value)) {
+      const decision = await approvals.request(request); // { choice: "approve" | "reject" | "edit", editedArguments? }
+      await resumeRun(decision);
+    }
+  }
+
   return (
-    <JuneUI
-      response={response}
-      actions={actions}
-      confirmAction={({ name, description }) => window.confirm(description ?? name)}
-      onJuneError={(error) => console.error(error.code, error.message)}
-    />
+    <>
+      <JuneUI response={response} actions={actions} confirmAction={approvals.confirmAction} />
+      <ToolApprovalList approvals={approvals} />
+    </>
   );
 }
 ```
 
-Create the map once, at module scope, so its identity stays stable.
+`<ToolApproval request status onDecide />` shows tool name, risk, side effect, description and arguments, with Approve / Reject / Edit (JSON, validated). Use `approvals.setStatus(id, "running" | "completed" | "failed")` to show progress. Customize with `labels`, `renderArguments`, CSS (`.june-approval*`), or your own UI on top of `useToolApproval`.
 
-What the runner does, in order:
+Example: [examples/tool-approval](examples/tool-approval/App.tsx).
 
-1. Unknown names, including `"constructor"`, are ignored. Outcome `"unhandled"`.
-2. `schema.safeParse` runs when you passed a schema. Zod objects work. A failed parse reports `ACTION_VALIDATION_ERROR` and does not call the handler.
-3. `sensitive: true`, or a per-action `confirm`, must approve the call. With neither a per-action `confirm` nor the `confirmAction` prop, a sensitive action is rejected (`ACTION_REJECTED`) and the handler does not run. A user declining is also `"rejected"` and is not an error.
-4. The handler receives the parsed payload and `{ name, event }`. A throw becomes `ACTION_ERROR`.
+## Custom feature development
 
-`defineJuneAction` throws `LIBRARY_ERROR`'s sibling `ACTION_VALIDATION_ERROR` immediately if `handler` is not a function. That is a setup bug, not a runtime action failure.
+A feature is a folder in `src/features/<name>/` with its own components, hooks, types, CSS and `index.ts`. It must not import from other features' internals or from `core/`. To ship one:
 
-The default parser reads the name from `type`, then `name`, then `action`, and the payload from `params`, then `payload`, then `data`. Pass `parseActionEvent` if your event shape differs.
+1. Implement it in `src/features/<name>/`; export its public API from `index.ts`.
+2. If it contributes OpenUI components, define them with `defineComponent` and add them in `src/core/default-library.ts` (the composition root) — the engine stays untouched.
+3. If it has CSS, add the file to `scripts/copy-css.mjs`.
+4. Re-export it from `src/entry-core.ts` (`export * from "./features/<name>"`).
+5. Add tests in `tests/features/<name>/` and docs.
 
-## Your own component library
+In an **application** (not the SDK), a "feature" is usually just components + `defineComponent` + `createJuneUI({ components })`, and hooks that read `useJuneRuntime()` / `useJuneTheme()`. You never edit the SDK.
 
-`JuneUI` uses OpenUI's built-in library (`Stack`, `TextContent`, `Form`, `Table`, `BarChart`, and the rest). Pass `library` to replace it.
+More: [docs/custom-features.md](docs/custom-features.md).
 
-Build the library once at module scope. `createJuneLibrary` checks that every component has a unique non-empty name, then applies `allow` and `deny`. `allow` lists the only names to keep. `deny` removes names after that. The `root` component must still be present. A bad library throws `LIBRARY_ERROR` when the module loads, which is what you want.
+## API reference
 
-```tsx
-import { createJuneLibrary, defineJuneComponent, JuneUI } from "@june-ai/june-ui";
-import { z } from "zod/v4";
+### Entry points
 
-const Greeting = defineJuneComponent({
-  name: "Greeting",
-  description: "Greets a person by name",
-  props: z.object({
-    name: z.string().describe("The person's name"),
-  }),
-  component: ({ props }) => <p>Hello, {props.name}</p>,
-});
+| Import | Contents |
+| :--- | :--- |
+| `@june-ai/june-ui` | Everything below, including `JuneUI` and the default library. |
+| `@june-ai/june-ui/core` | Everything except the default library (`JuneUI`, `juneLibrary`, `createJuneUI`, `JuneUIProvider`, `registerComponent`, `defaultRegistry`). Pair `JuneRenderer` with your own library for a smaller bundle. |
+| `@june-ai/june-ui/styles.css` | June's stylesheet. |
 
-const library = createJuneLibrary({
-  root: "Greeting",
-  components: [Greeting],
-});
+### Core
 
-export function Custom() {
-  return <JuneUI library={library} response={'root = Greeting("Ada")'} />;
-}
-```
+| Export | Description |
+| :--- | :--- |
+| `JuneUI` | Renders a response. All `JuneRenderer` props, plus optional `library` and `june`. |
+| `JuneRenderer` | Same, with a required `library`. Available from `/core`. |
+| `createJuneUI(options)` | Instance: `{ registry, library, defaults, register(), prompt() }`. Options: `components`, `overrides`, `remove`, `baseLibrary`, `defaults`. |
+| `JuneUIProvider` | `{ june?, defaults? }` for every `<JuneUI>` below. Props on `<JuneUI>` win. |
+| `juneLibrary` | Default OpenUI library: OpenUI components + `DocumentEditor`. |
 
-`defineJuneComponent` is OpenUI's `defineComponent`. Component schemas use Zod 4 (`zod/v4`). Props, functions, and actions follow [OpenUI's library guide](https://openui.com/docs/openui-lang). `createJuneLibrary` adds the name checks and the allow/deny lists on top of `createLibrary`. The `root` name has to be one of the components you pass.
+### `JuneUI` / `JuneRenderer` props
 
-To teach the model the built-in components, generate the system prompt on the server from the same library the client renders:
+Any other prop of OpenUI's `Renderer` is forwarded and typed from your installed `@openuidev/react-lang` (`initialState`, `onStateUpdate`, `toolProvider`, `queryLoader`, `onParseResult`, …).
 
-```ts
-import { openuiLibrary } from "@openuidev/react-ui";
+| Prop | Type | Default | |
+| :--- | :--- | :--- | :--- |
+| `response` | `string \| null` | — | Accumulated model output. |
+| `isStreaming` | `boolean` | `false` | The model is still writing. |
+| `library` | OpenUI library | instance / provider / default | Required on `JuneRenderer`. |
+| `june` | `JuneUIInstance` | provider | `JuneUI` only. |
+| `mixedContent` | `boolean` | `true` | Render prose around the program. |
+| `textFormat` | `"plain" \| "markdown"` | `"plain"` | How prose is drawn. |
+| `renderText` | `(text, index) => ReactNode` | — | Custom prose rendering. |
+| `repair` | `boolean` | `true` | Fix common model mistakes after streaming. |
+| `theme` | `"light" \| "dark" \| "system"` | omitted | Opt in to June colors. |
+| `themeVars` | vars or `{ light, dark }` | — | CSS variable overrides. |
+| `className` / `style` | | — | On `.june-ui-root`. |
+| `actions` | `JuneActionMap` | — | Whitelisted handlers. |
+| `confirmAction` | `(args) => boolean \| Promise<boolean>` | — | Approval for sensitive actions. |
+| `parseActionEvent` | `(event) => { name, payload } \| null` | built-in | Custom event shape. |
+| `onAction` | `(event) => void` | — | Every OpenUI action. |
+| `onError` | `(errors: unknown[]) => void` | — | Raw OpenUI errors (`[]` when cleared). |
+| `onJuneError` | `(error: JuneError) => void` | — | Structured errors. |
+| `documents` | `JuneDocumentOptions` | — | Document store and callbacks. Memoize. |
+| `onResponseChange` | `(response, info) => void` | — | Program rewritten with user document edits. |
+| `responseChangeDelay` | `number` | `300` | Debounce in ms. |
+| `loadingFallback` | `ReactNode` | `null` | Streaming, nothing to draw yet. |
+| `emptyFallback` | `ReactNode` | `null` | Finished, nothing to draw. |
+| `errorFallback` | node or `({ error, reset }) => node` | generic alert | Render-crash UI. |
+| `resetKeys` | `unknown[]` | `[response]` | Changing clears a caught error. |
+
+### Registry
+
+| Export | Description |
+| :--- | :--- |
+| `defineComponent({ name, description, schema, component \| render, slots?, metadata? })` | A component definition (also a valid OpenUI `DefinedComponent`). |
+| `createComponentRegistry({ base?, root?, components?, overrides?, remove? })` | A `ComponentRegistry`. |
+| `ComponentRegistry` | `.library`, `.register(c, { override })`, `.override(c)`, `.unregister(name)`, `.reset()`, `.has()`, `.get()`, `.getMeta()`, `.names()`, `.customNames()`, `.prompt()`, `.subscribe()`. |
+| `registerComponent(c, opts?)` / `unregisterComponent(name)` / `defaultRegistry` | The registry plain `<JuneUI>` uses. |
+| `useRegistryLibrary(registry)` | Hook: current library, re-renders on change. |
+| `createJuneLibrary({ components, root, allow?, deny? })`, `defineJuneComponent` | 0.2 APIs, unchanged. |
 
-const system = openuiLibrary.prompt({});
-```
+### Parser (pure functions)
+
+`splitResponse(text, { streaming?, markdown? })` → `{ before, ui, after, pure }` · `resolveMixedContent(response, { mixedContent?, isStreaming?, repair?, markdown? })` → `{ before, ui, after, hasUi, hasText }` · `normalizeProgram(program)`.
+
+### Streaming
+
+| Export | Description |
+| :--- | :--- |
+| `useJuneStream({ allowEmpty?, onComplete?, onError? })` | `{ response, isStreaming, status, error, start, startFetch, abort, reset }`. |
+| `fetchStream(input, init & { sse? })` | `fetch` → stream source with `JuneError`s. |
+| `consumeStream(source, { signal?, onText?, allowEmpty? })` | Reads a source to one string. |
+| `sseToText(source, { extract?, doneSentinel?, signal? })` | SSE → text chunks. `doneSentinel` default `"[DONE]"`. |
+| `jsonFieldExtractor("a.0.b")` | `extract` for a JSON path. |
+| `createLangGraphExtractor({ nodes? })`, `langGraphStreamOptions({ nodes? })` | LangGraph stream text. |
+| `readLangGraphInterrupts(data, event)`, `interruptToApprovalRequests(value)` | LangGraph interrupts → approval requests. |
+
+### Actions, approval, themes, documents, runtime
+
+| Export | Description |
+| :--- | :--- |
+| `defineJuneAction`, `runAction`, `createActionHandler`, `defaultParseActionEvent` | Actions. |
+| `ToolApproval`, `ToolApprovalList`, `useToolApproval`, `defaultToolApprovalLabels` | Tool approval. |
+| `JuneThemeProvider`, `useResolvedTheme`, `useJuneTheme`, `createTheme`, `lightTheme`, `darkTheme` | Themes. |
+| `DocumentEditor`, `createDocumentStore`, `getDefaultDocumentStore`, `exportDocument`, `registerDocumentExporter`, `serializeDocumentsForAgent`, `getDocumentEditorInstructions`, `documentPromptOptions`, `updateDocumentInProgram`, `readDocumentFromProgram`, … | Documents. |
+| `useJuneRuntime()` | `{ isStreaming }` for custom components. |
+| `MarkdownText`, `JuneErrorBoundary` | Building blocks. |
+| `JuneError`, `isJuneError`, `toJuneError` | Errors. |
+
+## TypeScript support
 
-Send `system` with the user prompt from your backend. Keep that call off the client if the prompt is large or if you add private rules to it.
+The package ships ESM and CommonJS builds with `.d.ts` / `.d.cts` declarations for both entries. Notable types:
 
-## Errors and fallbacks
+- `JuneUIProps`, `JuneRendererProps` — OpenUI's renderer props are **derived** from your installed `@openuidev/react-lang`, never copied.
+- `OpenUIActionEvent`, `OpenUILibrary` — OpenUI's own types, re-exported.
+- `ComponentProps<typeof MyComponent>` — props inferred from a component's schema.
+- `JuneComponent`, `DefineComponentOptions`, `JuneThemeVars` (with token autocompletion), `JuneThemeSet`, `ToolApprovalRequest`, `JuneErrorCode`.
 
-Three channels, for three kinds of failure:
+`moduleResolution: "bundler"` or `"node16"` is recommended so the `/core` subpath resolves.
 
-| Prop | When |
+## Error handling
+
+| Channel | When |
+| :--- | :--- |
+| `onJuneError` | A `JuneError`: parse failures (warnings excluded), render crashes, action, document and export failures. |
+| `onError` | OpenUI's raw error list; `[]` when cleared. |
+| `errorFallback` | The render boundary. The default alert never echoes model output. |
+| `useJuneStream().error` | Stream failures. |
+
+| Code | Meaning |
 | :--- | :--- |
-| `onError` | OpenUI's own list. Called with `[]` when the errors clear. Warnings stay in the list; filter `severity !== "warning"` if you only want failures. |
-| `onJuneError` | A `JuneError`: parse failures (warnings excluded), a render crash, or an action failure. |
-| `errorFallback` | The render crash boundary. The default is a short alert that does not echo the model output. |
+| `PARSE_ERROR` | OpenUI reported errors (bad syntax, props failing a schema). `details` is the list. |
+| `RENDER_ERROR` | A component threw. `details.componentStack`. |
+| `STREAM_ERROR` | The stream failed, including an SSE `event: error`. |
+| `STREAM_ABORTED` | Aborted. `useJuneStream` treats it as a stop. |
+| `STREAM_EMPTY` | No body, or nothing decoded. |
+| `NETWORK_ERROR` | `fetch` failed or non-2xx (`details.status`). |
+| `ACTION_ERROR` | A handler threw. |
+| `ACTION_VALIDATION_ERROR` | Payload failed the schema, or `defineJuneAction` had no handler. |
+| `ACTION_REJECTED` | Sensitive action with no confirm function. |
+| `LIBRARY_ERROR` | A component definition or registration was rejected. |
+| `DOCUMENT_ERROR` | Document content or sync failed. |
+| `EXPORT_ERROR` | A document export failed. |
 
 ```tsx
 <JuneUI
   response={stream.response}
   isStreaming={stream.isStreaming}
-  loadingFallback={<p>Drawing…</p>}
-  emptyFallback={<p>Nothing to show yet.</p>}
-  errorFallback={({ error, reset }) => (
-    <div role="alert">
-      <p>This reply could not be drawn.</p>
-      <button type="button" onClick={reset}>
-        Try again
-      </button>
-    </div>
-  )}
+  errorFallback={({ reset }) => <button onClick={reset}>This reply could not be drawn. Retry</button>}
   onJuneError={(error) => {
     if (error.code === "PARSE_ERROR") console.table(error.details);
   }}
 />
 ```
 
-`loadingFallback` shows while `isStreaming` is true and there is no UI yet. `emptyFallback` shows when the stream is finished and there is still no UI and no prose. `resetKeys` clears a caught render error when any value changes. The default key is the `response` string, so the next chunk retries the render.
+`isJuneError(value)` narrows a `catch`; `toJuneError(error, fallbackCode)` wraps anything. Without `onError`/`onJuneError`, parser errors are logged with `console.warn`.
 
-If you pass neither `onError` nor `onJuneError`, parser errors are written with `console.warn`.
+## Troubleshooting
 
-## Smaller bundle
-
-The main entry imports OpenUI's built-in component library, which is large. `@june-ai/june-ui/core` exports the same streaming, actions, themes, and `JuneRenderer`, and does not import that library. You pass `library` yourself.
-
-```tsx
-import { JuneRenderer } from "@june-ai/june-ui/core";
-import { library } from "./library";
-import "@openuidev/react-ui/components.css";
-import "@june-ai/june-ui/styles.css";
-
-export function View({ response, isStreaming }: { response: string | null; isStreaming: boolean }) {
-  return <JuneRenderer library={library} response={response} isStreaming={isStreaming} />;
-}
+| Symptom | Fix |
+| :--- | :--- |
+| Components render unstyled | Import `@openuidev/react-ui/components.css` and `@june-ai/june-ui/styles.css` once. |
+| My component doesn't render | Is it registered on the instance/registry `<JuneUI>` uses? Check `june.registry.has("Name")`, and `onJuneError` for `PARSE_ERROR` (arguments vs. schema order). |
+| `LIBRARY_ERROR … Zod 4 object schema` | Use `import { z } from "zod/v4"` (Zod 3.25) or Zod 4. |
+| `LIBRARY_ERROR … already registered` | Pass `{ override: true }` or use `overrides`. Registering in a component body re-runs every render — do it at module scope. |
+| The model never uses my component | Generate the prompt from the same instance: `june.prompt()`. Improve `description` and `.describe()`. |
+| UI flickers or re-parses constantly | `library`, `actions`, `documents` and instances must be stable (module scope or `useMemo`). |
+| Prose shows `**stars**` | Set `textFormat="markdown"`. |
+| Forms do nothing | `isStreaming` must become `false` when the stream ends. |
+| `/core` import not found | Use `moduleResolution: "bundler"` or `"node16"`. |
+| Next.js: hooks error | Render June from a `"use client"` component. |
+
+More: [docs/troubleshooting.md](docs/troubleshooting.md).
+
+## Using June UI with Claude Code and AI Coding Agents
+
+Give your AI coding assistant this instruction so it integrates June correctly instead of reinventing or patching the SDK:
+
+```markdown
+## June UI (@june-ai/june-ui)
+
+This project renders AI agent responses with June UI, a React SDK for Markdown + OpenUI Lang
+(generative UI) with streaming, a component registry, themes, actions, tool approval and a
+document editor. Docs: node_modules/@june-ai/june-ui/README.md and docs/.
+
+- Install: `npm install @june-ai/june-ui @openuidev/react-lang @openuidev/react-headless zod zustand`.
+  Import `@openuidev/react-ui/components.css` and `@june-ai/june-ui/styles.css` once at the app entry.
+- Import only from `@june-ai/june-ui` (or `@june-ai/june-ui/core`). Never import from its `dist/`
+  or `src/` paths, and never edit files in node_modules.
+- Render: `<JuneUI response={text} isStreaming={bool} />`. Stream with `useJuneStream().startFetch(url, init)`
+  (`sse: true`, `jsonFieldExtractor(...)` or `langGraphStreamOptions()` for SSE / OpenAI / LangGraph).
+- Custom components: `defineComponent({ name, description, schema: z.object({...}), component })`
+  with `import { z } from "zod/v4"`; register via `createJuneUI({ components: [...] })` at module scope
+  and render `<JuneUI june={june} … />` (or wrap in `<JuneUIProvider june={june}>`).
+  Schema key order = OpenUI Lang argument order. Generate the model prompt with `june.prompt()` on the server.
+- Buttons/forms: whitelist handlers with `defineJuneAction` + the `actions` prop; mark risky ones
+  `sensitive: true` and use `useToolApproval().confirmAction`.
+- Theme with `theme` + `themeVars`/`createTheme`; never override June CSS classes by default.
+- Keep `library`, `actions`, `documents` and `createJuneUI(...)` results stable (module scope / useMemo).
+- Handle failures through `onJuneError` (`JuneError.code`). Keep model API keys on the server.
+- If something seems missing, check the README API reference before writing a workaround.
 ```
 
-`JuneUI` is `JuneRenderer` with the built-in library as the default. Props are the same except `library` is required on `JuneRenderer`.
+Put it in your project's `CLAUDE.md` (Claude Code reads it automatically), or in the equivalent instruction file of your agent (`AGENTS.md`, `.cursor/rules`, …):
 
-## Props
+```markdown
+# CLAUDE.md
 
-`JuneUI` and `JuneRenderer` accept the props below. Any other prop of OpenUI's `Renderer` is forwarded and typed from the installed `@openuidev/react-lang`. That includes `onStateUpdate`, `initialState`, `toolProvider`, `queryLoader`, and `onParseResult`.
+## Project
+Customer-support dashboard (Vite + React 19). Agent backend: FastAPI + LangGraph at /api.
 
-| Prop | Type | Default | |
-| :--- | :--- | :--- | :--- |
-| `response` | `string \| null` | — | Accumulated model output. |
-| `isStreaming` | `boolean` | `false` | The model is still writing. |
-| `library` | OpenUI library | built-in (`JuneUI` only) | Required on `JuneRenderer`. |
-| `mixedContent` | `boolean` | `true` | Draw prose around the program. `false` passes `response` through. |
-| `renderText` | `(text, index) => ReactNode` | `<p className="june-text">` | How a prose segment is drawn. |
-| `theme` | `"light" \| "dark" \| "system"` | omitted | Opt in to June text colors. |
-| `themeVars` | `Record<string, string>` | — | CSS variable overrides. |
-| `className` | `string` | — | Added on `.june-ui-root`. |
-| `style` | `CSSProperties` | — | Inline style on `.june-ui-root`. |
-| `actions` | `JuneActionMap` | — | Whitelist of handlers, keyed by action name. |
-| `confirmAction` | `(args) => boolean \| Promise<boolean>` | — | Approval for sensitive actions. |
-| `parseActionEvent` | `(event) => { name, payload } \| null` | built-in | Override how an event is read. |
-| `onAction` | `(event) => void` | — | Every OpenUI action, before the whitelist. |
-| `onError` | `(errors: unknown[]) => void` | — | Raw OpenUI errors. |
-| `onJuneError` | `(error: JuneError) => void` | — | Parse, render, and action failures. |
-| `loadingFallback` | `ReactNode` | `null` | Shown while streaming with nothing to draw. |
-| `emptyFallback` | `ReactNode` | `null` | Shown when finished with nothing to draw. |
-| `errorFallback` | `ReactNode` or `({ error, reset }) => ReactNode` | generic alert | Render-crash UI. |
-| `resetKeys` | `readonly unknown[]` | `[response]` | Change clears a caught render error. |
+## June UI (@june-ai/june-ui)
+<paste the block above>
 
-## Streaming reference
-
-`useJuneStream(options?)` returns:
+## Our conventions
+- June components live in src/june/components/*.tsx and are registered in src/june/index.ts
+  (`export const june = createJuneUI({ components: [...] })`).
+- The system prompt is generated in the backend from the same component list.
+```
 
-| Field | |
-| :--- | :--- |
-| `response` | Text so far. Kept after an error or an abort. |
-| `isStreaming` | `true` only while a run is in progress. |
-| `status` | `"idle" \| "streaming" \| "done" \| "error" \| "aborted"`. |
-| `error` | `JuneError` or `null`. `null` after a clean stop. |
-| `start(source)` | `source` is a `ReadableStream`, an async iterable, or `(signal) =>` either of those. Returns the full text, or `null`. |
-| `startFetch(input, init)` | `fetch` plus the same return. `init.sse` enables SSE parsing. |
-| `abort()` | Cancels the current run. |
-| `reset()` | Cancels and clears back to idle. |
+## Security
 
-Options: `allowEmpty` resolves an empty body to `""` instead of `STREAM_EMPTY`. `onComplete(text)` and `onError(error)` fire for that hook instance.
+- The model chooses components and arguments, never which JavaScript runs. Only names in your `actions` map have handlers.
+- Mark anything that spends money, deletes data or leaves the account `sensitive: true`, and pass `confirmAction` (or `useToolApproval`).
+- Validate payloads with `schema`; treat `event.params` and tool arguments as untrusted even then.
+- Open URLs only for `https:` (or `http:` in local development).
+- Call the model, databases and MCP tools from the server. A client `toolProvider` should be a thin proxy.
+- Markdown rendering does not execute raw HTML. The error boundary never prints model text.
 
-`fetchStream(input, init)` is the non-hook version of the request. It throws `NETWORK_ERROR` when `fetch` rejects or the status is not OK, `STREAM_ABORTED` when the signal already fired, and `STREAM_EMPTY` when the body is missing.
+## Migrating from 0.2.x
 
-`consumeStream(source, { signal, onText, allowEmpty })` decodes the source to one string. `onText(delta, accumulated)` sees every chunk.
+**No breaking changes.** Every 0.2.7 export and prop still works (a test enforces this). New, optional:
 
-`sseToText(source, { extract, doneSentinel, signal })` turns an SSE byte stream into an async iterable of strings. The default `doneSentinel` is `"[DONE]"`.
+| Before | Now (optional) |
+| :--- | :--- |
+| `createJuneLibrary({ root, components: [...all, Mine] })` + `<JuneUI library={lib}>` | `createJuneUI({ components: [Mine] })` + `<JuneUI june={june}>` — keeps the built-ins. |
+| `defineJuneComponent({ props, component: ({ props }) => … })` | `defineComponent({ schema, component: (props) => … })` — plain React props, validation, metadata. Old style still accepted everywhere. |
+| `withDocumentEditor(openuiLibrary)` | Already in the default library; `createJuneUI({ baseLibrary })` to start elsewhere. |
+| Same props on every `<JuneUI>` | `createJuneUI({ defaults })` or `<JuneUIProvider defaults>`. |
+| `renderText` for Markdown | `textFormat="markdown"`. |
+| `themeVars` flat map | Also accepts `{ light, dark }`; `createTheme()`. |
+| `confirmAction={window.confirm…}` | `useToolApproval().confirmAction` + `<ToolApprovalList>`. |
 
-## Theme tokens
+**Fixed:** `@june-ai/june-ui/core` was declared in `package.json` but not built in 0.2.7; it now ships (ESM + CJS + types), sharing state with the root entry.
 
-Set on `.june-ui-root` when `theme` is `"light"`, `"dark"`, or `"system"`:
+Internal file paths changed (see [CHANGELOG.md](CHANGELOG.md)). They were never public; if you deep-imported `dist/` or `src/` files, switch to the package exports.
 
-| Variable | Light | Dark |
-| :--- | :--- | :--- |
-| `--june-foreground` | `#111827` | `#f3f4f6` |
-| `--june-muted` | `#6b7280` | `#9ca3af` |
-| `--june-border` | `#e5e7eb` | `#1f2937` |
-| `--june-accent` | `#4f46e5` | `#818cf8` |
-| `--june-danger` | `#b91c1c` | `#f87171` |
+## Development setup
 
-`color` on the root uses `--june-foreground` only when a theme was requested (the element has `data-june-theme="light"` or `"dark"`). `color-scheme` is set to the same value. Fonts and backgrounds stay yours.
+```bash
+git clone <repository-url>
+cd june-ui
+npm install
+npm test
+```
 
-## Errors
+Node 18+ is required. Source is in `src/`, tests in `tests/` (mirroring `src/`), runnable examples in `examples/` (type-checked against the source), docs in `docs/`.
 
-Every structured failure is a `JuneError`. `error.code` is one of:
+## Build and test commands
 
-| Code | |
+| Command | Does |
 | :--- | :--- |
-| `PARSE_ERROR` | OpenUI reported one or more non-warning errors. `details` is that list. |
-| `RENDER_ERROR` | A component threw. `details.componentStack` is the React stack. |
-| `STREAM_ERROR` | The stream failed, including an SSE `event: error` frame. |
-| `STREAM_ABORTED` | The request was aborted. `useJuneStream` treats this as a stop, not `error`. |
-| `STREAM_EMPTY` | The response had no body, or the body decoded to nothing. |
-| `NETWORK_ERROR` | `fetch` failed, or the status was not OK. `details.status` is set for HTTP errors. |
-| `ACTION_ERROR` | A registered handler threw. |
-| `ACTION_VALIDATION_ERROR` | The payload failed the schema, or `defineJuneAction` was called without a handler. |
-| `ACTION_REJECTED` | A sensitive action had no confirm function. A user's "no" is not this code. |
-| `LIBRARY_ERROR` | `createJuneLibrary` rejected the library. |
-
-`isJuneError(value)` narrows an unknown catch. `toJuneError(error, fallbackCode)` wraps anything else.
-
-## Security
-
-- The model chooses components and arguments. It does not choose which JavaScript runs. Only names in your `actions` map have handlers.
-- Mark anything that spends money, deletes data, or leaves the account as `sensitive: true`, and pass `confirmAction`.
-- Validate payloads with `schema`. Treat `event.params` as untrusted input even after that.
-- Open URLs only when the scheme is `https:` (or `http:` in local development).
-- Call the model, your database, and MCP tools from the server. `toolProvider` on the client should be a thin proxy to that server.
-- The render boundary does not print the thrown message by default. Keep raw model text out of error UI.
+| `npm run typecheck` | TypeScript check of `src` and `tests`. |
+| `npm run typecheck:examples` | Type-checks `examples/` against the public API. |
+| `npm test` / `npm run test:watch` | Vitest (jsdom). |
+| `npm run check:cycles` | Fails on circular imports in `src/`. |
+| `npm run build` | tsup → `dist/` (ESM, CJS, `.d.ts`), plus `dist/june.css`. |
+| `npm run check:exports` | Loads the built package (ESM + CJS), checks every export target, shared state across entries, and that `/core` stays free of OpenUI's component bundle. |
+| `npm run validate` | All of the above, in order (also runs on `prepublishOnly`). |
+| `npm run pack:check` | Lists what `npm publish` would include. |
+
+## Contribution guidelines
+
+1. Open an issue describing the change first for anything beyond a small fix.
+2. Keep module boundaries (see [docs/architecture.md](docs/architecture.md)): parser has no React, registry knows no app components, features don't import each other's internals, everything public is exported from `src/entry-core.ts` or `src/index.ts`.
+3. Add or update tests next to the matching folder in `tests/`, and docs/examples for public API changes.
+4. Don't remove or change public exports without a deprecation path; `tests/core/public-api.test.ts` guards them.
+5. Run `npm run validate` before opening a pull request, and add a line to `CHANGELOG.md`.
+
+## License
+
+[MIT](LICENSE)