@june-ai/june-ui 0.2.2 → 0.2.4

package/README.md

@@ -1,66 +1,633 @@
 # @june-ai/june-ui
 
-React Generative UI SDK built on [OpenUI](https://github.com/thesysdev/openui). June adds streaming
-helpers, themes, safe actions, error recovery, and library validation. OpenUI does all parsing and
-rendering.
+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.
+
+```tsx
+<JuneUI response={response} isStreaming={isStreaming} onJuneError={console.error} />
+```
+
+## 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 |
+| :--- | :--- |
+| `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` |
+
+`@openuidev/react-ui` is a direct dependency. You do not install it yourself. Component styles still have to be imported once (see below).
+
+The browser calls your backend. The backend calls the model. Do not put model API keys in the client.
 
 ## Install
 
 ```bash
-npm install @june-ai/june-ui
+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:
+
+```ts
+import "@openuidev/react-ui/components.css";
+import "@june-ai/june-ui/styles.css";
+```
+
+`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.
+
+## Set up a Vite app
+
+### 1. Create the project
+
+```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
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "@openuidev/react-ui/components.css";
+import "@june-ai/june-ui/styles.css";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
 ```
 
-Import styles once in your app entry:
+### 3. Point `/api` at your backend during development
+
+`vite.config.ts`:
 
 ```ts
-import "@openuidev/react-ui/components.css"; // OpenUI built-in components
-import "@june-ai/june-ui/styles.css";        // June theme variables
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    proxy: { "/api": "http://localhost:8000" },
+  },
+});
 ```
 
-## Usage
+### 4. Render
+
+`src/App.tsx`:
 
 ```tsx
 import { JuneUI } from "@june-ai/june-ui";
 
-<JuneUI response={response} isStreaming={isStreaming} theme="system" onJuneError={console.error} />
+const response = `root = Stack([title])
+title = TextContent("Hello", "large-heavy")`;
+
+export default function App() {
+  return <JuneUI response={response} isStreaming={false} />;
+}
+```
+
+```bash
+npm run dev
 ```
 
-### Streaming (works with any backend)
+Open the local URL Vite prints. The page shows the text "Hello".
+
+## Set up a Next.js app
+
+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
+```
+
+`app/june-preview.tsx`:
 
 ```tsx
-const stream = useJuneStream();
-stream.startFetch("/api/generate", { method: "POST", body, sse: false }); // sse: true for SSE
-<JuneUI response={stream.response} isStreaming={stream.isStreaming} />
+"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} />;
+}
 ```
 
-### Custom library
+`app/page.tsx`:
 
 ```tsx
-import { createJuneLibrary } from "@june-ai/june-ui";
-const library = createJuneLibrary({ root: "Stack", components: [Stack, Card] }); // module scope
-<JuneUI library={library} response={response} />
+import { JunePreview } from "./june-preview";
+
+export default function Page() {
+  return <JunePreview />;
+}
 ```
 
-### Actions
+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.
+
+## Render a static response
+
+`response` is the full string. `null` or `""` renders nothing unless you pass `emptyFallback`.
+
+```tsx
+import { JuneUI } from "@june-ai/june-ui";
+
+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}
+    />
+  );
+}
+```
+
+Prose around the program is rendered as paragraphs. This is the default (`mixedContent`):
 
 ```tsx
-const actions = { submit: defineJuneAction({ schema, sensitive: true, handler }) };
-<JuneUI actions={actions} confirmAction={({ name }) => window.confirm(name)} ... />
+<JuneUI
+  response={`Sales rose this quarter.
+
+root = Stack([title])
+title = TextContent("Sales", "large-heavy")
+
+Compared with last year.`}
+/>
 ```
-Model output never executes code. Only actions you registered by name can run, and sensitive
-actions are denied unless confirmed.
 
-### Lightweight entry
+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.
 
-`@june-ai/june-ui/core` exports `JuneRenderer`, which requires your own `library` and does not
-import OpenUI's built-in component library.
+`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`.
 
-## OpenUI features
+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:
 
-Tool providers, query loaders, state callbacks, and parse-result callbacks are forwarded to
-OpenUI's `Renderer` as props. See OpenUI's docs for their behaviour. Never put API keys in the
-browser; do tool/MCP calls in your backend.
+- `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.
 
