The Open Standard for Generative UI
Feat/vue tool provider 498 (#629)
Sayandip Roye860cde85477
diff --git a/packages/vue-lang/README.md b/packages/vue-lang/README.mdindex ef59ca42e..07b575efd 100644--- a/packages/vue-lang/README.md+++ b/packages/vue-lang/README.md@@ -119,6 +119,9 @@ import { Renderer } from "@openuidev/vue-lang";| `onStateUpdate` | `(state: Record<string, any>) => void` | Callback when form field values change || `initialState` | `Record<string, any>` | Initial form state for hydration || `onParseResult` | `(result: ParseResult \| null) => void` | Callback when the parse result changes |+| `toolProvider` | `Record<string, Function> \| McpClientLike \| null` | Tool provider for executing `Query()` and `Mutation()` tool calls |+| `queryLoader` | `Component \| VNode \| null` | Custom loading spinner / loader component shown during query loading |+| `onError` | `(errors: OpenUIError[]) => void` | Callback triggered with structured, LLM-friendly errors |#### Errors@@ -150,15 +153,16 @@ if (result.meta.unresolved.length > 0) {Use these inside component renderers to interact with the rendering context:-| Composable | Description |-| :--------------------- | :----------------------------------- |-| `useIsStreaming()` | Whether the model is still streaming |-| `useRenderNode()` | Render child element nodes |-| `useTriggerAction()` | Trigger an action event |-| `useGetFieldValue()` | Get a form field's current value |-| `useSetFieldValue()` | Set a form field's value |-| `useSetDefaultValue()` | Set a field's default value |-| `useFormName()` | Get the current form's name |+| Composable | Description |+| :--------------------- | :------------------------------------------- |+| `useIsStreaming()` | Whether the model is still streaming |+| `useIsQueryLoading()` | Whether any Query is currently fetching data |+| `useRenderNode()` | Render child element nodes |+| `useTriggerAction()` | Trigger an action event |+| `useGetFieldValue()` | Get a form field's current value |+| `useSetFieldValue()` | Set a form field's value |+| `useSetDefaultValue()` | Set a field's default value |+| `useFormName()` | Get the current form's name |### Form Validation@@ -190,6 +194,45 @@ import type {} from "@openuidev/vue-lang";```+## Tool Provider Support (Queries & Mutations)++OpenUI Lang connects to your backend through tools. You can register a `toolProvider` to handle data fetching (`Query()`) and updates (`Mutation()`) natively in Vue:++```vue+<template>+ <Renderer+ :response="response"+ :library="library"+ :tool-provider="toolProvider"+ :query-loader="SpinnerComponent"+ :on-error="handleErrors"+ />+</template>++<script setup lang="ts">+import { Renderer } from "@openuidev/vue-lang";+import SpinnerComponent from "./Spinner.vue";++const toolProvider = {+ async get_server_health(args: Record<string, unknown>) {+ const res = await fetch(`/api/health`);+ return res.json();+ },+ async create_ticket(args: Record<string, unknown>) {+ const res = await fetch(`/api/tickets`, {+ method: "POST",+ body: JSON.stringify(args)+ });+ return res.json();+ }+};++function handleErrors(errors: any[]) {+ console.error("OpenUI Errors:", errors);+}+</script>+```+## JSON Schema OutputLibraries can also produce a JSON Schema representation of their components:diff --git a/packages/vue-lang/src/Renderer.vue b/packages/vue-lang/src/Renderer.vueindex a2393dfdb..0f71d120c 100644--- a/packages/vue-lang/src/Renderer.vue+++ b/packages/vue-lang/src/Renderer.vue@@ -1,11 +1,18 @@<script setup lang="ts">-import type { ActionEvent, ElementNode, ParseResult } from "@openuidev/lang-core";-import { BuiltinActionType, createParser } from "@openuidev/lang-core";-import { computed, h, ref, toRef, watch } from "vue";-import type { ActionConfig } from "./context.js";+import type {+ ActionEvent,+ ElementNode,+ ParseResult,+ OpenUIError,+ McpClientLike,+ ToolProvider,+} from "@openuidev/lang-core";+import { BuiltinActionType, extractToolResult, ToolNotFoundError } from "@openuidev/lang-core";+import { computed, h, toRef, watch, type Component, type VNode } from "vue";import { provideOpenUIContext } from "./context.js";import type { Library, RenderNodeResult } from "./library.js";import RenderNode from "./RenderNode.vue";+import { useOpenUIState } from "./state.js";interface RendererProps {/** Raw response text (openui-lang code). */@@ -28,101 +35,47 @@ interface RendererProps {initialState?: Record<string, any>;/** Called whenever the parse result changes. */onParseResult?: (result: ParseResult | null) => void;+ /** Tool provider for Query()/Mutation() calls. */+ toolProvider?:+ | Record<string, (args: Record<string, unknown>) => Promise<unknown>>+ | McpClientLike+ | null;+ /** Custom loading indicator shown while queries are fetching. */+ queryLoader?: Component | VNode | null;+ /** Called with structured errors. */+ onError?: (errors: OpenUIError[]) => void;}const props = withDefaults(defineProps<RendererProps>(), {isStreaming: false,});-// ─── Parser (created once from the library's JSON schema) ───-// Intentional: parser is created once, not reactive on library changes (matches react-lang).-const parser = createParser(props.library.toJSONSchema());--// ─── Parse result (derived from response) ───-const result = computed<ParseResult | null>(() => {- if (!props.response) return null;- try {- return parser.parse(props.response);- } catch (e) {- console.error("[openui] Parse error:", e);- return null;- }-});--// ─── Form state ───-const formState = ref<Record<string, any>>(props.initialState ?? {});--// Sync if initialState changes (e.g. loading a different message)-watch(- () => props.initialState,- (newVal, oldVal) => {- if (newVal !== oldVal) {- formState.value = newVal ?? {};+// Stable ToolProvider wrapper — identity never changes. callTool() reads the+// latest input from props.toolProvider on every call, so function map updates+// are always observed without triggering re-creation.+const stableToolProvider: ToolProvider = {+ async callTool(toolName: string, args: Record<string, unknown>): Promise<unknown> {+ const current = props.toolProvider;+ if (current == null) throw new Error("[openui] toolProvider is null");+ if (typeof (current as any).callTool === "function") {+ const result = await (current as any).callTool({+ name: toolName,+ arguments: args,+ });+ return extractToolResult(result);}+ const map = current as Record<string, (a: Record<string, unknown>) => Promise<unknown>>;+ const fn = map[toolName];+ if (!fn) throw new ToolNotFoundError(toolName, Object.keys(map));+ return fn(args);},-);--// ─── Notify on parse result change ───-watch(- result,- (r) => {- props.onParseResult?.(r);- },- { immediate: true },-);--// ─── Form state functions ───--function getFieldValue(formName: string | undefined, name: string): any {- return formName ? formState.value[formName]?.[name]?.value : formState.value[name]?.value;-}--function setFieldValue(- formName: string | undefined,- componentType: string | undefined,- name: string,- value: any,- shouldTriggerSaveCallback: boolean = true,-): void {- if (formName) {- formState.value[formName] = {- ...formState.value[formName],- [name]: { value, componentType },- };- } else {- formState.value[name] = { value, componentType };- }-- if (shouldTriggerSaveCallback && props.onStateUpdate) {- props.onStateUpdate({ ...formState.value });- }-}--function triggerAction(userMessage: string, formName?: string, action?: ActionConfig): void {- const actionType = action?.type || BuiltinActionType.ContinueConversation;- const actionParams = action?.params;+};- // Collect relevant form state- let relevantState: Record<string, any> | undefined;- if (formName && formState.value[formName]) {- relevantState = { [formName]: formState.value[formName] };- } else if (Object.keys(formState.value).length > 0) {- relevantState = formState.value;- }-- if (!props.onAction) return;-- props.onAction({- type: actionType,- params: actionParams || {},- humanFriendlyMessage: userMessage,- formState: relevantState,- formName,- });-}+const resolvedToolProvider = computed<ToolProvider | null>(() => {+ return props.toolProvider != null ? stableToolProvider : null;+});// ─── Render node function ───-function renderNode(value: unknown): RenderNodeResult {if (value == null) return null;if (typeof value === "string") return value;@@ -139,17 +92,62 @@ function renderNode(value: unknown): RenderNodeResult {return null;}-// ─── Provide context ───-provideOpenUIContext({- library: props.library,+const { result, parseResult, contextValue, isQueryLoading } = useOpenUIState(+ {+ response: toRef(props, "response"),+ library: props.library,+ isStreaming: toRef(props, "isStreaming"),+ onAction: (e) => props.onAction?.(e),+ onStateUpdate: (s) => props.onStateUpdate?.(s),+ initialState: props.initialState,+ toolProvider: resolvedToolProvider,+ onError: (errs) => props.onError?.(errs),+ },renderNode,- triggerAction,- isStreaming: toRef(props, "isStreaming"),- getFieldValue,- setFieldValue,-});+);++// ─── Notify on parse result change ───+watch(+ parseResult,+ (r) => {+ props.onParseResult?.(r);+ },+ { immediate: true },+);++// ─── Provide context ───+provideOpenUIContext(contextValue.value);</script><template>- <RenderNode v-if="result?.root" :node="result.root" />+ <div style="position: relative">+ <div v-if="isQueryLoading" style="position: absolute; top: 8px; right: 8px; z-index: 10">+ <component v-if="props.queryLoader" :is="props.queryLoader" />+ <div+ v-else+ style="+ width: 16px;+ height: 16px;+ border: 2px solid #e5e7eb;+ border-top-color: #3b82f6;+ border-radius: 50%;+ animation: openui-spin 0.6s linear infinite;+ "+ />+ </div>+ <div :style="{ opacity: isQueryLoading ? 0.7 : 1, transition: 'opacity 0.2s ease' }">+ <RenderNode v-if="result?.root" :node="result.root" />+ </div>+ </div></template>++<style>+@keyframes openui-spin {+ 0% {+ transform: rotate(0deg);+ }+ 100% {+ transform: rotate(360deg);+ }+}+</style>diff --git a/packages/vue-lang/src/__tests__/Renderer.query.test.ts b/packages/vue-lang/src/__tests__/Renderer.query.test.tsnew file mode 100644index 000000000..6a6f46efe--- /dev/null+++ b/packages/vue-lang/src/__tests__/Renderer.query.test.ts@@ -0,0 +1,345 @@+import { mount } from "@vue/test-utils";+import { describe, expect, it, vi } from "vitest";+import { defineComponent as defineVueComponent, h, nextTick } from "vue";+import { z } from "zod/v4";+import Renderer from "../Renderer.vue";+import { useOpenUI } from "../context.js";+import { createLibrary, defineComponent } from "../library.js";++async function flushMicrotasks() {+ for (let i = 0; i < 5; i++) {+ await Promise.resolve();+ }+}++describe("Renderer Query and Mutation Support", () => {+ const TicketList = defineVueComponent({+ name: "TicketList",+ props: ["props"],+ setup() {+ const ctx = useOpenUI();+ return { ctx };+ },+ template: `+ <div>+ <div id="loading">{{ ctx.isQueryLoading.value ? 'loading' : 'idle' }}</div>+ <div v-for="ticket in props.tickets" :key="ticket.id" class="ticket">+ {{ ticket.title }}+ </div>+ </div>+ `,+ });++ const TicketListComponent = defineComponent({+ name: "TicketList",+ props: z.object({+ tickets: z.array(z.object({ id: z.string(), title: z.string() })),+ }),+ description: "Displays a list of tickets",+ component: TicketList as any,+ });++ const TicketCreator = defineVueComponent({+ name: "TicketCreator",+ props: ["props"],+ setup(props) {+ const ctx = useOpenUI();+ const create = () => {+ ctx.triggerAction("Create Ticket", undefined, props.props.onSave);+ };+ return { create };+ },+ template: `+ <div>+ <div id="mut-status">{{ props.status }}</div>+ <button id="create-btn" @click="create">Create</button>+ </div>+ `,+ });++ const TicketCreatorComponent = defineComponent({+ name: "TicketCreator",+ props: z.object({+ status: z.string().optional(),+ onSave: z.any().optional(),+ }),+ description: "Creates tickets",+ component: TicketCreator as any,+ });++ const library = createLibrary({+ components: [TicketListComponent, TicketCreatorComponent],+ root: "TicketList",+ });++ it("performs query and resolves data asynchronously", async () => {+ const toolProvider = {+ list_tickets: vi.fn().mockResolvedValue([+ { id: "1", title: "Ticket One" },+ { id: "2", title: "Ticket Two" },+ ]),+ };++ const response = `+ tickets = Query("list_tickets", {}, [])+ root = TicketList(tickets)+ `;++ const wrapper = mount(Renderer, {+ props: {+ response,+ library,+ toolProvider,+ },+ });++ // Before query resolves, it should render the default value (empty list)+ expect(wrapper.find("#loading").text()).toBe("loading");+ expect(wrapper.findAll(".ticket").length).toBe(0);++ // Let the async tool call resolve and Vue update DOM+ await flushMicrotasks();+ await nextTick();++ // Now it should show the loaded items and idle status+ expect(wrapper.find("#loading").text()).toBe("idle");+ const tickets = wrapper.findAll(".ticket");+ expect(tickets.length).toBe(2);+ expect(tickets[0]?.text()).toBe("Ticket One");+ expect(tickets[1]?.text()).toBe("Ticket Two");+ expect(toolProvider.list_tickets).toHaveBeenCalled();+ });++ it("handles query failures and propagates errors via onError", async () => {+ const onError = vi.fn();+ const toolProvider = {+ list_tickets: vi.fn().mockRejectedValue(new Error("Database offline")),+ };++ const response = `+ tickets = Query("list_tickets", {}, [])+ root = TicketList(tickets)+ `;++ mount(Renderer, {+ props: {+ response,+ library,+ toolProvider,+ onError,+ },+ });++ await flushMicrotasks();+ await nextTick();++ expect(onError).toHaveBeenCalled();+ const calls = onError.mock.calls;+ const errors = (calls[calls.length - 1] as any)?.[0] || [];+ expect(errors.length).toBeGreaterThan(0);+ expect(errors[0].code).toBe("tool-error");+ expect(errors[0].message).toContain("Database offline");+ });++ it("supports custom queryLoader component", async () => {+ const CustomLoader = defineVueComponent({+ name: "CustomLoader",+ template: `<div id="custom-loader">Loading tickets...</div>`,+ });++ const toolProvider = {+ list_tickets: vi.fn().mockReturnValue(new Promise(() => {})), // never resolves+ };++ const response = `+ tickets = Query("list_tickets", {}, [])+ root = TicketList(tickets)+ `;++ const wrapper = mount(Renderer, {+ props: {+ response,+ library,+ toolProvider,+ queryLoader: CustomLoader,+ },+ });++ expect(wrapper.find("#custom-loader").exists()).toBe(true);+ expect(wrapper.find("#custom-loader").text()).toBe("Loading tickets...");+ });++ it("supports mutations, tracks status, and invalidates queries on run", async () => {+ const mockListTickets = vi+ .fn()+ .mockResolvedValueOnce([{ id: "1", title: "Original Ticket" }])+ .mockResolvedValueOnce([+ { id: "1", title: "Original Ticket" },+ { id: "2", title: "Created Ticket" },+ ]);++ let resolveMutation: (value: any) => void;+ const mutationPromise = new Promise((resolve) => {+ resolveMutation = resolve;+ });+ const mockCreateTicket = vi.fn().mockReturnValue(mutationPromise);++ const toolProvider = {+ list_tickets: mockListTickets,+ create_ticket: mockCreateTicket,+ };++ // Define a wrapper component that renders both TicketCreator and TicketList+ const Container = defineVueComponent({+ name: "Container",+ props: ["props", "renderNode"],+ setup(props) {+ return () => h("div", {}, props.renderNode(props.props.children));+ },+ });++ const ContainerComponent = defineComponent({+ name: "Container",+ props: z.object({+ children: z.any(),+ }),+ description: "Simple container",+ component: Container as any,+ });++ const extendedLibrary = createLibrary({+ components: [TicketListComponent, TicketCreatorComponent, ContainerComponent],+ root: "Container",+ });++ const response = `+ tickets = Query("list_tickets", {}, [])+ createResult = Mutation("create_ticket", { title: "Created Ticket" })+ root = Container(+ [+ TicketCreator(createResult.status, Action([@Run(createResult), @Run(tickets)])),+ TicketList(tickets)+ ]+ )+ `;++ const wrapper = mount(Renderer, {+ props: {+ response,+ library: extendedLibrary,+ toolProvider,+ },+ });++ // Wait for the initial query to load+ await flushMicrotasks();+ await nextTick();++ expect(wrapper.findAll(".ticket").length).toBe(1);+ expect(wrapper.find(".ticket").text()).toBe("Original Ticket");+ expect(wrapper.find("#mut-status").text()).toBe("idle");++ // Click "Create" button to fire mutation+ await wrapper.find("#create-btn").trigger("click");++ // Let the mutation action start and update reactive state+ await flushMicrotasks();+ await nextTick();++ // While mutation is running (before we resolve the promise), status should be loading+ expect(wrapper.find("#mut-status").text()).toBe("loading");++ // Resolve the mutation tool call+ resolveMutation!({ id: "2", title: "Created Ticket" });++ // Let the mutation finish and the invalidated query resolve+ await flushMicrotasks();+ await nextTick();++ // Now status should be success and ticket list should be updated+ expect(wrapper.find("#mut-status").text()).toBe("success");+ const tickets = wrapper.findAll(".ticket");+ expect(tickets.length).toBe(2);+ expect(tickets[0]?.text()).toBe("Original Ticket");+ expect(tickets[1]?.text()).toBe("Created Ticket");++ expect(mockCreateTicket).toHaveBeenCalledWith({ title: "Created Ticket" });+ });++ it("handles mutation failures and exposes error status", async () => {+ const onError = vi.fn();+ const mockCreateTicket = vi.fn().mockRejectedValue(new Error("Unauthorized"));++ const toolProvider = {+ list_tickets: vi.fn().mockResolvedValue([]),+ create_ticket: mockCreateTicket,+ };++ const response = `+ tickets = Query("list_tickets", {}, [])+ createResult = Mutation("create_ticket", { title: "Fail Ticket" })+ root = TicketCreator(createResult.status, Action([@Run(createResult)]))+ `;++ const wrapper = mount(Renderer, {+ props: {+ response,+ library,+ toolProvider,+ onError,+ },+ });++ await flushMicrotasks();+ await nextTick();++ await wrapper.find("#create-btn").trigger("click");+ await flushMicrotasks();+ await nextTick();++ // Check mutation status is set to error+ expect(wrapper.find("#mut-status").text()).toBe("error");+ expect(onError).toHaveBeenCalled();+ const calls = onError.mock.calls;+ const errors = (calls[calls.length - 1] as any)?.[0] || [];+ expect(+ errors.some((e: any) => e.code === "tool-error" && e.message.includes("Unauthorized")),+ ).toBe(true);+ });++ it("handles transition of toolProvider from null to active provider", async () => {+ const toolProvider = {+ list_tickets: vi.fn().mockResolvedValue([{ id: "1", title: "Async Ticket" }]),+ };++ const response = `+ tickets = Query("list_tickets", {}, [])+ root = TicketList(tickets)+ `;++ const wrapper = mount(Renderer, {+ props: {+ response,+ library,+ toolProvider: null,+ },+ });++ // Since toolProvider is null initially, it cannot execute, so it should be idle+ expect(wrapper.find("#loading").text()).toBe("idle");+ expect(wrapper.findAll(".ticket").length).toBe(0);++ // Now set toolProvider to active provider+ await wrapper.setProps({ toolProvider });++ // Let query run and resolve+ await flushMicrotasks();+ await nextTick();++ expect(wrapper.find("#loading").text()).toBe("idle");+ const tickets = wrapper.findAll(".ticket");+ expect(tickets.length).toBe(1);+ expect(tickets[0]?.text()).toBe("Async Ticket");+ expect(toolProvider.list_tickets).toHaveBeenCalled();+ });+});diff --git a/packages/vue-lang/src/context.ts b/packages/vue-lang/src/context.tsindex 3fb3f3a19..4fe48faff 100644--- a/packages/vue-lang/src/context.ts+++ b/packages/vue-lang/src/context.ts@@ -1,3 +1,4 @@+import type { EvaluationContext, Store } from "@openuidev/lang-core";import type { InjectionKey, Ref } from "vue";import { inject, provide, watchEffect } from "vue";import type { Library, RenderNodeResult } from "./library.js";@@ -35,6 +36,15 @@ export interface OpenUIContextValue {/** Whether the LLM is currently streaming content. */isStreaming: Ref<boolean>;+ /** Whether any Query is currently fetching data. */+ isQueryLoading: Ref<boolean>;++ /** Reactive binding store for $variables and form data. */+ store: Store;++ /** AST evaluation context used by runtime expression evaluation. */+ evaluationContext: EvaluationContext;+/** Get a form field value. Returns undefined if not set. */getFieldValue: (formName: string | undefined, name: string) => any;@@ -106,6 +116,13 @@ export function useIsStreaming(): Ref<boolean> {return useOpenUI().isStreaming;}+/**+ * Whether any Query is currently fetching data.+ */+export function useIsQueryLoading(): Ref<boolean> {+ return useOpenUI().isQueryLoading;+}+/*** Get a form field value from the form state context.*/diff --git a/packages/vue-lang/src/index.ts b/packages/vue-lang/src/index.tsindex fc8111401..a0037bbab 100644--- a/packages/vue-lang/src/index.ts+++ b/packages/vue-lang/src/index.ts@@ -16,7 +16,7 @@ export type {// ─── Renderer ───-import type { ActionEvent, ParseResult } from "@openuidev/lang-core";+import type { ActionEvent, McpClientLike, OpenUIError, ParseResult } from "@openuidev/lang-core";import type { Library } from "./library.js";export { default as Renderer } from "./Renderer.vue";@@ -30,6 +30,12 @@ export interface RendererProps {onStateUpdate?: (state: Record<string, any>) => void;initialState?: Record<string, any>;onParseResult?: (result: ParseResult | null) => void;+ toolProvider?:+ | Record<string, (args: Record<string, unknown>) => Promise<unknown>>+ | McpClientLike+ | null;+ queryLoader?: any;+ onError?: (errors: OpenUIError[]) => void;}// ─── Context (composables for use inside component renderers) ───@@ -39,6 +45,7 @@ export {provideOpenUIContext,useFormName,useGetFieldValue,+ useIsQueryLoading,useIsStreaming,useOpenUI,useRenderNode,@@ -58,7 +65,15 @@ export type { ParsedRule, ValidatorFn } from "./validation.js";// ─── Re-exports from lang-core (parser, types) ───-export { BuiltinActionType } from "@openuidev/lang-core";-export type { ActionEvent, ElementNode, ParseResult } from "@openuidev/lang-core";+export { BuiltinActionType, extractToolResult, ToolNotFoundError } from "@openuidev/lang-core";+export type {+ ActionEvent,+ ElementNode,+ EvaluationContext,+ McpClientLike,+ OpenUIError,+ ParseResult,+ ToolProvider,+} from "@openuidev/lang-core";export { createParser, createStreamingParser, type LibraryJSONSchema } from "@openuidev/lang-core";diff --git a/packages/vue-lang/src/state.ts b/packages/vue-lang/src/state.tsnew file mode 100644index 000000000..e41a9d8c6--- /dev/null+++ b/packages/vue-lang/src/state.ts@@ -0,0 +1,497 @@+import {+ ACTION_STEPS,+ BuiltinActionType,+ createQueryManager,+ createStore,+ createStreamingParser,+ enrichErrors,+ evaluate,+ evaluateElementProps,+ type ActionEvent,+ type ActionPlan,+ type EvalContext,+ type EvaluationContext,+ type OpenUIError,+ type ParseResult,+ type QueryManager,+ type QuerySnapshot,+ type ToolProvider,+} from "@openuidev/lang-core";+import {+ computed,+ isRef,+ onUnmounted,+ ref,+ shallowRef,+ watchEffect,+ type ComputedRef,+ type Ref,+} from "vue";+import type { OpenUIContextValue } from "./context.js";++/** 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 {+ response: Ref<string | null> | string | null;+ library: any;+ isStreaming: Ref<boolean> | boolean;+ onAction?: (event: ActionEvent) => void;+ onStateUpdate?: (state: Record<string, any>) => void;+ initialState?: Record<string, any>;+ toolProvider?: Ref<ToolProvider | null> | ToolProvider | null;+ onError?: (errors: OpenUIError[]) => void;+}++export interface OpenUIState {+ result: ComputedRef<ParseResult | null>;+ parseResult: ComputedRef<ParseResult | null>;+ contextValue: ComputedRef<OpenUIContextValue>;+ isQueryLoading: ComputedRef<boolean>;+}++export function useOpenUIState(+ options: UseOpenUIStateOptions,+ renderDeep: (value: unknown) => any,+): OpenUIState {+ const responseRef = computed(() => {+ return typeof options.response === "object" &&+ options.response !== null &&+ "value" in options.response+ ? options.response.value+ : options.response;+ });++ const isStreamingRef = computed(() => {+ return typeof options.isStreaming === "object" &&+ options.isStreaming !== null &&+ "value" in options.isStreaming+ ? options.isStreaming.value+ : options.isStreaming;+ });++ const toolProviderRef = computed(() => {+ return isRef(options.toolProvider) ? options.toolProvider.value : options.toolProvider;+ });++ // ─── Streaming parser ───+ const sp = createStreamingParser(options.library.toJSONSchema(), options.library.root);++ // ─── Parse result ───+ const parseException = ref<OpenUIError | null>(null);+ const parseResult = computed<ParseResult | null>(() => {+ parseException.value = null;+ const resp = responseRef.value;+ if (!resp) return null;+ try {+ return sp.set(resp);+ } catch (e) {+ const msg = e instanceof Error ? e.message : String(e);+ parseException.value = {+ source: "parser",+ code: "parse-exception",+ message: `Parser crashed: ${msg}`,+ hint: "The response may contain syntax the parser cannot handle",+ };+ return null;+ }+ });++ // ─── Store ───+ const store = createStore();++ // ─── QueryManager ───+ const queryManager = shallowRef<QueryManager | null>(null);+ const querySnapshot = shallowRef<QuerySnapshot>({+ __openui_loading: [],+ __openui_refetching: [],+ __openui_errors: [],+ });++ watchEffect((onCleanup) => {+ const provider = toolProviderRef.value;+ const qm = createQueryManager(provider ?? null);+ qm.activate();+ queryManager.value = qm;++ querySnapshot.value = qm.getSnapshot();+ const unsub = qm.subscribe(() => {+ querySnapshot.value = qm.getSnapshot();+ });++ onCleanup(() => {+ unsub();+ qm.dispose();+ });+ });++ onUnmounted(() => {+ store.dispose();+ });++ // ─── Initialize Store ───+ let lastStoreInitKey = "";+ watchEffect(() => {+ const res = parseResult.value;+ const initial = options.initialState;+ if (!res?.stateDeclarations && !initial) return;+ const key = `${JSON.stringify(res?.stateDeclarations)}::${JSON.stringify(initial)}`;+ if (lastStoreInitKey === key) return;+ lastStoreInitKey = key;++ const bindingDefaults: Record<string, unknown> = {};+ if (initial) {+ for (const [k, v] of Object.entries(initial)) {+ if (k.startsWith("$")) {+ bindingDefaults[k] = v;+ } else {+ store.set(k, v);+ }+ }+ }+ store.initialize(res?.stateDeclarations ?? {}, bindingDefaults);+ });++ // ─── Snapshots ───+ const storeSnapshot = shallowRef(store.getSnapshot());++ const unsubStore = store.subscribe(() => {+ storeSnapshot.value = store.getSnapshot();+ });++ onUnmounted(() => {+ unsubStore();+ });++ // ─── Build EvaluationContext ───+ const evaluationContext = computed<EvaluationContext>(() => {+ // Touch snapshots to reactively track changes+ const _store = storeSnapshot.value;+ const qm = queryManager.value;++ return {+ getState: (name: string) => unwrapFieldValue(store.get(name)),+ resolveRef: (name: string) => {+ if (!qm) return null;+ const mutResult = qm.getMutationResult(name);+ if (mutResult) return mutResult;+ return qm.getResult(name);+ },+ };+ });++ // ─── Evaluate and submit queries ───+ watchEffect(() => {+ if (isStreamingRef.value) return;++ // Touch storeSnapshot to re-evaluate when dependencies change+ const _store = storeSnapshot.value;+ const qm = queryManager.value;+ if (!qm) return;++ const queryStmts = parseResult.value?.queryStatements ?? [];+ const evaluatedNodes = queryStmts.map((qn) => {+ const relevantDeps: Record<string, unknown> = {};+ if (qn.deps) {+ for (const refName of qn.deps) {+ relevantDeps[refName] = storeSnapshot.value[refName];+ }+ }+ return {+ statementId: qn.statementId,+ toolName: qn.toolAST ? (evaluate(qn.toolAST, evaluationContext.value) as string) : "",+ args: qn.argsAST ? evaluate(qn.argsAST, evaluationContext.value) : null,+ defaults: qn.defaultsAST ? evaluate(qn.defaultsAST, evaluationContext.value) : null,+ refreshInterval: qn.refreshAST+ ? (evaluate(qn.refreshAST, evaluationContext.value) as number)+ : undefined,+ deps: Object.keys(relevantDeps).length > 0 ? relevantDeps : undefined,+ complete: qn.complete,+ };+ });++ qm.evaluateQueries(evaluatedNodes);+ });++ // ─── Register mutations ───+ watchEffect(() => {+ if (isStreamingRef.value) return;+ const qm = queryManager.value;+ if (!qm) return;++ const mutStmts = parseResult.value?.mutationStatements ?? [];+ const nodes = mutStmts.map((mn) => ({+ statementId: mn.statementId,+ toolName: mn.toolAST ? (evaluate(mn.toolAST, evaluationContext.value) as string) : "",+ }));+ qm.registerMutations(nodes);+ });++ // ─── Fire onStateUpdate when Store changes ───+ let lastStateUpdateSnapshot = store.getSnapshot();+ const unsubStateUpdate = store.subscribe(() => {+ const currentSnapshot = store.getSnapshot();+ if (currentSnapshot === lastStateUpdateSnapshot) return;+ lastStateUpdateSnapshot = currentSnapshot;+ options.onStateUpdate?.(currentSnapshot);+ });+ onUnmounted(() => {+ unsubStateUpdate();+ });++ // ─── getFieldValue ───+ function getFieldValue(formName: string | undefined, name: string): any {+ 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]);+ }++ // ─── setFieldValue ───+ function setFieldValue(+ formName: string | undefined,+ componentType: string | undefined,+ name: string,+ value: unknown,+ shouldTriggerSaveCallback: boolean = true,+ ): void {+ 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) {+ options.onStateUpdate?.(store.getSnapshot());+ }+ }++ // ─── Materialize form payload ───+ function getFormPayload(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();+ }++ // ─── triggerAction ───+ async function triggerAction(+ userMessage: string,+ formName?: string,+ action?: ActionPlan | { type?: string; params?: Record<string, any> },+ ): Promise<void> {+ const formPayload = getFormPayload(formName);+ const qm = queryManager.value;++ // Legacy action config path (v0.1 compat) — { type?, params? }+ if (action && !("steps" in action)) {+ const actionType = action.type || BuiltinActionType.ContinueConversation;+ const params = { ...(action.params || {}) };+ if ((action as any).url) params["url"] = (action as any).url;+ if ((action as any).context) params["context"] = (action as any).context;+ options.onAction?.({+ type: actionType,+ params,+ humanFriendlyMessage: userMessage,+ formState: formPayload,+ formName,+ });+ return;+ }++ // ActionPlan path (v0.5)+ 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 = parseResult.value?.mutationStatements?.find(+ (m) => m.statementId === step.statementId,+ );+ const evaluatedArgs = mn?.argsAST+ ? (evaluate(mn.argsAST, evaluationContext.value) as Record<string, unknown>)+ : {};+ if (!qm) return;+ const ok = await qm.fireMutation(step.statementId, evaluatedArgs);+ if (!ok) return; // halt on failure+ } else {+ if (qm) qm.invalidate([step.statementId]);+ }+ break;+ }+ case ACTION_STEPS.ToAssistant:+ options.onAction?.({+ type: BuiltinActionType.ContinueConversation,+ params: step.context ? { context: step.context } : {},+ humanFriendlyMessage: step.message,+ formState: formPayload,+ formName,+ });+ break;+ case ACTION_STEPS.OpenUrl:+ options.onAction?.({+ type: BuiltinActionType.OpenUrl,+ params: { url: step.url },+ humanFriendlyMessage: "",+ formState: formPayload,+ formName,+ });+ break;+ case ACTION_STEPS.Set: {+ if (!step.valueAST) break;+ const value = evaluate(step.valueAST, evaluationContext.value);+ store.set(step.target, value);+ break;+ }+ case ACTION_STEPS.Reset: {+ const decls = parseResult.value?.stateDeclarations ?? {};+ for (const target of step.targets) {+ store.set(target, decls[target] ?? null);+ }+ break;+ }+ }+ }+ return;+ }++ // Default+ options.onAction?.({+ type: BuiltinActionType.ContinueConversation,+ params: {},+ humanFriendlyMessage: userMessage,+ formState: formPayload,+ formName,+ });+ }++ const isQueryLoading = computed(() => querySnapshot.value.__openui_loading.length > 0);++ // ─── Context value ───+ const contextValue = computed<OpenUIContextValue>(() => ({+ library: options.library,+ renderNode: renderDeep,+ triggerAction,+ isStreaming: isStreamingRef as any,+ isQueryLoading: isQueryLoading as any,+ getFieldValue,+ setFieldValue,+ store,+ evaluationContext: evaluationContext.value,+ }));++ // ─── Evaluate props ───+ const runtimeErrors = ref<OpenUIError[]>([]);++ const evaluatedResult = computed<ParseResult | null>(() => {+ const res = parseResult.value;+ if (!res?.root) return res;+ // Touch querySnapshot to re-evaluate props when queries/mutations resolve/fail+ const _query = querySnapshot.value;+ const errors: OpenUIError[] = [];+ const evalCtx: EvalContext = {+ ctx: evaluationContext.value,+ library: options.library,+ store,+ errors,+ };+ try {+ const evaluatedRoot = evaluateElementProps(res.root, evalCtx);+ runtimeErrors.value = errors;+ return { ...res, root: evaluatedRoot };+ } catch (e) {+ const msg = e instanceof Error ? e.message : String(e);+ errors.push({+ source: "runtime",+ code: "runtime-error",+ message: `Prop evaluation failed: ${msg}`,+ });+ runtimeErrors.value = errors;+ return res;+ }+ });++ // ─── Collect and fire onError ───+ let lastErrorKey = "";+ watchEffect(() => {+ if (isStreamingRef.value) {+ if (lastErrorKey !== "") {+ lastErrorKey = "";+ options.onError?.([]);+ }+ return;+ }++ const errors: OpenUIError[] = [];++ // Parser exception+ if (parseException.value) {+ errors.push(parseException.value);+ }++ // Parse failure+ const resp = responseRef.value;+ const res = parseResult.value;+ if (resp && !res?.root && !parseException.value) {+ errors.push({+ source: "parser",+ code: "parse-failed",+ message: res+ ? "Code parsed but produced no renderable root component"+ : "Response could not be parsed as valid openui-lang",+ hint: `The entire response must be valid openui-lang code starting with root = ${options.library.root ?? "Root"}(...)`,+ });+ }++ // Parser validation errors+ if (res?.meta?.errors?.length) {+ errors.push(+ ...enrichErrors(+ res.meta.errors,+ options.library.toJSONSchema(),+ Object.keys(options.library.components),+ ),+ );+ }++ // Runtime eval errors+ errors.push(...runtimeErrors.value);++ // Query/mutation errors+ errors.push(...(querySnapshot.value.__openui_errors ?? []));++ // Deduplicate+ const key = JSON.stringify(errors);+ if (key === lastErrorKey) return;+ lastErrorKey = key;++ if (options.onError) {+ options.onError(errors);+ } else if (errors.length > 0) {+ for (const e of errors) {+ console.warn(`[openui] ${e.source}/${e.code}: ${e.message}`);+ }+ }+ });++ return { result: evaluatedResult, parseResult, contextValue, isQueryLoading };+}