@june-ai/june-ui 0.2.7 → 0.2.8

package/dist/june.css

@@ -488,3 +488,97 @@
   .june-doc__canvas { max-height: none; overflow: visible; padding: 0; background: none; }
   .june-doc__sheet { width: auto; box-shadow: none; border: 0; background-image: none; padding: 0; }
 }
+
+/* Tool approval (features/tool-approval). Colors come from June theme variables, with fallbacks. */
+.june-approval {
+  border: 1px solid var(--june-border, #e5e7eb);
+  border-radius: 10px;
+  padding: 12px 14px;
+  display: grid;
+  gap: 8px;
+  max-width: 100%;
+  min-width: 0;
+}
+.june-approval[data-risk="high"] {
+  border-color: var(--june-danger, #b91c1c);
+}
+.june-approval__header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px;
+}
+.june-approval__tool {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  overflow-wrap: anywhere;
+}
+.june-approval__badge {
+  font-size: 0.75em;
+  padding: 1px 8px;
+  border-radius: 999px;
+  border: 1px solid var(--june-border, #e5e7eb);
+  color: var(--june-muted, #6b7280);
+}
+.june-approval__badge[data-risk="high"] {
+  color: var(--june-danger, #b91c1c);
+  border-color: currentColor;
+}
+.june-approval__description,
+.june-approval__status {
+  margin: 0;
+  color: var(--june-muted, #6b7280);
+}
+.june-approval__args,
+.june-approval__editor {
+  margin: 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.85em;
+  max-height: 240px;
+  overflow: auto;
+  padding: 8px;
+  border-radius: 6px;
+  border: 1px solid var(--june-border, #e5e7eb);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.june-approval__editor {
+  width: 100%;
+  box-sizing: border-box;
+  background: transparent;
+  color: inherit;
+  resize: vertical;
+}
+.june-approval__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.june-approval__button {
+  font: inherit;
+  padding: 4px 12px;
+  border-radius: 6px;
+  border: 1px solid var(--june-border, #e5e7eb);
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.june-approval__button[data-variant="primary"] {
+  border-color: var(--june-accent, #4f46e5);
+  background: var(--june-accent, #4f46e5);
+  color: #fff;
+}
+.june-approval__button[data-variant="danger"] {
+  color: var(--june-danger, #b91c1c);
+}
+.june-approval__button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.june-approval__error {
+  margin: 4px 0 0;
+  color: var(--june-danger, #b91c1c);
+}
+.june-approval-list {
+  display: grid;
+  gap: 8px;
+}

package/docs/architecture.md

@@ -0,0 +1,95 @@
+# Architecture
+
+June UI wraps OpenUI behind a small public API and keeps every concern in its own module. This page explains the folders, how a response flows through them, and the rules that keep them independent.
+
+## Layers
+
+```mermaid
+flowchart TB
+  subgraph Public["Public API — src/index.ts, src/entry-core.ts"]
+    direction LR
+    JuneUI & createJuneUI & JuneUIProvider & defineComponent & useJuneStream
+  end
+  subgraph Core["core/ — composition"]
+    direction LR
+    C1[JuneUI] --- C2[createJuneUI] --- C3[JuneUIProvider] --- C4[default-library<br/>defaultRegistry]
+  end
+  subgraph Engine["engine/ — generic machinery"]
+    direction LR
+    P[parser<br/>pure text] --- R[renderer<br/>React] --- G[registry<br/>OpenUI library]
+  end
+  subgraph Features["features/ — independent capabilities"]
+    direction LR
+    F1[streaming] --- F2[actions] --- F3[document-editor] --- F4[tool-approval]
+  end
+  A[adapters/langgraph]
+  T[themes]
+  U[utils/errors]
+  Public --> Core --> Engine
+  Core --> Features
+  Engine --> Features
+  Engine --> T
+  A --> Features
+  Features --> U
+  Engine --> U
+```
+
+## Data flow
+
+```mermaid
+sequenceDiagram
+  participant Agent
+  participant Stream as features/streaming
+  participant JuneUI as core/JuneUI
+  participant Parser as engine/parser
+  participant Registry as engine/registry
+  participant Renderer as engine/renderer
+  participant OpenUI as OpenUI Renderer
+  Agent->>Stream: bytes (text, SSE, LangGraph)
+  Stream->>JuneUI: response (batched ~1 per frame)
+  JuneUI->>Registry: library (instance, provider or default)
+  JuneUI->>Renderer: props + library
+  Renderer->>Parser: resolveMixedContent(response)
+  Parser-->>Renderer: prose segments + one OpenUI program
+  Renderer->>OpenUI: program, library, isStreaming
+  OpenUI-->>Renderer: components (props validated by Zod)
+  Renderer-->>Agent: actions → whitelisted handlers / approval
+```
+
+1. **Streaming** decodes bytes safely (multi-byte characters across chunks), applies SSE/JSON/LangGraph extraction, and accumulates text. React state updates are batched to about one per frame.
+2. **Parser** (`resolveMixedContent`) splits prose from statements, keeps a half-typed trailing identifier from flashing as prose, and — after the stream ends — repairs common model mistakes (`normalizeProgram`).
+3. **Registry** supplies the OpenUI library: built-in components plus registered, overridden or removed ones. The reference only changes when the components change, because OpenUI memoizes parsing by library identity.
+4. **Renderer** wraps OpenUI's `Renderer` in the theme root, the runtime context (`useJuneRuntime`), the document bridge and an error boundary, and routes actions and errors.
+5. **OpenUI** parses incrementally, validates arguments against each component's Zod schema, and renders.
+
+## Folders
+
+| Folder | Owns | Must not |
+| :--- | :--- | :--- |
+| `core/` | `JuneUI`, `createJuneUI`, `JuneUIProvider`, `config.ts` (default props), `default-library.ts` (composition root: which features contribute components), runtime context, shared OpenUI-derived types. | Implement feature logic. |
+| `engine/parser/` | `splitResponse`, `resolveMixedContent`, `normalizeProgram`. | Import React or anything with side effects. |
+| `engine/renderer/` | `JuneRenderer`, `JuneErrorBoundary`, `MarkdownText`. | Fetch or read streams; know document internals (it mounts `DocumentBridge` only). |
+| `engine/registry/` | `defineComponent`, `ComponentRegistry`, `useRegistryLibrary`, `createJuneLibrary`. | Import application or feature components. |
+| `engine/openui-devtools.tsx` | Keeps OpenUI's dev launcher hidden. | — |
+| `features/streaming/` | Stream sources, SSE, `useJuneStream`. | Know about parsing or rendering. |
+| `features/actions/` | `defineJuneAction`, `runAction`. | Render UI. |
+| `features/document-editor/` | Tiptap editor, store, merge, export, instructions, `DocumentBridge` (write-back of edits into the program). | Depend on the chat or the renderer. |
+| `features/tool-approval/` | `ToolApproval`, `ToolApprovalList`, `useToolApproval`. | Depend on a specific agent framework. |
+| `adapters/langgraph/` | Pure translation of LangGraph streams and interrupts. | Hold React state or perform network calls. |
+| `themes/` | Tokens, palettes, `JuneThemeProvider`, theme context, `createTheme`. | Contain component behavior. |
+| `utils/` | `JuneError`. | — |
+| `styles/` | Base CSS; features keep their own CSS next to their code. | — |
+
+## Rules (enforced)
+
+- **No import cycles** — `npm run check:cycles`.
+- **Public API only through the entries** — `src/entry-core.ts` (no default library) and `src/index.ts` (adds the default library and the `JuneUI` layer). `tests/core/public-api.test.ts` fails if a 0.2.7 export disappears.
+- **`/core` stays light** — `npm run check:exports` fails if `entry-core` statically imports `@openuidev/react-ui`.
+- **One copy of state** — the build uses shared chunks so React contexts and the default document store are identical across `.` and `./core` (checked by `check:exports`).
+
+## Why these choices
+
+- **Built on OpenUI's own extension API.** The registry uses `defineComponent`, `createLibrary` and `library.extend({ components: { add, override, remove } })`. June invents no parallel component model, so anything OpenUI accepts, June accepts.
+- **Composition root in `core/default-library.ts`.** Features contribute components there; the engine never imports a feature's components. Adding a component-providing feature touches one line of core and nothing in the engine.
+- **`DocumentBridge` instead of document logic in the renderer.** The renderer only mounts a provider; everything about stores, echoes and program rewriting lives in the document feature.
+- **Pure parser.** Splitting and repair are synchronous functions, testable without React and reusable on the server.

package/docs/component-registration.md

@@ -0,0 +1,115 @@
+# Component registration
+
+Registering a component makes a React component available to the model through OpenUI Lang. June's registry is a thin, validated layer over OpenUI's own `defineComponent` / `createLibrary` / `library.extend`.
+
+## 1. Define
+
+```tsx
+import { z } from "zod/v4";
+import { defineComponent } from "@june-ai/june-ui";
+
+export const ProductCard = defineComponent({
+  name: "ProductCard",                       // PascalCase, unique
+  description: "A product with price and stock. Use when showing a single product.",
+  schema: z.object({                         // key order = argument order
+    title: z.string().describe("Product name"),
+    price: z.number().describe("Price in USD"),
+    inStock: z.boolean().optional().describe("Defaults to true"),
+  }),
+  component: ({ title, price, inStock = true }) => (
+    <article>
+      <h3>{title}</h3>
+      <p>${price.toFixed(2)} {inStock ? "" : "· sold out"}</p>
+    </article>
+  ),
+  slots: ["Card"],                           // optional: may appear inside Card
+  metadata: { owner: "catalog-team" },       // optional: for your tooling
+});
+```
+
+The model writes `p = ProductCard("Desk lamp", 39.5, false)`.
+
+### `component` or `render`
+
+| Field | Receives | Use when |
+| :--- | :--- | :--- |
+| `component` | The validated props, as plain React props. | Almost always. |
+| `render` | OpenUI's `{ props, renderNode, statementId }`. | You render child nodes (`renderNode(props.children)`) or need the statement id. |
+
+```tsx
+const Section = defineComponent({
+  name: "Section",
+  description: "A titled section containing other components.",
+  schema: z.object({ title: z.string(), children: z.array(z.any()) }),
+  render: ({ props, renderNode }) => (
+    <section>
+      <h2>{props.title}</h2>
+      {renderNode(props.children)}
+    </section>
+  ),
+});
+```
+
+### Validation at definition time
+
+`defineComponent` throws `JuneError("LIBRARY_ERROR")` with a fix in the message when: the name is not PascalCase, the description is empty, the schema is not a Zod 4 object, or not exactly one of `component`/`render` is given.
+
+## 2. Register
+
+| Where | Code | Scope |
+| :--- | :--- | :--- |
+| Instance (recommended) | `const june = createJuneUI({ components: [ProductCard] })` | `<JuneUI june={june}>` or `<JuneUIProvider june={june}>` |
+| Default registry | `registerComponent(ProductCard)` | Every `<JuneUI>` without `june`/`library` |
+| Standalone registry | `createComponentRegistry({ base, components })` | Pass `registry.library` to `JuneRenderer` (works from `/core`) |
+
+`createJuneUI` options:
+
+```ts
+createJuneUI({
+  components: [ProductCard],          // add (names must be new)
+  overrides: [MyTextContent],         // replace built-ins by name
+  remove: ["Modal", "DocumentEditor"],// drop built-ins (not the root)
+  baseLibrary: openuiLibrary,         // start from another library (default: June's)
+  defaults: { theme: "system" },      // default <JuneUI> props
+});
+```
+
+### Runtime changes
+
+```ts
+june.register(NewChart);                    // add
+june.registry.override(BetterTable);        // replace
+june.registry.unregister("NewChart");       // remove / revert an override
+june.registry.reset();                      // back to the base library
+```
+
+Each change is atomic: it is validated immediately and, if OpenUI rejects it, the registry is left exactly as before and the error is thrown. Mounted `<JuneUI>` components re-render with the new library (`useRegistryLibrary` subscribes to the registry).
+
+### Inspecting
+
+`registry.names()`, `registry.has(name)`, `registry.get(name)`, `registry.customNames()`, `registry.getMeta(name)`.
+
+## 3. Teach the model
+
+```ts
+// server
+import { june } from "./june";
+const system = june.prompt({
+  preamble: "You are a shopping assistant.",
+  additionalRules: ["Show at most 6 products."],
+});
+```
+
+`prompt()` is OpenUI's `library.prompt()` for the current components, so the model sees your `description` and every `.describe()` text. Generate it on the server; it can be large.
+
+## 4. Render and validate
+
+OpenUI parses each statement and validates its arguments against the schema. Invalid statements are not rendered; June reports them through `onJuneError` as `PARSE_ERROR` with OpenUI's error list in `details`. While streaming, partially written statements are held until complete.
+
+## Existing OpenUI components
+
+Anything made with OpenUI's `defineComponent` (or the 0.2 alias `defineJuneComponent`) can be registered as is — June's definitions *are* OpenUI `DefinedComponent`s with an extra `june` field.
+
+## Zod versions
+
+OpenUI needs Zod 4 schemas. With Zod 3.25 import from `"zod/v4"`. `slots` clone parent schemas and need Zod 4.1+; on older versions June registers the component without slots and logs a development warning.

package/docs/custom-features.md

@@ -0,0 +1,68 @@
+# Custom features
+
+Two audiences: **applications** extending June from the outside (no SDK changes), and **contributors** adding a feature to the SDK.
+
+## In your application
+
+Everything an app needs is public API. A typical feature is a folder in your app:
+
+```text
+src/june/
+  components/
+    product-card.tsx      # React component + defineComponent(...)
+    order-status.tsx
+  actions.ts              # defineJuneAction(...) map
+  index.ts                # export const june = createJuneUI({ components, defaults: { actions } })
+```
+
+```ts
+// src/june/index.ts
+import { createJuneUI } from "@june-ai/june-ui";
+import { ProductCard } from "./components/product-card";
+import { OrderStatus } from "./components/order-status";
+import { actions } from "./actions";
+
+export const june = createJuneUI({
+  components: [ProductCard, OrderStatus],
+  defaults: { actions, textFormat: "markdown" },
+});
+```
+
+Building blocks for feature code:
+
+| Need | Use |
+| :--- | :--- |
+| Know if the answer is still streaming | `useJuneRuntime().isStreaming` |
+| Current light/dark mode | `useJuneTheme()` |
+| React to buttons and forms | `actions` + `defineJuneAction`, or `onAction` |
+| Ask the user before something risky | `sensitive: true` + `useToolApproval()` |
+| Persist UI state | `initialState` / `onStateUpdate` (forwarded to OpenUI) |
+| Custom data fetching from programs | OpenUI `toolProvider` (proxy to your server) |
+| Teach the model | `june.prompt({ additionalRules, examples })` |
+
+## Inside the SDK
+
+### Checklist
+
+1. **Folder**: `src/features/<name>/` with `types.ts`, components, hooks, optional `<name>.css`, and `index.ts` exporting only the public API.
+2. **Boundaries**: import from `../../utils`, `../../themes`, or another feature's **public types** only. No imports from `core/`. The parser and registry must not import your feature.
+3. **Components for the model**: define them with `defineComponent` inside the feature and add them in `src/core/default-library.ts`, the composition root. The engine is not modified.
+4. **Renderer integration** (rare): if every response needs a provider (like `DocumentBridge`), expose a single component from the feature and mount it in `engine/renderer/june-renderer.tsx`. Keep all logic in the feature.
+5. **CSS**: add the file to `scripts/copy-css.mjs`; use `--june-*` tokens with fallbacks; prefix classes `june-<name>`.
+6. **Exports**: `export * from "./features/<name>"` in `src/entry-core.ts`. Add the names to `NEW_EXPORTS` in `tests/core/public-api.test.ts`.
+7. **Tests** in `tests/features/<name>/`; **docs** in the README and, if large, `docs/`; an example in `examples/` (type-checked by `npm run typecheck:examples`).
+8. `npm run validate`.
+
+### Example: how tool approval was added
+
+- `features/tool-approval/types.ts` — `ToolApprovalRequest`, `ToolApprovalDecision`, statuses.
+- `tool-approval.tsx` — presentational card, labels, edit-as-JSON.
+- `use-tool-approval.ts` — promise-based state; exposes `confirmAction` matching the actions feature's `ConfirmAction` type, so it plugs into `<JuneUI confirmAction>` without either feature knowing the other's internals.
+- `tool-approval.css` added to the stylesheet build.
+- `adapters/langgraph` maps LangGraph interrupts to `ToolApprovalRequest` — the adapter depends on the feature's types, never the reverse.
+
+No change to `core/` or `engine/` was needed.
+
+### Adding an adapter
+
+Adapters translate an external framework's wire format into June types. Keep them pure (no React state, no network), put them in `src/adapters/<framework>/`, and expose small composable functions (an `extract` for `sseToText`, mappers to June types).

package/docs/streaming.md

@@ -0,0 +1,76 @@
+# Streaming
+
+## How June streams
+
+| Stage | Module | Behavior |
+| :--- | :--- | :--- |
+| Transport | `fetchStream` | `fetch` with structured errors: `NETWORK_ERROR` (rejected or non-2xx, `details.status`), `STREAM_ABORTED`, `STREAM_EMPTY`. |
+| Framing | `sseToText` | Parses SSE frames (`data:` lines joined, comments skipped). `event: error` → `STREAM_ERROR`. Stops at `doneSentinel` (`"[DONE]"`, or `null` to wait for close). `extract(data, event)` maps a frame to text. |
+| Decoding | `consumeStream` | UTF-8 decoding that survives multi-byte characters split across chunks; accumulates text; `onText(delta, full)`. |
+| React | `useJuneStream` | Coalesces updates to about one per frame (16 ms), cancels the previous run on `start`, cancels on unmount, ignores late results. |
+| Parsing | `resolveMixedContent` + OpenUI | Splits prose, holds back a half-typed trailing identifier; OpenUI parses statements incrementally and only renders complete ones. |
+
+Rendering cost stays low because `JuneUI` memoizes the split per `response` string, OpenUI memoizes by library identity, and handlers passed to OpenUI keep a stable identity.
+
+## Recipes
+
+```ts
+// Plain text body
+stream.startFetch("/api/generate", { method: "POST", body });
+
+// SSE where each data line is text
+stream.startFetch("/api/generate", { method: "POST", body, sse: true });
+
+// OpenAI-compatible SSE
+stream.startFetch("/api/proxy", {
+  method: "POST",
+  body,
+  sse: { extract: jsonFieldExtractor("choices.0.delta.content") },
+});
+
+// Custom SSE payload
+stream.startFetch("/api/agent", {
+  method: "POST",
+  body,
+  sse: {
+    extract: (data, event) => (event === "token" ? JSON.parse(data).text : null),
+    doneSentinel: null, // server just closes the stream
+  },
+});
+
+// Anything else: WebSocket bridge, SDK async iterator, ReadableStream
+stream.start(async (signal) => myAsyncIterableOfStrings(signal));
+```
+
+## LangGraph
+
+The LangGraph adapter reads the SSE produced by the LangGraph server API (`/threads/{id}/runs/stream`, `/runs/stream`):
+
+| `stream_mode` | Event | Handling |
+| :--- | :--- | :--- |
+| `messages-tuple` | `messages` → `[chunk, metadata]` | Each AI chunk's text is a delta. Filter with `nodes` (matches `metadata.langgraph_node`). |
+| `messages` | `messages/partial` → `[message…]` | Messages are cumulative; only the new part of each (by id) is emitted. |
+| subgraphs | `messages|<ns>` | Same as above. |
+| anything else | — | Ignored. |
+
+Only AI messages are kept; tool and human messages are skipped. Text content blocks (`[{ type: "text", text }]`) are supported.
+
+```ts
+stream.startFetch(url, { method: "POST", headers, body, ...langGraphStreamOptions({ nodes: ["agent"] }) });
+```
+
+`langGraphStreamOptions` creates a fresh, stateful extractor: call it for every run.
+
+**Interrupts (human in the loop).** If you parse the stream yourself (e.g. with `stream_mode: ["messages-tuple", "updates"]`), `readLangGraphInterrupts(data, event)` returns interrupt values from `updates` events, and `interruptToApprovalRequests(value)` maps the `{ action_requests, review_configs }` shape (LangChain's human-in-the-loop middleware) to `ToolApprovalRequest`s for `useToolApproval().request(...)`. For your own interrupt payloads, build the requests yourself.
+
+## Status and errors
+
+| `status` | `isStreaming` | `error` | `response` |
+| :--- | :--- | :--- | :--- |
+| `idle` | false | null | `""` |
+| `streaming` | true | null | grows |
+| `done` | false | null | full text |
+| `aborted` | false | null | partial text |
+| `error` | false | `JuneError` | partial text |
+
+Pass `isStreaming` to `<JuneUI>` unchanged. While it is true, components can read `useJuneRuntime().isStreaming` to defer expensive work (the document editor shows a placeholder until the stream ends).

package/docs/theming.md

@@ -0,0 +1,65 @@
+# Theming
+
+June's theming has one rule: **inherit by default, opt in to color**. Without a `theme` prop June sets no colors, fonts or `color-scheme`; your app's styles apply.
+
+## Modes
+
+| `theme` | Effect on `.june-ui-root` |
+| :--- | :--- |
+| omitted | No `data-june-theme`, no palette. `themeVars` still apply. |
+| `"light"` / `"dark"` | `data-june-theme`, palette as CSS variables, `color: var(--june-foreground)`, `color-scheme`. |
+| `"system"` | Same, resolved from `prefers-color-scheme` and updated live (SSR renders light). |
+
+## Tokens
+
+| Token | Light | Dark |
+| :--- | :--- | :--- |
+| `--june-foreground` | `#111827` | `#f3f4f6` |
+| `--june-muted` | `#6b7280` | `#9ca3af` |
+| `--june-border` | `#e5e7eb` | `#1f2937` |
+| `--june-accent` | `#4f46e5` | `#818cf8` |
+| `--june-danger` | `#b91c1c` | `#f87171` |
+
+June's prose, root, tool-approval cards and error alert read these tokens (with fallbacks). The document editor uses its own `--jd-*` variables, which follow the June theme context automatically (`theme="auto"`).
+
+## Overrides
+
+```tsx
+// both modes
+<JuneUI theme="dark" themeVars={{ "--june-accent": "var(--brand)" }} response={r} />
+
+// per mode, starting from June's palettes
+const brand = createTheme({
+  light: { "--june-accent": "#0ea5e9" },
+  dark: { "--june-accent": "#38bdf8" },
+});
+<JuneUI theme="system" themeVars={brand} response={r} />
+```
+
+`themeVars` are inline custom properties and win over the palette. Any `--name` is passed through, so you can set your own variables for custom components in the same place.
+
+## Custom components
+
+Read the resolved mode with `useJuneTheme()` and style with the tokens:
+
+```tsx
+function Badge({ label }: { label: string }) {
+  const { theme } = useJuneTheme();
+  return <span style={{ color: "var(--june-accent)", border: "1px solid var(--june-border)" }} data-mode={theme}>{label}</span>;
+}
+```
+
+Keep styling in CSS or tokens; keep logic in the component. Never hard-code a palette inside a registered component.
+
+## OpenUI components
+
+Cards, charts, inputs and tables come from `@openuidev/react-ui` and use OpenUI's tokens from `components.css`. Restyle them with OpenUI's `ThemeProvider` (wrap your app), pointing its tokens at your design system. June's `theme` prop does not replace it.
+
+## Global setup
+
+Set a theme once for all messages:
+
+```tsx
+const june = createJuneUI({ defaults: { theme: "system", themeVars: brand } });
+<JuneUIProvider june={june}>…</JuneUIProvider>
+```

package/docs/troubleshooting.md

@@ -0,0 +1,59 @@
+# Troubleshooting
+
+Start by passing `onJuneError={(e) => console.log(e.code, e.message, e.details)}` — most problems show up there.
+
+## Nothing renders
+
+| Check | Why |
+| :--- | :--- |
+| `response` contains a `root = …` statement | OpenUI draws only what `root` references. |
+| `mixedContent` is not `false` for prose | With it off, prose is handed to OpenUI and ignored. |
+| `onJuneError` shows `PARSE_ERROR` | A statement is invalid; `details` lists OpenUI's errors (often wrong argument order or type). |
+| `emptyFallback` / `loadingFallback` | Shown when there is no UI and no prose. |
+
+## Custom component issues
+
+| Symptom | Fix |
+| :--- | :--- |
+| `LIBRARY_ERROR: Component name … is invalid` | Use PascalCase: `ProductCard`. |
+| `… needs a Zod 4 object schema` | `import { z } from "zod/v4"` (Zod 3.25) or upgrade to Zod 4. |
+| `… already registered` | Name taken by a built-in or an earlier registration. Rename, or `{ override: true }`. Often caused by registering inside a component body: move it to module scope. |
+| Component missing in `<JuneUI>` | It was registered on a different instance. `createJuneUI` instances are isolated from `registerComponent`. Check `june.registry.has("Name")`. |
+| Arguments land in the wrong props | Positional arguments follow the schema's key order. |
+| Model ignores the component | Regenerate the system prompt from the same instance (`june.prompt()`); improve `description` and `.describe()` texts. |
+| Dev warning: slots skipped | `slots` need Zod 4.1+. The component still works at the top level. |
+
+## Streaming issues
+
+| Symptom | Fix |
+| :--- | :--- |
+| UI appears only at the end | The backend buffers. Disable proxy buffering (e.g. `X-Accel-Buffering: no`), flush per token, avoid compression middleware on the stream. |
+| Raw `data: {...}` text in the UI | Use `sse: true` or an `extract` function. |
+| Stream never finishes | The server doesn't send `[DONE]` and doesn't close; send it, or close the response. |
+| `NETWORK_ERROR` with `details.status` | The HTTP call failed; check the backend. |
+| `STREAM_EMPTY` | The body was empty. Use `allowEmpty: true` if that is valid. |
+| LangGraph shows nothing | Use `stream_mode: ["messages-tuple"]` (or `"messages"`), and check the `nodes` filter matches your graph node names. |
+
+## Performance
+
+- Create `createJuneUI(...)`, libraries, `actions` maps and definitions at **module scope**; memoize `documents` and `themeVars` objects. A new library object every render forces OpenUI to re-parse.
+- Use `useJuneRuntime().isStreaming` in heavy custom components to defer work until the stream ends.
+- For long chats, render finished messages with `isStreaming={false}` so they are parsed once.
+
+## Styling
+
+| Symptom | Fix |
+| :--- | :--- |
+| Unstyled cards and charts | Import `@openuidev/react-ui/components.css`. |
+| Unstyled document editor or approval cards | Import `@june-ai/june-ui/styles.css`. |
+| Colors don't change with `themeVars` | Token names start with `--`; per-mode sets must be `{ light, dark }`. |
+| Text color ignores the theme | Set `theme`; without it June inherits your page on purpose. |
+
+## Build and module resolution
+
+| Symptom | Fix |
+| :--- | :--- |
+| `Cannot find module '@june-ai/june-ui/core'` | Use `moduleResolution: "bundler"` or `"node16"`; upgrade from 0.2.7, where `/core` was not built. |
+| Hooks error in Next.js | Render June from a `"use client"` file. |
+| Two copies of React | Ensure a single `react` / `react-dom` (`npm ls react`). |
+| OpenUI's devtools logo appears | Import June before any other OpenUI package in your entry. |

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@june-ai/june-ui",
-  "version": "0.2.7",
-  "description": "A React Generative UI SDK powered by OpenUI",
+  "version": "0.2.8",
+  "description": "A modular React SDK for generative UI: Markdown, streaming OpenUI Lang, custom components and documents",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
     "**/*.css",
     "./dist/block-automount.js",
-    "./src/openui/disable-devtools.tsx"
+    "./src/engine/openui-devtools.tsx"
   ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -38,6 +38,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -45,10 +46,14 @@
   "scripts": {
     "build": "tsup && node scripts/copy-css.mjs && node scripts/prepare-devtools-block.mjs",
     "typecheck": "tsc --noEmit",
+    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
     "test": "vitest run",
     "test:watch": "vitest",
+    "check:cycles": "node scripts/check-cycles.mjs",
+    "check:exports": "node scripts/check-exports.mjs",
     "pack:check": "npm pack --dry-run",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+    "validate": "npm run typecheck && npm run typecheck:examples && npm run check:cycles && npm test && npm run build && npm run check:exports",
+    "prepublishOnly": "npm run validate"
   },
   "peerDependencies": {
     "@openuidev/react-headless": ">=0.14.0 <0.19.0",
@@ -91,5 +96,14 @@
     "vitest": "^3.0.0",
     "zod": "^4.0.0",
     "zustand": "^4.5.5"
-  }
+  },
+  "keywords": [
+    "react",
+    "openui",
+    "generative-ui",
+    "llm",
+    "streaming",
+    "langgraph",
+    "sdk"
+  ]
 }