-## Requirements
+A program that is already valid is left as it was.
+
+## Stream from your backend
+
+`useJuneStream` collects chunks into one string, about once per frame. Starting a new stream cancels the one in progress. Unmount cancels it too.
+
+The backend should write the OpenUI Lang (or prose plus OpenUI Lang) as a plain text body. Chunked `fetch` is enough. No special framing.
+
+```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),
+    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}>
+        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>
+      )}
+      <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.
+
+`startFetch` returns the full string, or `null` if the run was aborted, superseded, or failed.
+
+If you already have a `ReadableStream` or an async iterable, use `start` instead of `startFetch`:
+
+```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;
+});
+```
+
+Prefer `startFetch` unless you need that control. It maps network failures, non-2xx responses, and an empty body to a `JuneError`.
+
+## Server-sent events
+
+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.
+
+```tsx
+void stream.startFetch("/api/generate", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ prompt }),
+  sse: true,
+});
+```
+
+OpenAI-style streams put the token under a JSON path. `jsonFieldExtractor` reads that path and skips frames that do not have a string there:
+
+```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") },
+});
+```
+
+`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.
+
+Outside React, the same helpers work in a script or a test:
+
+```ts
+import { consumeStream, fetchStream } from "@june-ai/june-ui";
+
+const source = await fetchStream("/api/generate", { method: "POST", body, sse: true });
+const text = await consumeStream(source, {
+  onText: (_delta, full) => process.stdout.write(full),
+});
+```
+
+## 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.
+
+```tsx
+<JuneUI response={response} />
+```
+
+Pass `theme` when you want June's own text colors:
+
+| 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. |
+
+```tsx
+<JuneUI response={response} theme="system" />
+```
+
+`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.
+
+Override individual tokens with `themeVars`. They are written as inline custom properties and win over the built-in palette:
+
+```tsx
+<JuneUI
+  response={response}
+  theme="system"
+  themeVars={{
+    "--june-foreground": "var(--text)",
+    "--june-accent": "var(--brand)",
+    "--june-danger": "#b91c1c",
+  }}
+  className="assistant-ui"
+/>
+```
+
+`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"`.
+
+`lightTheme` and `darkTheme` are the palettes June applies. Read them if you need the same colors elsewhere. Do not mutate them.
+
+## Chat actions
+
+Buttons and forms call `onAction` with OpenUI's event. June does not run those for you. Two built-in types matter for a chat:
+
+| `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. |
+
+```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);
+    }
+  }}
+/>
+```
+
+`onAction` runs for every event, including ones you also handle with the `actions` map below.
+
+Form values can be restored on the next render with `initialState`, and read as the user types with `onStateUpdate`. Both are forwarded to OpenUI:
+
+```tsx
+<JuneUI
+  response={response}
+  initialState={saved}
+  onStateUpdate={(state) => setSaved(state)}
+/>
+```
+
+`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.
+
+## Registered actions
+
+`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.
+
+A custom OpenUI action step arrives as `event.type` equal to the action name and `event.params` equal to its parameters. Register that name:
+
+```tsx
+import { defineJuneAction, JuneUI } from "@june-ai/june-ui";
+import { z } from "zod";
+
+const actions = {
+  place_order: defineJuneAction({
+    description: "Place an order",
+    sensitive: true,
+    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})`);
+    },
+  }),
+};
+
+export function Checkout({ response }: { response: string }) {
+  return (
+    <JuneUI
+      response={response}
+      actions={actions}
+      confirmAction={({ name, description }) => window.confirm(description ?? name)}
+      onJuneError={(error) => console.error(error.code, error.message)}
+    />
+  );
+}
+```
+
+Create the map once, at module scope, so its identity stays stable.
+
+What the runner does, in order:
+
+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`.
+
+`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.
+
+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.
+
+## Your own component library
+
+`JuneUI` uses OpenUI's built-in library (`Stack`, `TextContent`, `Form`, `Table`, `BarChart`, and the rest). Pass `library` to replace it.
+
+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.
+
+```tsx
+import { createJuneLibrary, defineJuneComponent, JuneUI } from "@june-ai/june-ui";
+import { z } from "zod/v4";
+
+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>,
+});
+
+const library = createJuneLibrary({
+  root: "Greeting",
+  components: [Greeting],
+});
+
+export function Custom() {
+  return <JuneUI library={library} response={'root = Greeting("Ada")'} />;
+}
+```
+
+`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.
+
+To teach the model the built-in components, generate the system prompt on the server from the same library the client renders:
+
+```ts
+import { openuiLibrary } from "@openuidev/react-ui";
+
+const system = openuiLibrary.prompt({});
+```
+
+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.
+
+## Errors and fallbacks
+
+Three channels, for three kinds of failure:
+
+| Prop | When |
+| :--- | :--- |
+| `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. |
+
+```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>
+  )}
+  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.
+
+If you pass neither `onError` nor `onJuneError`, parser errors are written with `console.warn`.
+
+## 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} />;
+}
+```
+
+`JuneUI` is `JuneRenderer` with the built-in library as the default. Props are the same except `library` is required on `JuneRenderer`.
+
+## Props
+
+`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`.
+
+| 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. |
+
+## Streaming reference
+
+`useJuneStream(options?)` returns:
+
+| 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. |
+
+Options: `allowEmpty` resolves an empty body to `""` instead of `STREAM_EMPTY`. `onComplete(text)` and `onError(error)` fire for that hook instance.
+
+`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.
+
+`consumeStream(source, { signal, onText, allowEmpty })` decodes the source to one string. `onText(delta, accumulated)` sees every chunk.
+
+`sseToText(source, { extract, doneSentinel, signal })` turns an SSE byte stream into an async iterable of strings. The default `doneSentinel` is `"[DONE]"`.
+
+## Theme tokens
+
+Set on `.june-ui-root` when `theme` is `"light"`, `"dark"`, or `"system"`:
+
+| Variable | Light | Dark |
+| :--- | :--- | :--- |
+| `--june-foreground` | `#111827` | `#f3f4f6` |
+| `--june-muted` | `#6b7280` | `#9ca3af` |
+| `--june-border` | `#e5e7eb` | `#1f2937` |
+| `--june-accent` | `#4f46e5` | `#818cf8` |
+| `--june-danger` | `#b91c1c` | `#f87171` |
+
+`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.
+
+## Errors
+
+Every structured failure is a `JuneError`. `error.code` is one of:
+
+| Code | |
+| :--- | :--- |
+| `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
 
-React 18.3.1+ or 19, plus the OpenUI peer dependencies listed in package.json.
+- 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.