Skip to content

The Open Standard for Generative UI

Add standalone WithPreviewRenderer rendering (#1268)

ABf1f66c4266d6
diff --git a/.changeset/generalized-renderer.md b/.changeset/generalized-renderer.md
new file mode 100644
index 000000000..399f53928
--- /dev/null
+++ b/.changeset/generalized-renderer.md
@@ -0,0 +1,9 @@
+---
+"@openuidev/react-lang": minor
+"@openuidev/a2ui": minor
+"@openuidev/server": minor
+---
+
+Add optional Renderer slots for content, query loading, errors, and retry controls. Keep `queryLoader` supported on `Renderer` and `A2UIRenderer`. Preserve the default loading spinner; error/retry views render nothing unless supplied by the application.
+
+Preserve the existing query lifecycle while waiting for generation to finish. Keep mounted input state through retries and refresh query results when generated scripts change.
diff --git a/docs/content/docs/api-reference/a2ui.mdx b/docs/content/docs/api-reference/a2ui.mdx
index aa7e2396f..83aaed8d0 100644
--- a/docs/content/docs/api-reference/a2ui.mdx
+++ b/docs/content/docs/api-reference/a2ui.mdx
@@ -325,7 +325,7 @@ The component subscribes to the client with `useSyncExternalStore`, reads the re
| `onError` | `(errors) => void` | Receives OpenUI parser/runtime errors |
| `formStateKeys` | `readonly string[]` | Adds top-level data-model keys that should also hydrate form namespaces |
| `toolProvider` | `RendererProps["toolProvider"]` | Overrides the default A2UI routing for OpenUI Lang `Query()` and `Mutation()` calls |
-| `queryLoader` | `ReactNode` | UI shown while a query is loading |
+| `children` | `React.ReactNode` | Optional Renderer slot composition; omit for default content, loading, and error views. |
`@OpenUrl` is handled locally and is not emitted as an A2UI action. Other OpenUI actions are converted to A2UI actions automatically.
diff --git a/docs/content/docs/api-reference/react-lang.mdx b/docs/content/docs/api-reference/react-lang.mdx
index 1a329b7d5..2f3552285 100644
--- a/docs/content/docs/api-reference/react-lang.mdx
+++ b/docs/content/docs/api-reference/react-lang.mdx
@@ -106,11 +106,41 @@ interface RendererProps {
| Record<string, (args: Record<string, unknown>) => Promise<unknown>>
| McpClientLike
| null;
+ /** Custom loading indicator. Defaults to a spinner. */
queryLoader?: React.ReactNode;
+ children?: React.ReactNode;
onError?: (errors: OpenUIError[]) => void;
}
```
+## Renderer slots
+
+`Renderer` keeps query defaults or cached results visible while loading and after failures, and reports errors through `onError`. A spinner is shown while queries load; provide `queryLoader` to customize it. No error/retry view is shown by default. To customize loading feedback and opt into an error/retry presentation, use `Renderer.Root` with these slots:
+
+| Slot | Purpose |
+| --- | --- |
+| `Renderer.Content` | Generated UI; accepts div props and stays mounted during query failures. |
+| `Renderer.QueryLoading` | Children shown while queries wait or fetch; omitted children use `queryLoader` or the default spinner. |
+| `Renderer.QueryError` | Children shown when queries fail; renders nothing without children. |
+| `Renderer.Retry` | A retry button; accepts standard button props. |
+
+Root accepts the same runtime props as Renderer and renders only its children. Put overlays in your own positioned container. Slots share context through wrappers and React portals. `useRendererQuery()` returns `{ isLoading, errors, retry, isRetrying }` within that root. `Renderer.Content` renders defaults or cached data while queries load and hides content on failure while preserving mounted state through retries.
+
+`Renderer` accepts slot children to replace its default content composition. Without children, Renderer keeps its default views. Calling `preventDefault()` in the retry button’s click handler cancels the retry.
+
+```tsx
+<Renderer.Root response={response} library={library} toolProvider={tools}>
+ <div style={{ position: "relative" }}>
+ <Renderer.Content />
+ <Renderer.QueryLoading>Loading data…</Renderer.QueryLoading>
+ <Renderer.QueryError>
+ <p role="alert">Data is unavailable.</p>
+ <Renderer.Retry>Try again</Renderer.Retry>
+ </Renderer.QueryError>
+ </div>
+</Renderer.Root>
+```
+
## Tool Provider
Handles `Query()` and `Mutation()` tool calls at runtime. The `toolProvider` prop accepts two forms:
diff --git a/docs/content/docs/api-reference/server.mdx b/docs/content/docs/api-reference/server.mdx
index 8a7144857..658e8ad38 100644
--- a/docs/content/docs/api-reference/server.mdx
+++ b/docs/content/docs/api-reference/server.mdx
@@ -3,7 +3,7 @@ title: "@openuidev/server"
description: API reference for Autofix helpers and conversation history persistence on the OpenUI Gateway.
---
-Server utilities for OpenUI Gateway. Validate and repair model-generated OpenUI Lang, and persist a completed turn as Conversations API items.
+Server utilities for OpenUI Gateway. Validate and repair model-generated OpenUI Lang, and persist a completed turn as Conversations API items.
Import from the subpath that matches your SDK. The helpers call [Autofix HTTP API](/docs/gateway/api/autofix).
## Install
diff --git a/docs/content/docs/openui-lang/renderer.mdx b/docs/content/docs/openui-lang/renderer.mdx
index 51ee3aba2..d1e139ab1 100644
--- a/docs/content/docs/openui-lang/renderer.mdx
+++ b/docs/content/docs/openui-lang/renderer.mdx
@@ -34,7 +34,8 @@ export function AssistantMessage({
| `initialState` | `Record<string, any>` | Hydrates form state on load (e.g. from persisted message). |
| `onParseResult` | `(result: ParseResult \| null) => void` | Debug/inspect latest parse result. |
| `toolProvider` | `Record<string, (args: Record<string, unknown>) => Promise<unknown>> \| McpClientLike \| null` | Handles `Query()` / `Mutation()` tool calls. Pass a function map or an [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) client. |
-| `queryLoader` | `React.ReactNode` | Custom loading indicator shown while queries are fetching. Defaults to a spinner. |
+| `queryLoader` | `React.ReactNode` | Custom loading indicator; defaults to a spinner. |
+| `children` | `React.ReactNode` | Optional Renderer slot composition; omit to keep content visible with a loading indicator. |
| `onError` | `(errors: OpenUIError[]) => void` | Structured, LLM-friendly errors from the parser and query system. Suitable for automated correction loops. Called with `[]` when resolved. |
## Connecting tools
diff --git a/packages/a2ui/src/Renderer.tsx b/packages/a2ui/src/Renderer.tsx
index a3a3acfde..8bc544f73 100644
--- a/packages/a2ui/src/Renderer.tsx
+++ b/packages/a2ui/src/Renderer.tsx
@@ -30,7 +30,9 @@ export interface A2UIRendererProps {
/** Additional top-level data-model keys that should hydrate form namespaces. */
formStateKeys?: readonly string[];
toolProvider?: OpenUIRendererProps["toolProvider"];
+ /** Custom loading indicator. Defaults to a spinner. */
queryLoader?: OpenUIRendererProps["queryLoader"];
+ children?: OpenUIRendererProps["children"];
}
function collectFormStateKeys(result: ParseResult | null): string[] {
@@ -68,6 +70,7 @@ export function A2UIRenderer({
formStateKeys,
toolProvider,
queryLoader,
+ children,
}: A2UIRendererProps) {
const subscribe = useCallback((notify: () => void) => client.subscribe(notify), [client]);
const getSnapshot = useCallback(() => client.getSurface(surfaceId), [client, surfaceId]);
@@ -140,6 +143,7 @@ export function A2UIRenderer({
onError={onError}
toolProvider={toolProvider ?? agentToolProvider}
queryLoader={queryLoader}
+ children={children}
/>
);
}
diff --git a/packages/lang-core/src/telemetry/runtime.ts b/packages/lang-core/src/telemetry/runtime.ts
index 0eadf4abb..dde4b3853 100644
--- a/packages/lang-core/src/telemetry/runtime.ts
+++ b/packages/lang-core/src/telemetry/runtime.ts
@@ -471,6 +471,7 @@ function getValidationErrorCounts(
| "validation_error_count"
> {
const counts: Record<ValidationErrorCode, number> = {
+ "type-mismatch": 0,
"unknown-component": 0,
"missing-required": 0,
"null-required": 0,
diff --git a/packages/react-lang/README.md b/packages/react-lang/README.md
index 6a1b94f9b..5a60540db 100644
--- a/packages/react-lang/README.md
+++ b/packages/react-lang/README.md
@@ -18,6 +18,37 @@ pnpm add @openuidev/react-lang
**Peer dependencies:** `react >=19.0.0`
+## Query failures
+
+Without slot children, `Renderer` keeps query defaults or cached results visible while loading and after failures. A spinner is shown while queries load, and `onError` receives structured errors. Provide `queryLoader` to customize the indicator, or slot children for custom layouts. No error/retry view is shown by default.
+
+Use slots to customize loading and failure views:
+
+```tsx
+<Renderer.Root response={response} library={library} toolProvider={toolProvider}>
+ <div style={{ position: "relative" }}>
+ <Renderer.Content />
+ <Renderer.QueryLoading>Loading data…</Renderer.QueryLoading>
+ <Renderer.QueryError>
+ <div role="alert">
+ <p>We couldn't load your data. Please try again.</p>
+ <Renderer.Retry>Try again</Renderer.Retry>
+ </div>
+ </Renderer.QueryError>
+ </div>
+</Renderer.Root>
+```
+
+`Renderer.Root` owns one runtime and renders only its children. Slots can sit inside wrappers or portals under that root. `Renderer.Content` keeps generated components mounted while queries load or fail; failed results remain hidden until recovery. Omitting a slot omits its presentation. Plain `Renderer` supplies content and a loading indicator without hiding results on failure.
+
+`Renderer.QueryLoading` shows its children while queries await generation or fetch data, unless failures are being displayed. Omit children to use `queryLoader`, falling back to the default spinner. Position custom overlays within your own relative container. `Renderer.QueryError` shows its children on failure and renders nothing without children. Add `Renderer.Retry` explicitly if you want a retry button. `Renderer.Retry` disables itself during loading and when no queries have failed. It accepts standard button props; its click handler can prevent the retry with `event.preventDefault()`.
+
+Use `useRendererQuery()` inside the root to read `{ isLoading, errors, retry, isRetrying }` in your own components. Generation progress remains available through `useIsStreaming()`. Do not create another root for each slot.
+
+`Renderer` accepts slot children to replace its default content composition.
+
+While queries load, `Renderer.Content` renders their defaults or previously successful data. During streaming edits, previously loaded results remain visible with loading feedback until the updated response is ready.
+
## Overview
`@openuidev/react-lang` is the React runtime layer for OpenUI Lang. It covers the loop most apps need:
@@ -100,7 +131,7 @@ function AssistantMessage({ response, isStreaming }) {
| Export | Description |
| :--- | :--- |
-| `Renderer` | React component that parses and renders OpenUI Lang output |
+| `Renderer` | Render OpenUI Lang |
**`RendererProps`:**
@@ -112,6 +143,7 @@ function AssistantMessage({ response, isStreaming }) {
| `onAction` | `(event: ActionEvent) => void` | Callback when a component triggers an action |
| `onStateUpdate` | `(state: Record<string, any>) => void` | Callback when form field values change |
| `initialState` | `Record<string, any>` | Initial form state for hydration |
+| `queryLoader` | `React.ReactNode` | Custom loading indicator; defaults to a spinner |
| `onParseResult` | `(result: ParseResult \| null) => void` | Callback when the parse result changes |
### Parser (Server-Side)
diff --git a/packages/react-lang/src/Renderer.tsx b/packages/react-lang/src/Renderer.tsx
index 669ddb5b5..df50ee11e 100644
--- a/packages/react-lang/src/Renderer.tsx
+++ b/packages/react-lang/src/Renderer.tsx
@@ -7,13 +7,30 @@ import type {
ToolProvider,
} from "@openuidev/lang-core";
import { ToolNotFoundError, extractToolResult } from "@openuidev/lang-core";
-import React, { Component, Fragment, useEffect, useInsertionEffect, useRef } from "react";
+import React, {
+ Component,
+ Fragment,
+ createContext,
+ useContext,
+ useEffect,
+ useInsertionEffect,
+ useMemo,
+ useRef,
+} from "react";
import { OpenUIContext, useOpenUI, useRenderNode } from "./context";
import { useOpenUIState } from "./hooks/useOpenUIState";
import type { ComponentRenderer, Library } from "./library";
+export interface RendererQueryState {
+ /** Whether any query is waiting for generation or fetching data. */
+ isLoading: boolean;
+ errors: OpenUIError[];
+ retry: () => void;
+ isRetrying: boolean;
+}
+
export interface RendererProps {
- /** Raw response text (openui-lang code). */
+ /** OpenUI Lang code or the complete Cloud response bundle. */
response: string | null;
/** Component library from createLibrary(). */
library: Library;
@@ -41,12 +58,15 @@ export interface RendererProps {
*/
toolProvider?:
Record<string, (args: Record<string, unknown>) => Promise<unknown>> | McpClientLike | null;
- /** Custom loading indicator shown while queries are fetching. Defaults to a spinner. */
+ /** Custom loading indicator. Defaults to a spinner. */
queryLoader?: React.ReactNode;
+ /** Custom slot composition. Omit to keep content visible with a loading indicator. */
+ children?: React.ReactNode;
/**
* Called with structured, LLM-friendly errors from the parser and query system.
- * Only includes errors fixable by changing the openui-lang code (unknown components,
- * missing required props, tool-not-found). Suitable for an automated LLM correction loop.
+ * Includes generation errors (unknown components, missing required props)
+ * and tool execution failures. Retry data-source failures instead of treating
+ * every query error as a reason to regenerate the program.
* Called with [] when all errors are resolved.
*/
onError?: (errors: OpenUIError[]) => void;
@@ -182,6 +202,8 @@ function ensureLoadingStyle() {
const DefaultQueryLoader = () => (
<div
+ role="status"
+ aria-label="Loading data"
style={{
position: "absolute",
top: 8,
@@ -197,7 +219,7 @@ const DefaultQueryLoader = () => (
/>
);
-export function Renderer({
+function RendererRoot({
response,
library,
isStreaming = false,
@@ -207,6 +229,7 @@ export function Renderer({
onParseResult,
toolProvider,
queryLoader,
+ children,
onError,
publishObservability,
}: RendererProps) {
@@ -245,20 +268,21 @@ export function Renderer({
});
const resolvedToolProvider = toolProvider != null ? stableToolProvider.current : null;
- const { result, parseResult, contextValue, isQueryLoading } = useOpenUIState(
- {
- response,
- library,
- isStreaming,
- onAction,
- onStateUpdate,
- initialState,
- toolProvider: resolvedToolProvider,
- onError,
- publishObservability,
- },
- renderDeep,
- );
+ const { result, parseResult, contextValue, isQueryLoading, queryErrors, retryQueries } =
+ useOpenUIState(
+ {
+ response,
+ library,
+ isStreaming,
+ onAction,
+ onStateUpdate,
+ initialState,
+ toolProvider: resolvedToolProvider,
+ onError,
+ publishObservability,
+ },
+ renderDeep,
+ );
// Fire onParseResult with the RAW parse result (not evaluated),
// so hosts only see changes when the parser output actually changes.
@@ -266,18 +290,132 @@ export function Renderer({
onParseResultRef.current?.(parseResult);
}, [parseResult]);
- if (!result?.root) {
- return null;
- }
+ const query = useMemo<RendererQueryState>(
+ () => ({
+ isLoading: isQueryLoading,
+ errors: queryErrors,
+ retry: retryQueries,
+ isRetrying: queryErrors.length > 0 && isQueryLoading,
+ }),
+ [isQueryLoading, queryErrors, retryQueries],
+ );
+ const value = useMemo(
+ () => ({ root: result?.root ?? null, query, queryLoader }),
+ [result?.root, query, queryLoader],
+ );
return (
<OpenUIContext.Provider value={contextValue}>
- <div style={{ position: "relative" }}>
- {isQueryLoading && (queryLoader ?? <DefaultQueryLoader />)}
- <div style={{ opacity: isQueryLoading ? 0.7 : 1, transition: "opacity 0.2s ease" }}>
- <RenderNode node={result.root} />
- </div>
- </div>
+ <RendererContext.Provider value={value}>{children}</RendererContext.Provider>
</OpenUIContext.Provider>
);
}
+
+const RendererContext = createContext<{
+ root: ElementNode | null;
+ query: RendererQueryState;
+ queryLoader?: React.ReactNode;
+} | null>(null);
+
+function useRendererContext() {
+ const context = useContext(RendererContext);
+ if (!context) {
+ throw new Error("Renderer slots must be used within Renderer.Root or Renderer.");
+ }
+ return context;
+}
+
+/** Access query loading, failures, and retry within the nearest Renderer root. */
+export function useRendererQuery(): RendererQueryState {
+ return useRendererContext().query;
+}
+
+export type RendererContentSlotProps = Omit<React.ComponentPropsWithRef<"div">, "children">;
+
+/** Displays generated content, preserving mounted components while queries load or fail. */
+function RendererContent({ style, hidden, ...props }: RendererContentSlotProps) {
+ const { root, query } = useRendererContext();
+ if (!root) return null;
+ return (
+ <div
+ {...props}
+ aria-busy={query.isLoading}
+ hidden={hidden || query.errors.length > 0}
+ style={{ opacity: query.isLoading ? 0.7 : 1, transition: "opacity 0.2s ease", ...style }}
+ >
+ <RenderNode node={root} />
+ </div>
+ );
+}
+
+export interface RendererSlotProps {
+ children?: React.ReactNode;
+}
+
+/** Shows query loading feedback, except while a query failure is being displayed. */
+function RendererQueryLoading({ children }: RendererSlotProps) {
+ const {
+ query: { isLoading, errors },
+ queryLoader,
+ } = useRendererContext();
+ if (!isLoading || errors.length > 0) return null;
+ return <>{children === undefined ? (queryLoader ?? <DefaultQueryLoader />) : children}</>;
+}
+
+/** Shows the supplied content when queries fail; renders nothing without children. */
+function RendererQueryError({ children }: RendererSlotProps) {
+ const { errors } = useRendererQuery();
+ if (errors.length === 0) return null;
+ return <>{children}</>;
+}
+
+export type RendererRetryProps = React.ComponentPropsWithRef<"button">;
+
+function RendererRetry({ children, onClick, disabled, ...props }: RendererRetryProps) {
+ const { retry, isLoading, errors } = useRendererQuery();
+ const isDisabled = disabled || isLoading || errors.length === 0;
+ return (
+ <button
+ type="button"
+ {...props}
+ disabled={isDisabled}
+ onClick={(event: React.MouseEvent<HTMLButtonElement>) => {
+ if (isDisabled || event.defaultPrevented) return;
+ onClick?.(event);
+ if (!event.defaultPrevented) retry();
+ }}
+ >
+ {children}
+ </button>
+ );
+}
+
+function DefaultRendererContent() {
+ const { root, query, queryLoader } = useRendererContext();
+ if (!root) return null;
+ return (
+ <div aria-busy={query.isLoading} style={{ position: "relative" }}>
+ {query.isLoading && (queryLoader ?? <DefaultQueryLoader />)}
+ <div style={{ opacity: query.isLoading ? 0.7 : 1, transition: "opacity 0.2s ease" }}>
+ <RenderNode node={root} />
+ </div>
+ </div>
+ );
+}
+
+function DefaultRenderer({ children, ...props }: RendererProps) {
+ return (
+ <RendererRoot {...props}>
+ {children === undefined ? <DefaultRendererContent /> : children}
+ </RendererRoot>
+ );
+}
+
+/** Render with the default presentation, or compose slots around one shared runtime. */
+export const Renderer = Object.assign(DefaultRenderer, {
+ Root: RendererRoot,
+ Content: RendererContent,
+ QueryLoading: RendererQueryLoading,
+ QueryError: RendererQueryError,
+ Retry: RendererRetry,
+});
diff --git a/packages/react-lang/src/WithPreviewRenderer.tsx b/packages/react-lang/src/WithPreviewRenderer.tsx
new file mode 100644
index 000000000..582b1ccf8
--- /dev/null
+++ b/packages/react-lang/src/WithPreviewRenderer.tsx
@@ -0,0 +1,192 @@
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useEffect,
+ useId,
+ useMemo,
+ useRef,
+ useState,
+ type ComponentPropsWithRef,
+} from "react";
+import { Renderer, type RendererProps } from "./Renderer";
+import { parseResponseBundle, type ResponseMetadata } from "./responseBundle";
+
+export interface RendererPreviewState {
+ metadata: ResponseMetadata;
+ isOpen: boolean;
+ isStreaming: boolean;
+ /** ID of the expanded content region. */
+ contentId: string;
+ open: () => void;
+ close: () => void;
+}
+
+export interface WithPreviewRendererProps extends RendererProps {
+ /** Controlled visibility. Omit to use internal state. */
+ open?: boolean;
+ /** Initial visibility when uncontrolled. Defaults to false. */
+ defaultOpen?: boolean;
+ onOpenChange?: (open: boolean) => void;
+ /** Metadata belongs to the preview presentation, not the underlying Renderer. */
+ onMetadata?: (metadata: ResponseMetadata) => void;
+ /** Compose Trigger, Content, and Close. Omit for the default preview and panel. */
+ children?: React.ReactNode;
+}
+
+const PreviewContext = createContext<{
+ state: RendererPreviewState;
+ rendererProps: RendererProps;
+} | null>(null);
+
+function usePreviewContext() {
+ const context = useContext(PreviewContext);
+ if (!context) {
+ throw new Error(
+ "Preview slots must be used within WithPreviewRenderer.Root or WithPreviewRenderer.",
+ );
+ }
+ return context;
+}
+
+/** Read metadata and control the nearest preview. Available even while its content is closed. */
+export function useRendererPreview(): RendererPreviewState {
+ return usePreviewContext().state;
+}
+
+function PreviewRoot({
+ open: controlledOpen,
+ defaultOpen = false,
+ onOpenChange,
+ onMetadata,
+ children,
+ ...rendererProps
+}: WithPreviewRendererProps) {
+ const [internalOpen, setInternalOpen] = useState(defaultOpen);
+ const isOpen = controlledOpen ?? internalOpen;
+ const isStreaming = rendererProps.isStreaming === true;
+ const contentId = useId();
+ const bundle = useMemo(
+ () => parseResponseBundle(rendererProps.response, isStreaming),
+ [rendererProps.response, isStreaming],
+ );
+ const metadataName = bundle.metadata.name;
+ const metadata = useMemo<ResponseMetadata>(
+ () => (metadataName === undefined ? {} : { name: metadataName }),
+ [metadataName],
+ );
+ const metadataCallback = useRef(onMetadata);
+ metadataCallback.current = onMetadata;
+ useEffect(() => {
+ metadataCallback.current?.(metadata);
+ }, [metadata]);
+
+ const setOpen = useCallback(
+ (next: boolean) => {
+ if (next === isOpen) return;
+ if (controlledOpen === undefined) setInternalOpen(next);
+ onOpenChange?.(next);
+ },
+ [controlledOpen, isOpen, onOpenChange],
+ );
+ const open = useCallback(() => setOpen(true), [setOpen]);
+ const close = useCallback(() => setOpen(false), [setOpen]);
+ const state = useMemo(
+ () => ({ metadata, isOpen, isStreaming, contentId, open, close }),
+ [metadata, isOpen, isStreaming, contentId, open, close],
+ );
+
+ return (
+ <PreviewContext.Provider value={{ state, rendererProps }}>{children}</PreviewContext.Provider>
+ );
+}
+
+export type PreviewButtonProps = ComponentPropsWithRef<"button">;
+
+function PreviewTrigger({ children, onClick, disabled, ...props }: PreviewButtonProps) {
+ const { metadata, isOpen, isStreaming, contentId, open, close } = useRendererPreview();
+ return (
+ <button
+ type="button"
+ {...props}
+ disabled={disabled}
+ aria-expanded={isOpen}
+ aria-controls={isOpen ? contentId : undefined}
+ onClick={(event) => {
+ if (disabled || event.defaultPrevented) return;
+ onClick?.(event);
+ if (!event.defaultPrevented) (isOpen ? close : open)();
+ }}
+ >
+ {children === undefined
+ ? `${metadata.name || "Untitled artifact"}${isStreaming ? " (generating…)" : ""}`
+ : children}
+ </button>
+ );
+}
+
+function PreviewClose({ children, onClick, disabled, ...props }: PreviewButtonProps) {
+ const { metadata, close } = useRendererPreview();
+ return (
+ <button
+ type="button"
+ {...props}
+ disabled={disabled}
+ onClick={(event) => {
+ if (disabled || event.defaultPrevented) return;
+ onClick?.(event);
+ if (!event.defaultPrevented) close();
+ }}
+ >
+ {children === undefined ? `Close ${metadata.name || "Untitled artifact"}` : children}
+ </button>
+ );
+}
+
+export type PreviewContentProps = ComponentPropsWithRef<"section">;
+
+/** Mount one content slot per preview. Query hooks and Renderer slots belong inside it. */
+function PreviewContent({ children, style, ...props }: PreviewContentProps) {
+ const { state, rendererProps } = usePreviewContext();
+ if (!state.isOpen) return null;
+ return (
+ <section
+ aria-label={state.metadata.name || "Untitled artifact"}
+ {...props}
+ id={state.contentId}
+ style={{ position: "relative", ...style }}
+ >
+ {children === undefined ? (
+ <>
+ <PreviewClose />
+ <Renderer {...rendererProps} />
+ </>
+ ) : (
+ <Renderer {...rendererProps}>{children}</Renderer>
+ )}
+ </section>
+ );
+}
+
+function DefaultWithPreviewRenderer({ children, ...props }: WithPreviewRendererProps) {
+ return (
+ <PreviewRoot {...props}>
+ {children === undefined ? (
+ <>
+ <PreviewTrigger />
+ <PreviewContent />
+ </>
+ ) : (
+ children
+ )}
+ </PreviewRoot>
+ );
+}
+
+/** Adds a preview and expandable content. Use Renderer for a directly visible interface. */
+export const WithPreviewRenderer = Object.assign(DefaultWithPreviewRenderer, {
+ Root: PreviewRoot,
+ Trigger: PreviewTrigger,
+ Content: PreviewContent,
+ Close: PreviewClose,
+});
diff --git a/packages/react-lang/src/exports.ts b/packages/react-lang/src/exports.ts
index 586c5ef99..2a2beb30e 100644
--- a/packages/react-lang/src/exports.ts
+++ b/packages/react-lang/src/exports.ts
@@ -14,8 +14,14 @@ export type {
} from "./library";
// openui-lang renderer
-export { Renderer } from "./Renderer";
-export type { RendererProps } from "./Renderer";
+export { Renderer, useRendererQuery } from "./Renderer";
+export type {
+ RendererContentSlotProps,
+ RendererProps,
+ RendererQueryState,
+ RendererRetryProps,
+ RendererSlotProps,
+} from "./Renderer";
// openui-lang action types
export { ACTION_STEPS, BuiltinActionType } from "@openuidev/lang-core";
@@ -86,3 +92,12 @@ export {
validate,
} from "@openuidev/lang-core";
export type { ParsedRule, ValidatorFn } from "@openuidev/lang-core";
+
+export type { ResponseMetadata } from "./responseBundle";
+export { WithPreviewRenderer, useRendererPreview } from "./WithPreviewRenderer";
+export type {
+ PreviewButtonProps,
+ PreviewContentProps,
+ RendererPreviewState,
+ WithPreviewRendererProps,
+} from "./WithPreviewRenderer";
diff --git a/packages/react-lang/src/hooks/useOpenUIState.ts b/packages/react-lang/src/hooks/useOpenUIState.ts
index 13df4cde6..7ff171c01 100644
--- a/packages/react-lang/src/hooks/useOpenUIState.ts
+++ b/packages/react-lang/src/hooks/useOpenUIState.ts
@@ -21,6 +21,7 @@ import type React from "react";
import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
import type { OpenUIContextValue } from "../context";
import type { Library } from "../library";
+import { parseResponseBundle } from "../responseBundle";
import { useOpenUIErrors } from "./useOpenUIErrors";
import { useStreamingObservability } from "./useStreamingObservability";
@@ -59,6 +60,9 @@ export interface OpenUIState {
contextValue: OpenUIContextValue;
/** Whether any Query is currently fetching data. */
isQueryLoading: boolean;
+ /** Failed queries whose fallback values must not be presented as current data. */
+ queryErrors: OpenUIError[];
+ retryQueries: () => void;
}
/**
@@ -82,16 +86,33 @@ export function useOpenUIState(
}: UseOpenUIStateOptions,
renderDeep: (value: unknown) => React.ReactNode,
): OpenUIState {
+ const bundle = useMemo(() => parseResponseBundle(response, isStreaming), [response, isStreaming]);
+ const blocked = isStreaming || !bundle.complete || !!bundle.error;
+ // Bare DSL keeps its existing manager, cached results and imperative actions while streaming.
+ const bundleBlocked = bundle.isBundle && blocked;
+ // Keep the last completed script revision while an edit streams its base and patches.
+ const settledScripts = useRef({ revision: null as string | null, names: new Set<string>() });
+ if (!blocked) {
+ settledScripts.current = {
+ revision: "scriptRevision" in bundle ? (bundle.scriptRevision ?? null) : null,
+ names: bundle.scripts,
+ };
+ }
+ const scriptRevision = settledScripts.current.revision;
+ const scriptNames = settledScripts.current.names;
+
// ─── Streaming parser (incremental — caches completed statements) ───
const sp = useMemo(() => createStreamingParser(library.toJSONSchema(), library.root), [library]);
// ─── Parse result ───
const parseExceptionRef = useRef<OpenUIError | null>(null);
const result = useMemo<ParseResult | null>(() => {
- parseExceptionRef.current = null;
- if (!response) return null;
+ parseExceptionRef.current = bundle.error
+ ? { source: "parser", code: "parse-failed", message: bundle.error }
+ : null;
+ if (!bundle.program) return null;
try {
- return sp.set(response);
+ return sp.set(bundle.program);
} catch (e) {
const msg = e instanceof Error ? e.message : String(e);
parseExceptionRef.current = {
@@ -102,7 +123,7 @@ export function useOpenUIState(
};
return null;
}
- }, [sp, response]);
+ }, [sp, bundle.program, bundle.error]);
// ─── Store (holds everything: $bindings + form fields) ───
const store = useMemo<Store>(() => createStore(), []);
@@ -164,19 +185,22 @@ export function useOpenUIState(
// ─── Evaluate and submit queries ───
useEffect(() => {
- if (isStreaming) return;
+ // Keep the existing query lifecycle until streaming finishes and the bundle is ready.
+ if (blocked) return;
const queryStmts = result?.queryStatements ?? [];
const evaluatedNodes = queryStmts.map((qn) => {
const relevantDeps: Record<string, unknown> = {};
+ const toolName = qn.toolAST ? (evaluate(qn.toolAST, evaluationContext) as string) : "";
if (qn.deps) {
for (const ref of qn.deps) {
relevantDeps[ref] = storeSnapshot[ref];
}
}
+ if (scriptNames.has(toolName)) relevantDeps.__openuiScriptRevision = scriptRevision;
return {
statementId: qn.statementId,
- toolName: qn.toolAST ? (evaluate(qn.toolAST, evaluationContext) as string) : "",
+ toolName,
args: qn.argsAST ? evaluate(qn.argsAST, evaluationContext) : null,
defaults: qn.defaultsAST ? evaluate(qn.defaultsAST, evaluationContext) : null,
refreshInterval: qn.refreshAST
@@ -189,11 +213,19 @@ export function useOpenUIState(
// Always call — empty array clears removed queries and their errors
queryManager.evaluateQueries(evaluatedNodes);
- }, [isStreaming, result?.queryStatements, evaluationContext, queryManager, storeSnapshot]);
+ }, [
+ blocked,
+ result?.queryStatements,
+ evaluationContext,
+ queryManager,
+ storeSnapshot,
+ scriptRevision,
+ scriptNames,
+ ]);
// ─── Register mutations ───
useEffect(() => {
- if (isStreaming) return;
+ if (blocked) return;
const mutStmts = result?.mutationStatements ?? [];
const nodes = mutStmts.map((mn) => ({
@@ -202,7 +234,7 @@ export function useOpenUIState(
}));
// Always call — empty array clears removed mutations and their errors
queryManager.registerMutations(nodes);
- }, [isStreaming, result?.mutationStatements, evaluationContext, queryManager]);
+ }, [blocked, result?.mutationStatements, evaluationContext, queryManager]);
// ─── Ref for stable callbacks ───
const propsRef = useRef({ onAction, onStateUpdate });
@@ -283,6 +315,7 @@ export function useOpenUIState(
formName?: string,
action?: ActionPlan | { type?: string; params?: Record<string, any> },
) => {
+ if (bundleBlocked) return;
const formPayload = getFormPayload(formName);
const { onAction: handler } = propsRef.current;
@@ -371,7 +404,7 @@ export function useOpenUIState(
formName,
});
},
- [queryManager, evaluationContext, getFormPayload, store],
+ [bundleBlocked, queryManager, evaluationContext, getFormPayload, store],
);
// ─── reportError (for error boundary) ───
@@ -384,35 +417,17 @@ export function useOpenUIState(
renderErrorsRef.current.push(error);
}, []);
- const isQueryLoading = querySnapshot.__openui_loading.length > 0;
-
- // ─── Context value ───
- const contextValue = useMemo<OpenUIContextValue>(
- () => ({
- library,
- renderNode: renderDeep,
- triggerAction,
- isStreaming,
- getFieldValue,
- setFieldValue,
- store,
- evaluationContext,
- reportError,
- isQueryLoading,
- }),
- [
- library,
- renderDeep,
- isStreaming,
- isQueryLoading,
- triggerAction,
- getFieldValue,
- setFieldValue,
- store,
- evaluationContext,
- reportError,
- ],
+ const isQueryLoading =
+ querySnapshot.__openui_loading.length > 0 ||
+ (isStreaming && bundleBlocked && (result?.queryStatements.length ?? 0) > 0);
+ const queryErrors = useMemo(
+ () => querySnapshot.__openui_errors.filter((error) => error.source === "query"),
+ [querySnapshot],
);
+ const retryQueries = useCallback(() => {
+ if (bundleBlocked) return;
+ queryManager.invalidate(queryErrors.map((error) => error.statementId!));
+ }, [bundleBlocked, queryManager, queryErrors]);
// ─── Evaluate props ───
const runtimeErrorsRef = useRef<OpenUIError[]>([]);
@@ -439,6 +454,33 @@ export function useOpenUIState(
}
}, [result, evaluationContext, library, store, storeSnapshot, querySnapshot]);
+ const contextValue = useMemo<OpenUIContextValue>(
+ () => ({
+ library,
+ renderNode: renderDeep,
+ triggerAction,
+ isStreaming: blocked,
+ getFieldValue,
+ setFieldValue,
+ store,
+ evaluationContext,
+ reportError,
+ isQueryLoading,
+ }),
+ [
+ library,
+ renderDeep,
+ blocked,
+ isQueryLoading,
+ triggerAction,
+ getFieldValue,
+ setFieldValue,
+ store,
+ evaluationContext,
+ reportError,
+ ],
+ );
+
// Keep error collection first: its effect refreshes this ref before the
// observability effect publishes the terminal stream event.
const { errorsRef, errorRevision } = useOpenUIErrors({
@@ -455,7 +497,7 @@ export function useOpenUIState(
});
useStreamingObservability({
- response,
+ response: bundle.program,
isStreaming,
result,
errorsRef,
@@ -464,5 +506,12 @@ export function useOpenUIState(
__libraryId: library.__libraryId,
});
- return { result: evaluatedResult, parseResult: result, contextValue, isQueryLoading };
+ return {
+ result: evaluatedResult,
+ parseResult: result,
+ contextValue,
+ isQueryLoading,
+ queryErrors,
+ retryQueries,
+ };
}
diff --git a/packages/react-lang/src/responseBundle.test.ts b/packages/react-lang/src/responseBundle.test.ts
new file mode 100644
index 000000000..532667804
--- /dev/null
+++ b/packages/react-lang/src/responseBundle.test.ts
@@ -0,0 +1,244 @@
+import { describe, expect, it } from "vitest";
+import { parseResponseBundle } from "./responseBundle";
+
+const program = '```openui-lang\nroot = Text("Hello")\n```\n';
+const script = { name: "sales_total", code: "async ({ tools }) => tools.get_sales({})" };
+
+function scriptsSection(values: unknown, count: unknown = 1) {
+ return `]]>openui:scripts ${JSON.stringify({ count })}\n${JSON.stringify(values)}\n`;
+}
+
+describe("parseResponseBundle", () => {
+ describe("plain programs", () => {
+ it.each([null, "", " \n", 'root = Text("Hello")', program])(
+ "preserves an unframed response: %j",
+ (response) => {
+ for (const streaming of [false, true]) {
+ expect(parseResponseBundle(response, streaming)).toEqual({
+ program: response ?? "",
+ metadata: {},
+ scripts: new Set(),
+ complete: true,
+ isBundle: false,
+ error: undefined,
+ });
+ }
+ },
+ );
+ });
+
+ describe("content and metadata", () => {
+ it("decodes the optional name and separates the program from its envelope", () => {
+ const response = ` \n]]>openui:content?thesys=true&name=Sales+%26+Growth+%E2%82%AC\n${program}]]>openui:end\n`;
+
+ expect(parseResponseBundle(response, false)).toEqual({
+ program,
+ metadata: { name: "Sales & Growth €" },
+ scripts: new Set(),
+ complete: true,
+ isBundle: true,
+ error: undefined,
+ });
+ });
+
+ it("accepts a bundle without metadata or scripts", () => {
+ const response = `]]>openui:content\n${program}]]>openui:end`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program,
+ metadata: {},
+ complete: true,
+ error: undefined,
+ });
+ });
+
+ it("handles Windows line endings", () => {
+ const response = `]]>openui:content?name=Sales\r\n${program.replaceAll("\n", "\r\n")}${scriptsSection([script]).replaceAll("\n", "\r\n")}]]>openui:end\r\n`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program: program.replaceAll("\n", "\r\n"),
+ metadata: { name: "Sales" },
+ scripts: new Set(["sales_total"]),
+ complete: true,
+ error: undefined,
+ });
+ });
+
+ it("uses the latest content section without retaining old scripts or metadata", () => {
+ const previous = `]]>openui:content?name=Previous\n${program}${scriptsSection([script])}]]>openui:end\n`;
+ const replacement = 'root = Text("Updated")\n';
+ const response = `${previous}]]>openui:content\n${replacement}]]>openui:end`;
+
+ expect(parseResponseBundle(response, false)).toEqual({
+ program: replacement,
+ metadata: {},
+ scripts: new Set(),
+ complete: true,
+ isBundle: true,
+ error: undefined,
+ });
+ });
+ });
+
+ describe("scripts", () => {
+ it("extracts script names without including script definitions in the program", () => {
+ const values = [script, { name: "save_sales", code: "async () => null" }];
+ const response = `]]>openui:content\n${program}${scriptsSection(values, 2)}]]>openui:end`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program,
+ scripts: new Set(["sales_total", "save_sales"]),
+ complete: true,
+ error: undefined,
+ });
+ });
+
+ it("accepts an explicitly empty scripts section", () => {
+ const response = `]]>openui:content\n${program}${scriptsSection([], 0)}]]>openui:end`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ scripts: new Set(),
+ complete: true,
+ error: undefined,
+ });
+ });
+
+ it.each(["", "]]>openui:end"])("accepts a legacy script bundle with end marker %j", (end) => {
+ const response = `${program}${scriptsSection([script])}${end}`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program,
+ isBundle: true,
+ scripts: new Set(["sales_total"]),
+ complete: true,
+ error: undefined,
+ });
+ });
+
+ it.each([
+ ["non-array payload", {}, 1],
+ ["null payload", null, 1],
+ ["mismatched count", [script], 2],
+ ["string count", [script], "1"],
+ ["fractional count", [script], 1.5],
+ ["negative count", [], -1],
+ ["null entry", [null], 1],
+ ["missing name", [{ code: "async () => null" }], 1],
+ ["empty name", [{ ...script, name: "" }], 1],
+ ["non-string name", [{ ...script, name: 42 }], 1],
+ ["missing code", [{ name: "sales_total" }], 1],
+ ["non-string code", [{ ...script, code: 42 }], 1],
+ ["duplicate names", [script, script], 2],
+ ])("rejects %s after streaming finishes", (_label, values, count) => {
+ const response = `]]>openui:content\n${program}${scriptsSection(values, count)}]]>openui:end`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program,
+ complete: false,
+ error: "Invalid scripts bundle",
+ });
+ expect(parseResponseBundle(response, true)).toMatchObject({
+ program,
+ complete: false,
+ error: undefined,
+ });
+ });
+
+ it.each(["]]>openui:scripts {invalid}\n[]\n", ']]>openui:scripts {"count":1}\n[{"name":\n'])(
+ "rejects malformed script JSON: %j",
+ (section) => {
+ const response = `]]>openui:content\n${program}${section}]]>openui:end`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program,
+ complete: false,
+ error: "Invalid scripts bundle",
+ });
+ },
+ );
+ });
+
+ describe("streaming and incomplete responses", () => {
+ it("keeps every partial chunk error-free and exposes the program progressively", () => {
+ const header = "]]>openui:content?name=Sales\n";
+ const response = `${header}${program}${scriptsSection([script])}]]>openui:end`;
+
+ for (let length = 1; length <= response.length; length++) {
+ const parsed = parseResponseBundle(response.slice(0, length), true);
+ expect(parsed.error, `prefix length ${length}`).toBeUndefined();
+ expect(parsed.complete, `prefix length ${length}`).toBe(length === response.length);
+ expect(parsed.isBundle).toBe(true);
+ const visibleLength = Math.max(0, Math.min(program.length, length - header.length));
+ expect(parsed.program).toBe(program.slice(0, visibleLength));
+ }
+ });
+
+ it.each(["]]", "]]>openui:content?name=Sales"])(
+ "reports an unfinished header only when streaming stops: %j",
+ (response) => {
+ expect(parseResponseBundle(response, true)).toMatchObject({
+ program: "",
+ complete: false,
+ error: undefined,
+ });
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program: "",
+ complete: false,
+ error: "Incomplete response header",
+ });
+ },
+ );
+
+ it.each([
+ "",
+ "]]>openui:scripts",
+ scriptsSection([script]),
+ "]]>openui:unknown",
+ "]]>openui:end\nunexpected content",
+ ])("does not mark an unfinished or invalid envelope complete: %j", (tail) => {
+ const response = `]]>openui:content\n${program}${tail}`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program,
+ complete: false,
+ error: "Incomplete response bundle",
+ });
+ });
+ });
+
+ describe("markers inside content", () => {
+ it.each([
+ 'root = Text("]]>openui:scripts")\n',
+ "root = Text(']]>openui:end')\n",
+ String.raw`root = Text("An escaped quote: \" and marker: ]]>openui:end")` + "\n",
+ String.raw`root = Text("A trailing backslash: \\")` + "\n",
+ '// Ignore "]]>openui:scripts\nroot = Text("Hello")\n',
+ '# Ignore \' ]]>openui:end\nroot = Text("Hello")\n',
+ ])("preserves literal markers and comments: %j", (content) => {
+ expect(parseResponseBundle(content, false)).toMatchObject({
+ program: content,
+ isBundle: false,
+ error: undefined,
+ });
+ expect(
+ parseResponseBundle(`]]>openui:content\n${content}]]>openui:end`, false),
+ ).toMatchObject({
+ program: content,
+ complete: true,
+ error: undefined,
+ });
+ });
+
+ it("does not treat marker text inside script code as the end of the payload", () => {
+ const code = String.raw`async () => "Escaped quote: \"; ]]>openui:end; ]]>openui:scripts"`;
+ const response = `]]>openui:content\n${program}${scriptsSection([{ ...script, code }])}]]>openui:end`;
+
+ expect(parseResponseBundle(response, false)).toMatchObject({
+ program,
+ scripts: new Set(["sales_total"]),
+ complete: true,
+ error: undefined,
+ });
+ });
+ });
+});
diff --git a/packages/react-lang/src/responseBundle.ts b/packages/react-lang/src/responseBundle.ts
new file mode 100644
index 000000000..3135cd02c
--- /dev/null
+++ b/packages/react-lang/src/responseBundle.ts
@@ -0,0 +1,125 @@
+/** Metadata emitted by OpenUI Cloud. */
+export interface ResponseMetadata {
+ name?: string;
+}
+
+const CONTENT = "]]>openui:content";
+const SCRIPTS = "]]>openui:scripts";
+const END = "]]>openui:end";
+
+// Markers inside DSL/JSON strings are ordinary content.
+function markerIndex(text: string, partial = false): number {
+ let quote = "";
+ let escaped = false;
+ for (let i = 0; i < text.length; i++) {
+ const c = text[i];
+ if (quote) {
+ if (escaped) escaped = false;
+ else if (c === "\\") escaped = true;
+ else if (c === quote) quote = "";
+ } else if (c === "#" || (c === "/" && text[i + 1] === "/")) {
+ const newline = text.indexOf("\n", i);
+ if (newline < 0) return -1;
+ i = newline;
+ } else if (c === '"' || c === "'") quote = c;
+ else if (text.startsWith("]]>", i) || (partial && "]]>".startsWith(text.slice(i)))) return i;
+ }
+ return -1;
+}
+
+export function parseResponseBundle(response: string | null, streaming: boolean) {
+ let program = response ?? "";
+ const metadata: ResponseMetadata = {};
+ const scripts = new Set<string>();
+ let scriptRevision: string | undefined;
+ let error: string | undefined;
+ let complete = true;
+ let framed = false;
+ let body = program.trimStart();
+ if (body && (body.startsWith(CONTENT) || CONTENT.startsWith(body))) {
+ framed = true;
+ // A new content section replaces a progressive preview or failed retry.
+ const sections = [...body.matchAll(/^\]\]>openui:content(?:\?[^\r\n]*)?\r?$/gm)];
+ const last = sections[sections.length - 1];
+ if (last) body = body.slice(last.index);
+ const newline = body.indexOf("\n");
+ if (newline < 0)
+ return {
+ isBundle: true,
+ program: "",
+ metadata,
+ scripts,
+ complete: false,
+ error: streaming ? undefined : "Incomplete response header",
+ };
+ const header = body.slice(0, newline).trimEnd();
+ const name = new URLSearchParams(header.slice(CONTENT.length).replace(/^\?/, "")).get("name");
+ if (name !== null) metadata.name = name;
+ body = body.slice(newline + 1);
+ }
+ program = body;
+ const marker = markerIndex(body, framed && streaming);
+ const isBundle = framed || marker >= 0;
+ if (!isBundle) {
+ return { program: response ?? "", metadata, scripts, complete, isBundle, error };
+ }
+ if (marker >= 0) {
+ program = body.slice(0, marker);
+ let tail = body.slice(marker).trimEnd();
+ if (tail.startsWith(SCRIPTS)) {
+ complete = false;
+ const newline = tail.indexOf("\n");
+ if (newline >= 0) {
+ try {
+ const header = JSON.parse(tail.slice(SCRIPTS.length, newline));
+ let payload = tail.slice(newline + 1);
+ const end = markerIndex(payload);
+ if (end >= 0) {
+ tail = payload.slice(end).trim();
+ payload = payload.slice(0, end);
+ } else tail = "";
+ const values: unknown = JSON.parse(payload);
+ if (
+ !Array.isArray(values) ||
+ !Number.isSafeInteger(header.count) ||
+ header.count !== values.length
+ )
+ throw new Error("Invalid script count");
+ for (const script of values) {
+ if (
+ !script ||
+ typeof script.name !== "string" ||
+ !script.name ||
+ typeof script.code !== "string" ||
+ scripts.has(script.name)
+ )
+ throw new Error("Invalid or duplicate script definition");
+ scripts.add(script.name);
+ }
+ scriptRevision = JSON.stringify(
+ values
+ .map((script) => ({ name: script.name as string, code: script.code as string }))
+ .sort((a, b) => a.name.localeCompare(b.name)),
+ );
+ complete = framed ? tail === END : tail === "" || tail === END;
+ if (!complete) error = "Incomplete response bundle";
+ } catch {
+ error = "Invalid scripts bundle";
+ }
+ }
+ } else {
+ complete = tail === END;
+ if (!complete) error = "Incomplete response bundle";
+ }
+ } else if (framed) complete = false;
+ if (!complete && !streaming) error ??= "Incomplete response bundle";
+ return {
+ program,
+ metadata,
+ scripts,
+ complete,
+ isBundle,
+ error: streaming ? undefined : error,
+ ...(scripts.size ? { scriptRevision } : {}),
+ };
+}
diff --git a/packages/server/src/shared/abort.ts b/packages/server/src/shared/abort.ts
new file mode 100644
index 000000000..ba7820059
--- /dev/null
+++ b/packages/server/src/shared/abort.ts
@@ -0,0 +1,14 @@
+/** Stop waiting even when an upstream request or customer tool ignores cancellation. */
+export async function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+ signal.throwIfAborted();
+ let abort!: () => void;
+ const cancelled = new Promise<never>((_, reject) => {
+ abort = () => reject(signal.reason);
+ signal.addEventListener("abort", abort, { once: true });
+ });
+ try {
+ return await Promise.race([promise, cancelled]);
+ } finally {
+ signal.removeEventListener("abort", abort);
+ }
+}
diff --git a/packages/server/src/tools/execute.ts b/packages/server/src/tools/execute.ts
new file mode 100644
index 000000000..e3d887923
--- /dev/null
+++ b/packages/server/src/tools/execute.ts
@@ -0,0 +1,228 @@
+import { abortable } from "../shared/abort";
+import { THESYS_API_BASE_URL } from "../shared/constants";
+import {
+ ToolExecutionError,
+ type RegisteredTools,
+ type ScriptToolCall,
+ type ScriptToolResult,
+ type ToolExecutionOptions,
+ type ToolExecutionRequest,
+ type ToolExecutorOptions,
+} from "./types";
+
+const MAX_ROUNDS = 8;
+const MAX_TOOL_CALLS = 16;
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+ value !== null && typeof value === "object" && !Array.isArray(value);
+
+function invalidResponse(): never {
+ throw new ToolExecutionError("Invalid script execution response", "invalid_response", 502);
+}
+
+/** Register server tools once, then execute direct tools or generated script loops. */
+export function createToolExecutor<Context = undefined>(
+ options: ToolExecutorOptions<Context>,
+): RegisteredTools<Context> {
+ const entries = Object.entries(options.tools);
+ const tools = Object.fromEntries(entries.map(([name, tool]) => [name, tool.execute]));
+ const definitions = entries.map(([name, { description, parameters, output }]) => ({
+ name,
+ parameters,
+ ...(description !== undefined && { description }),
+ ...(output !== undefined && { output }),
+ }));
+ const endpoint = `${(options.apiBaseUrl ?? THESYS_API_BASE_URL).replace(/\/+$/, "")}/v1/app/execute`;
+ const fetchFn = options.fetch ?? globalThis.fetch;
+ const apiKey = options.apiKey;
+
+ async function execute(
+ input: ToolExecutionRequest,
+ executionOptions?: ToolExecutionOptions<Context>,
+ ): Promise<unknown> {
+ if (!input || typeof input.name !== "string" || !input.name) {
+ throw new ToolExecutionError("A tool name is required", "invalid_input");
+ }
+ const args = input.arguments ?? {};
+ if (!isRecord(args))
+ throw new ToolExecutionError("Tool arguments must be an object", "invalid_input");
+ const timeoutMs = executionOptions?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+ throw new ToolExecutionError("timeoutMs must be a positive finite number", "invalid_input");
+ }
+ executionOptions?.signal?.throwIfAborted();
+ const controller = new AbortController();
+ const forwardAbort = () => controller.abort(executionOptions?.signal?.reason);
+ executionOptions?.signal?.addEventListener("abort", forwardAbort, { once: true });
+ const timer = setTimeout(
+ () =>
+ controller.abort(new ToolExecutionError("Tool execution timed out", "tool_timeout", 504)),
+ timeoutMs,
+ );
+ const signal = controller.signal;
+
+ const dispatch = async (name: string, toolArgs: Record<string, unknown>) => {
+ signal.throwIfAborted();
+ if (!Object.hasOwn(tools, name) || typeof tools[name] !== "function") {
+ throw new ToolExecutionError(`Unknown customer tool: ${name}`, "tool_not_found", 404);
+ }
+ return abortable(
+ Promise.resolve().then(() =>
+ tools[name]!(toolArgs, { context: executionOptions?.context as Context, signal }),
+ ),
+ signal,
+ );
+ };
+
+ try {
+ if (Object.hasOwn(tools, input.name)) return await dispatch(input.name, args);
+ if (typeof input.response !== "string" || !input.response.trim()) {
+ throw new ToolExecutionError(
+ `Unknown tool: ${input.name}. Supply a complete OpenUI response for script execution.`,
+ "tool_not_found",
+ 404,
+ );
+ }
+
+ if (!apiKey?.trim()) {
+ throw new ToolExecutionError(
+ "Pass apiKey to createToolExecutor to execute generated scripts",
+ "missing_api_key",
+ );
+ }
+
+ let state: string | undefined;
+ let toolResults: ScriptToolResult[] = [];
+ const seen = new Set<string>();
+ // Allow a final settlement request after the last tool-call round.
+ for (let round = 0; round <= MAX_ROUNDS; round++) {
+ const response = await abortable(
+ executeRound(
+ {
+ response: input.response,
+ name: input.name,
+ arguments: args,
+ tool_results: toolResults,
+ ...(state !== undefined && { state }),
+ },
+ signal,
+ ),
+ signal,
+ );
+ if (!isRecord(response)) invalidResponse();
+ if (response["status"] === "done") return response["result"];
+ if (response["status"] === "error") {
+ const error = response["error"];
+ if (
+ !isRecord(error) ||
+ typeof error["code"] !== "string" ||
+ typeof error["message"] !== "string"
+ )
+ invalidResponse();
+ // Never replay tools after a failed snapshot: a prior call may have mutated data.
+ throw new ToolExecutionError(error["message"], error["code"]);
+ }
+ const calls = response["calls"];
+ if (
+ response["status"] !== "tool_calls" ||
+ typeof response["state"] !== "string" ||
+ !response["state"] ||
+ !Array.isArray(calls) ||
+ !calls.length
+ )
+ invalidResponse();
+ if (round === MAX_ROUNDS || seen.size + calls.length > MAX_TOOL_CALLS) {
+ throw new ToolExecutionError("Script execution limit exceeded", "script_limit", 502);
+ }
+ // Validate the complete batch before any customer tool starts.
+ for (const call of calls) {
+ if (
+ !isRecord(call) ||
+ (call["type"] !== undefined && call["type"] !== "function_call") ||
+ typeof call["call_id"] !== "string" ||
+ !call["call_id"] ||
+ seen.has(call["call_id"]) ||
+ typeof call["name"] !== "string" ||
+ !call["name"] ||
+ typeof call["arguments"] !== "string"
+ )
+ invalidResponse();
+ seen.add(call["call_id"]);
+ }
+ state = response["state"];
+ toolResults = await Promise.all(
+ (calls as ScriptToolCall[]).map(async (call): Promise<ScriptToolResult> => {
+ try {
+ const toolArgs: unknown = JSON.parse(call.arguments);
+ if (!isRecord(toolArgs))
+ throw new ToolExecutionError("Tool arguments must be an object", "bad_args");
+ const result = await dispatch(call.name, toolArgs);
+ signal.throwIfAborted();
+ const output = JSON.stringify(result ?? null);
+ if (output === undefined)
+ throw new ToolExecutionError(
+ "Tool result must be JSON serializable",
+ "bad_tool_result",
+ );
+ return {
+ type: "function_call_output",
+ call_id: call.call_id,
+ output,
+ };
+ } catch (error) {
+ signal.throwIfAborted();
+ return {
+ call_id: call.call_id,
+ error: {
+ code: error instanceof ToolExecutionError ? error.code : "tool_exec_error",
+ message: error instanceof Error ? error.message : String(error),
+ },
+ };
+ }
+ }),
+ );
+ }
+ throw new ToolExecutionError("Script execution limit exceeded", "script_limit", 502);
+ } finally {
+ clearTimeout(timer);
+ executionOptions?.signal?.removeEventListener("abort", forwardAbort);
+ controller.abort();
+ }
+ }
+
+ async function executeRound(body: unknown, signal: AbortSignal): Promise<unknown> {
+ signal.throwIfAborted();
+ const response = await fetchFn(endpoint, {
+ method: "POST",
+ headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+ body: JSON.stringify(body),
+ signal,
+ });
+ let result: unknown;
+ try {
+ result = await response.json();
+ } catch {
+ signal.throwIfAborted();
+ throw new ToolExecutionError(
+ `Could not read script execution response (HTTP ${response.status})`,
+ "invalid_response",
+ response.status,
+ );
+ }
+ signal.throwIfAborted();
+ if (!response.ok) {
+ const error = isRecord(result) && isRecord(result["error"]) ? result["error"] : undefined;
+ throw new ToolExecutionError(
+ typeof error?.["message"] === "string"
+ ? error["message"]
+ : `Script execution failed: HTTP ${response.status}`,
+ typeof error?.["code"] === "string" ? error["code"] : "http_error",
+ response.status,
+ );
+ }
+ return result;
+ }
+
+ return { definitions, execute };
+}
diff --git a/packages/server/src/tools/types.ts b/packages/server/src/tools/types.ts
new file mode 100644
index 000000000..677963bb6
--- /dev/null
+++ b/packages/server/src/tools/types.ts
@@ -0,0 +1,73 @@
+/** Provider-neutral metadata passed to generation, without server handlers. */
+export interface ToolDefinition {
+ name: string;
+ description?: string;
+ parameters: Record<string, unknown>;
+ /** Illustrative output for generation; the handler supplies actual runtime data. */
+ output?: unknown;
+}
+
+/** Registered customer tools execute on the host server with trusted context. */
+export type ToolHandler<Context = undefined> = (
+ args: Record<string, unknown>,
+ options: { context: Context; signal: AbortSignal },
+) => unknown | Promise<unknown>;
+
+export type ToolRegistration<Context = undefined> = Omit<ToolDefinition, "name"> & {
+ execute: ToolHandler<Context>;
+};
+
+export interface ToolExecutionRequest {
+ name: string;
+ arguments?: Record<string, unknown>;
+ /** Complete generated response. Required for script names, optional for direct tools. */
+ response?: string;
+}
+
+export type ToolExecutionOptions<Context = undefined> = {
+ signal?: AbortSignal;
+ /** Total execution budget, including customer tools. Default: 60 seconds. */
+ timeoutMs?: number;
+} & (undefined extends Context ? { context?: Context } : { context: Context });
+
+export interface ToolExecutorOptions<Context = undefined> {
+ tools: Record<string, ToolRegistration<Context>>;
+ /** Required for generated scripts. Direct registered tools do not need a Gateway key. */
+ apiKey?: string;
+ /** Gateway origin, without /v1. Defaults to https://api.thesys.dev. */
+ apiBaseUrl?: string;
+ fetch?: typeof globalThis.fetch;
+}
+
+export interface RegisteredTools<Context = undefined> {
+ definitions: ToolDefinition[];
+ execute(
+ input: ToolExecutionRequest,
+ ...options: undefined extends Context
+ ? [options?: ToolExecutionOptions<Context>]
+ : [options: ToolExecutionOptions<Context>]
+ ): Promise<unknown>;
+}
+
+export interface ScriptToolCall {
+ type?: "function_call";
+ call_id: string;
+ name: string;
+ arguments: string;
+}
+
+export type ScriptToolResult =
+ | { type: "function_call_output"; call_id: string; output: string }
+ | { call_id: string; error: { code: string; message: string } };
+
+/** Execution failures expose a stable code and an optional HTTP status. */
+export class ToolExecutionError extends Error {
+ constructor(
+ message: string,
+ readonly code: string,
+ readonly status?: number,
+ ) {
+ super(message);
+ this.name = "ToolExecutionError";
+ }
+}