The Open Standard for Generative UI
import {
ACTION_STEPS,
BuiltinActionType,
createQueryManager,
createStore,
createStreamingParser,
evaluate,
evaluateRoot,
type ActionEvent,
type ActionPlan,
type EvalContext,
type EvaluationContext,
type OpenUIError,
type ParseResult,
type QueryManager,
type QuerySnapshot,
type Store,
type ToolProvider,
} from "@openuidev/lang-core";
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";
/** Unwrap { value, componentType } wrapper from form field entries. Returns raw value. */
function unwrapFieldValue(v: unknown): unknown {
if (
v &&
typeof v === "object" &&
!Array.isArray(v) &&
"value" in (v as Record<string, unknown>)
) {
return (v as Record<string, unknown>).value;
}
return v;
}
export interface UseOpenUIStateOptions {
/** Raw response: openui-lang code, or a stored message with protocol markers. */
response: string | null;
library: Library;
isStreaming: boolean;
onAction?: (event: ActionEvent) => void;
onStateUpdate?: (state: Record<string, unknown>) => void;
initialState?: Record<string, any>;
/** ToolProvider for Query data fetching — MCP, REST, GraphQL, or any backend. */
toolProvider?: ToolProvider | null;
/** Callback for structured, LLM-friendly errors. See OpenUIError type. */
onError?: (errors: OpenUIError[]) => void;
publishObservability?: boolean;
}
export interface OpenUIState {
/** Evaluated result (props resolved to concrete values). Used by Renderer. */
result: ParseResult | null;
/** Raw parse result (AST nodes in props). Used by onParseResult callback. */
parseResult: ParseResult | null;
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;
}
/**
* Core state hook — extracts all form state, action handling, parser
* management, and context assembly out of the Renderer component.
*
* Store holds everything: $bindings as top-level keys, form fields nested
* under formName as plain values.
*/
export function useOpenUIState(
{
response: raw,
library,
isStreaming,
onAction,
onStateUpdate,
initialState,
toolProvider,
onError,
publishObservability,
}: UseOpenUIStateOptions,
renderDeep: (value: unknown) => React.ReactNode,
): OpenUIState {
// Strip protocol markers and read Cloud scripts; plain responses pass through unchanged.
const bundle = useMemo(() => parseResponseBundle(raw, isStreaming), [raw, 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 schema = useMemo(() => library.toJSONSchema(), [library]);
const sp = useMemo(() => createStreamingParser(schema, library.root), [schema, library.root]);
// Library functions: the schema's entries plus each `fn`, for the evaluator
const functions = useMemo(
() =>
Object.fromEntries(
Object.entries(schema.functions ?? {}).flatMap(([name, s]) => {
// A hand-built library may list a function in its schema without an implementation
const fn = library.functions?.[name]?.fn;
return fn ? [[name, { ...s, fn }]] : [];
}),
),
[schema, library.functions],
);
// ─── Parse result ───
const parseExceptionRef = useRef<OpenUIError | null>(null);
const result = useMemo<ParseResult | null>(() => {
parseExceptionRef.current = bundle.error
? { source: "parser", code: "parse-failed", message: bundle.error }
: null;
if (!bundle.program) return null;
try {
return sp.set(bundle.program, !isStreaming);
} catch (e) {
const msg = e instanceof Error ? e.message : String(e);
parseExceptionRef.current = {
source: "parser",
code: "parse-exception",
message: `Parser crashed: ${msg}`,
hint: "The response may contain syntax the parser cannot handle",
};
return null;
}
}, [sp, bundle.program, bundle.error, isStreaming]);
// ─── Store (holds everything: $bindings + form fields) ───
const store = useMemo<Store>(() => createStore(), []);
// ─── QueryManager ───
const queryManager = useMemo<QueryManager>(
() => createQueryManager(toolProvider ?? null),
[toolProvider],
);
useEffect(() => {
queryManager.activate();
return () => queryManager.dispose();
}, [queryManager]);
// ─── Initialize Store ───
// Declared defaults are not a user change, so they do not fire onStateUpdate: a saved
// default read from a half-streamed statement would come back as initialState and stick.
const initializingRef = useRef(false);
const storeInitKeyRef = useRef<unknown>(Symbol());
useEffect(() => {
if (!result?.stateDeclarations && !initialState) return;
const key = `${JSON.stringify(result?.stateDeclarations)}::${JSON.stringify(initialState)}`;
if (storeInitKeyRef.current === key) return;
storeInitKeyRef.current = key;
// Split initialState: $-prefixed keys are bindings, everything else is form state
const bindingDefaults: Record<string, unknown> = {};
if (initialState) {
for (const [key, value] of Object.entries(initialState)) {
if (key.startsWith("$")) {
bindingDefaults[key] = value;
} else {
// Form state — restore as-is (preserves { value, componentType } wrapper)
store.set(key, value);
}
}
}
initializingRef.current = true;
store.initialize(result?.stateDeclarations ?? {}, bindingDefaults);
initializingRef.current = false;
}, [result?.stateDeclarations, store, initialState]);
// ─── Subscribe to Store and QueryManager for re-renders ───
const storeSnapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
const querySnapshot = useSyncExternalStore(
queryManager.subscribe,
queryManager.getSnapshot,
queryManager.getSnapshot,
) as QuerySnapshot;
// ─── Build EvaluationContext ───
const evaluationContext = useMemo<EvaluationContext>(
() => ({
getState: (name: string) => unwrapFieldValue(store.get(name)),
resolveRef: (name: string) => {
const mutResult = queryManager.getMutationResult(name);
if (mutResult) return mutResult;
return queryManager.getResult(name);
},
functions,
actions: schema.actions,
}),
[store, queryManager, functions, schema.actions],
);
// ─── Evaluate and submit queries ───
useEffect(() => {
// 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,
args: qn.argsAST ? evaluate(qn.argsAST, evaluationContext) : null,
defaults: qn.defaultsAST ? evaluate(qn.defaultsAST, evaluationContext) : null,
refreshInterval: qn.refreshAST
? (evaluate(qn.refreshAST, evaluationContext) as number)
: undefined,
deps: Object.keys(relevantDeps).length > 0 ? relevantDeps : undefined,
complete: qn.complete,
};
});
// Always call — empty array clears removed queries and their errors
queryManager.evaluateQueries(evaluatedNodes);
}, [
blocked,
result?.queryStatements,
evaluationContext,
queryManager,
storeSnapshot,
scriptRevision,
scriptNames,
]);
// ─── Register mutations ───
useEffect(() => {
if (blocked) return;
const mutStmts = result?.mutationStatements ?? [];
const nodes = mutStmts.map((mn) => ({
statementId: mn.statementId,
toolName: mn.toolAST ? (evaluate(mn.toolAST, evaluationContext) as string) : "",
}));
// Always call — empty array clears removed mutations and their errors
queryManager.registerMutations(nodes);
}, [blocked, result?.mutationStatements, evaluationContext, queryManager]);
// ─── Ref for stable callbacks ───
const propsRef = useRef({ onAction, onStateUpdate });
propsRef.current = { onAction, onStateUpdate };
const resultRef = useRef(result);
resultRef.current = result;
// ─── Fire onStateUpdate when Store changes ───
const lastInitSnapshotRef = useRef<Record<string, unknown> | null>(null);
useEffect(() => {
lastInitSnapshotRef.current = store.getSnapshot();
const unsub = store.subscribe(() => {
const currentSnapshot = store.getSnapshot();
if (initializingRef.current || currentSnapshot === lastInitSnapshotRef.current) return;
lastInitSnapshotRef.current = null;
propsRef.current.onStateUpdate?.(currentSnapshot);
});
return unsub;
}, [store]);
// ─── getFieldValue ───
const getFieldValue = useCallback(
(formName: string | undefined, name: string) => {
if (!formName) return unwrapFieldValue(store.get(name));
const formData = store.get(formName);
if (!formData || typeof formData !== "object" || Array.isArray(formData)) return undefined;
return unwrapFieldValue((formData as Record<string, unknown>)[name]);
},
[store],
);
// ─── setFieldValue ───
const setFieldValue = useCallback(
(
formName: string | undefined,
componentType: string | undefined,
name: string,
value: unknown,
shouldTriggerSaveCallback: boolean = true,
) => {
const wrapped = { value, componentType };
if (!formName) {
store.set(name, wrapped);
} else {
const raw = store.get(formName);
const formData =
raw && typeof raw === "object" && !Array.isArray(raw)
? (raw as Record<string, unknown>)
: {};
store.set(formName, { ...formData, [name]: wrapped });
}
if (shouldTriggerSaveCallback) {
propsRef.current.onStateUpdate?.(store.getSnapshot());
}
},
[store],
);
// ─── Materialize form payload ───
const getFormPayload = useCallback(
(formName?: string): Record<string, unknown> | undefined => {
if (formName) {
const raw = store.get(formName);
if (raw && typeof raw === "object" && !Array.isArray(raw)) {
return { [formName]: raw };
}
}
return store.getSnapshot();
},
[store],
);
// ─── triggerAction ───
const triggerAction = useCallback(
async (
userMessage: string,
formName?: string,
action?: ActionPlan | { type?: string; params?: Record<string, any> },
) => {
if (bundleBlocked) return;
const { onAction: handler } = propsRef.current;
// Legacy action config path (v0.1 compat) — { type?, params? }
if (action && !("steps" in action)) {
const formPayload = getFormPayload(formName);
const actionType = action.type || BuiltinActionType.ContinueConversation;
// Only a real call delivers a custom action; a legacy object cannot pose as one
if (schema.actions && Object.prototype.hasOwnProperty.call(schema.actions, actionType))
return;
const params = { ...(action.params || {}) };
// v0.1 compat — url and context were top-level, not in params
if ((action as any).url) params.url = (action as any).url;
if ((action as any).context) params.context = (action as any).context;
handler?.({
type: actionType,
params,
humanFriendlyMessage: userMessage,
formState: formPayload,
formName,
});
return;
}
// ActionPlan path (v0.5) — sequential steps with halt-on-mutation-failure
// Form state is read per step so an earlier @Set in the same plan is visible.
const actionPlan = action as ActionPlan | undefined;
if (actionPlan?.steps) {
for (const step of actionPlan.steps) {
switch (step.type) {
case ACTION_STEPS.Run: {
if (step.refType === "mutation") {
const mn = resultRef.current?.mutationStatements?.find(
(m) => m.statementId === step.statementId,
);
const evaluatedArgs = mn?.argsAST
? (evaluate(mn.argsAST, evaluationContext) as Record<string, unknown>)
: {};
const ok = await queryManager.fireMutation(step.statementId, evaluatedArgs);
if (!ok) return; // halt on failure
} else {
queryManager.invalidate([step.statementId]);
}
break;
}
case ACTION_STEPS.ToAssistant:
handler?.({
type: BuiltinActionType.ContinueConversation,
params: step.context !== undefined ? { context: step.context } : {},
humanFriendlyMessage: step.message,
formState: getFormPayload(formName),
formName,
});
break;
case ACTION_STEPS.OpenUrl:
handler?.({
type: BuiltinActionType.OpenUrl,
params: { url: step.url },
humanFriendlyMessage: "",
formState: getFormPayload(formName),
formName,
});
break;
case "custom_action":
handler?.({
type: step.name,
params: step.params,
humanFriendlyMessage: "",
formState: getFormPayload(formName),
formName,
});
break;
case ACTION_STEPS.Set: {
if (!step.valueAST) {
console.warn(`[openui] Set action for ${step.target} has no valueAST — skipping`);
break;
}
const value = evaluate(step.valueAST, evaluationContext);
store.set(step.target, value);
break;
}
case ACTION_STEPS.Reset: {
const decls = resultRef.current?.stateDeclarations ?? {};
for (const target of step.targets) {
store.set(target, decls[target] ?? null, { pristine: true });
}
break;
}
}
}
return;
}
// Default — ContinueConversation with label
handler?.({
type: BuiltinActionType.ContinueConversation,
params: {},
humanFriendlyMessage: userMessage,
formState: getFormPayload(formName),
formName,
});
},
[bundleBlocked, queryManager, evaluationContext, getFormPayload, store, schema.actions],
);
// ─── reportError (for error boundary) ───
const renderErrorsRef = useRef<OpenUIError[]>([]);
const isStreamingRef = useRef(isStreaming);
isStreamingRef.current = isStreaming;
const reportError = useCallback((error: OpenUIError) => {
// Skip during streaming — render errors are transient and onError won't fire until streaming stops
if (isStreamingRef.current) return;
renderErrorsRef.current.push(error);
}, []);
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[]>([]);
const evaluatedResult = useMemo<ParseResult | null>(() => {
if (!result?.root && !result?.rootExpression) return result;
// Fresh errors array each pass — avoids mutating memoized context
const errors: OpenUIError[] = [];
const evalCtx: EvalContext = { ctx: evaluationContext, library, store, errors };
try {
const evaluatedRoot = evaluateRoot(result, evalCtx);
runtimeErrorsRef.current = errors;
return { ...result, root: evaluatedRoot };
} catch (e) {
// Safety net — per-prop catch in evaluateElementProps handles most cases
const msg = e instanceof Error ? e.message : String(e);
errors.push({
source: "runtime",
code: "runtime-error",
message: `Prop evaluation failed: ${msg}`,
});
runtimeErrorsRef.current = errors;
return result;
}
}, [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({
response: bundle.program,
isStreaming,
result,
evaluatedResult,
library,
querySnapshot,
parseExceptionRef,
runtimeErrorsRef,
renderErrorsRef,
onError,
});
useStreamingObservability({
response: bundle.program,
isStreaming,
result,
errorsRef,
errorRevision,
publish: publishObservability,
__libraryId: library.__libraryId,
});
return {
result: evaluatedResult,
parseResult: result,
contextValue,
isQueryLoading,
queryErrors,
retryQueries,
};
}