@dudousxd/nestjs-agent-react 0.32.0 → 0.33.0

package/dist/{client-C7eu9WMJ.d.cts → client-B6EE8-AC.d.cts}

@@ -1,4 +1,4 @@
-import { ChatQueueState, ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
+import { ActionProposalMutationResult, ChatQueueState, ThreadSummary, ThreadDetail, ActionProposal, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
 
 /**
  * What a server said when it refused a request, read once so every error class of this package
@@ -67,6 +67,14 @@ interface ResumeStreamRequest {
  * headers). The body's own `event: meta` frame supplies them otherwise.
  */
 interface ChatStreamResponse {
+    proposalDecision?: {
+        threadId: string;
+        proposalDecision: ActionProposalMutationResult | {
+            status: 'ambiguous';
+            proposalIds: string[];
+        };
+        text?: string;
+    };
     body: ReadableStream<Uint8Array>;
     runId?: string;
     threadId?: string;
@@ -189,6 +197,19 @@ interface AgentBackend {
     forkFromMessage?(threadId: string, messageId: string): Promise<ThreadSummary>;
     promoteThread?(id: string): Promise<unknown>;
     truncateFromMessage?(threadId: string, messageId: string): Promise<unknown>;
+    listActionProposals?(input: {
+        threadId: string;
+    }): Promise<ActionProposal[]>;
+    approveActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationResult>;
+    rejectActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationResult>;
     approveToolCall?(input: {
         toolCallId: string;
         remember?: boolean;
@@ -392,6 +413,19 @@ declare class AgentClient implements AgentBackend {
      * `remember` approves later calls of the same tool in the same thread; `via` names the surface
      * the decision came through (the server records `'web'` when omitted).
      */
+    listActionProposals({ threadId }: {
+        threadId: string;
+    }): Promise<ActionProposal[]>;
+    approveActionProposal({ threadId, proposalId, remember, }: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationResult>;
+    rejectActionProposal({ threadId, proposalId, reason, }: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationResult>;
     approveToolCall(input: {
         toolCallId: string;
         remember?: boolean;
@@ -433,6 +467,7 @@ declare class AgentClient implements AgentBackend {
     private resolveHeaders;
     private credentials;
     private request;
+    private requestResponse;
     /** The error for a refused `response`, already reported to `onHttpError`. */
     private failure;
     private handleResponse;

package/dist/{client-C7eu9WMJ.d.ts → client-B6EE8-AC.d.ts}

@@ -1,4 +1,4 @@
-import { ChatQueueState, ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
+import { ActionProposalMutationResult, ChatQueueState, ThreadSummary, ThreadDetail, ActionProposal, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
 
 /**
  * What a server said when it refused a request, read once so every error class of this package
@@ -67,6 +67,14 @@ interface ResumeStreamRequest {
  * headers). The body's own `event: meta` frame supplies them otherwise.
  */
 interface ChatStreamResponse {
+    proposalDecision?: {
+        threadId: string;
+        proposalDecision: ActionProposalMutationResult | {
+            status: 'ambiguous';
+            proposalIds: string[];
+        };
+        text?: string;
+    };
     body: ReadableStream<Uint8Array>;
     runId?: string;
     threadId?: string;
@@ -189,6 +197,19 @@ interface AgentBackend {
     forkFromMessage?(threadId: string, messageId: string): Promise<ThreadSummary>;
     promoteThread?(id: string): Promise<unknown>;
     truncateFromMessage?(threadId: string, messageId: string): Promise<unknown>;
+    listActionProposals?(input: {
+        threadId: string;
+    }): Promise<ActionProposal[]>;
+    approveActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationResult>;
+    rejectActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationResult>;
     approveToolCall?(input: {
         toolCallId: string;
         remember?: boolean;
@@ -392,6 +413,19 @@ declare class AgentClient implements AgentBackend {
      * `remember` approves later calls of the same tool in the same thread; `via` names the surface
      * the decision came through (the server records `'web'` when omitted).
      */
+    listActionProposals({ threadId }: {
+        threadId: string;
+    }): Promise<ActionProposal[]>;
+    approveActionProposal({ threadId, proposalId, remember, }: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationResult>;
+    rejectActionProposal({ threadId, proposalId, reason, }: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationResult>;
     approveToolCall(input: {
         toolCallId: string;
         remember?: boolean;
@@ -433,6 +467,7 @@ declare class AgentClient implements AgentBackend {
     private resolveHeaders;
     private credentials;
     private request;
+    private requestResponse;
     /** The error for a refused `response`, already reported to `onHttpError`. */
     private failure;
     private handleResponse;

package/dist/{generative-ui-VTZ1EADD.d.cts → generative-ui-DOe2RsoO.d.cts}

@@ -1,7 +1,19 @@
 import * as React from 'react';
 import { ComponentType, ReactNode } from 'react';
-import { ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ElicitationInput } from '@dudousxd/nestjs-agent-core';
-import { ToolUIPart, DynamicToolUIPart, UIMessage } from 'ai';
+import { ActionProposal, StoredMessage, ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ToolConfirmation, ElicitationInput } from '@dudousxd/nestjs-agent-core';
+import { UIMessage, ToolUIPart, DynamicToolUIPart } from 'ai';
+
+type ApprovalTarget = {
+    kind: 'legacy';
+    toolCallId: string;
+} | {
+    kind: 'proposal';
+    proposalId: string;
+    threadId?: string;
+};
+declare function proposalNeedsPolling(proposal: ActionProposal): boolean;
+/** Patch proposal metadata and append outcome facts; never replace live text with stored rows. */
+declare function reconcileProposalMessages(current: UIMessage[], proposals: ActionProposal[], facts: StoredMessage[]): UIMessage[];
 
 /** What a form control can hand over: a field's value, a checkbox's state, a picked date, a list. */
 type RawAnswer = string | number | boolean | Date | null | undefined | readonly RawAnswer[];
@@ -96,7 +108,7 @@ declare function resolveResultView(output: unknown, view: ToolResultView | undef
  *  - `done` / `failed` / `denied` — settled. A tool that RETURNS `{ error }` has failed just as much
  *    as one that threw; the two arrive differently and read the same to a person.
  */
-type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied';
+type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied' | 'queued' | 'executing' | 'succeeded';
 interface ToolCallState {
     status: ToolCallStatus;
     isSettled: boolean;
@@ -136,6 +148,8 @@ interface ToolCallDescription {
     presentation: ToolPresentation | null;
 }
 interface DescribeToolCallOptions {
+    /** Resolved strings from the call preflight override the tool catalog templates. */
+    confirmation?: ToolConfirmation;
     /** Words for a tool the catalog does not describe. Default `Working` / `Done`. */
     fallback?: {
         running: string;
@@ -263,13 +277,16 @@ interface TranscriptSettleState {
     run: () => void;
 }
 /** How an approval stands. */
-type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'superseded';
 /**
  * Who has to settle a parked call, until when, and — once it settled — how. From the stream's
  * `approval-requested` / `approval-settled` frames, or the same parts a reloaded thread carries.
  * `null` on a call whose runner never said (the call can still be awaiting approval).
  */
 interface TranscriptApproval {
+    target?: ApprovalTarget;
+    executionStatus?: 'queued' | 'executing' | 'succeeded' | 'failed' | null;
+    confirmation?: ToolConfirmation;
     /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
     approver: string;
     /** ISO-8601; `null` when the request never lapses. Pair with `useApprovalCountdown`. */
@@ -371,6 +388,8 @@ interface TranscriptUiBlock {
     props: Record<string, unknown>;
     /** Schema version of `props`; `null` when the server did not stamp one. */
     version: number | null;
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     /** The tool call that pushed it (`ctx.emitUi`); `null` for a component pushed outside a tool. */
     toolCallId: string | null;
 }
@@ -516,8 +535,8 @@ interface ElicitationBlockOptions {
 interface ApprovalBlockOptions {
     canApprove: boolean;
     canReject: boolean;
-    approve: (toolCallId: string, options?: ApproveOptions) => void;
-    reject: (toolCallId: string) => void;
+    approve: (toolCallId: string, options?: ApproveOptions, target?: ApprovalTarget) => void;
+    reject: (toolCallId: string, target?: ApprovalTarget) => void;
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
     errorOf: (toolCallId: string) => string | null;
@@ -580,6 +599,8 @@ declare function formatRelativeTime(date: Date): string;
 declare const GENUI_TREE_COMPONENT = "genui:tree";
 /** One pushed component, normalized from whatever carried it (a transcript block, a `data-ui` part, a stored entry). */
 interface GenerativeUIItem {
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     id: string;
     component: string;
     props: Record<string, unknown>;
@@ -624,6 +645,9 @@ type ValidationLike = {
  * object does too.
  */
 interface GenuiCatalogLike {
+    get?(name: string): {
+        version?: number;
+    } | undefined;
     has(name: string): boolean;
     validate(name: string, props: unknown): Promise<ValidationLike>;
     validateSync?(name: string, props: unknown): ValidationLike | undefined;
@@ -678,6 +702,8 @@ declare function GenuiTree({ root }: {
     root?: GenerativeUIElement;
 }): React.JSX.Element | null;
 interface GenerativeUIScopeProps extends GenerativeUIOptions {
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     fallback?: GenerativeUIFallback;
     loading?: ReactNode;
     onError?: (error: unknown, item: GenerativeUIItem) => void;
@@ -687,7 +713,7 @@ interface GenerativeUIScopeProps extends GenerativeUIOptions {
  * The registry, catalog and fallbacks tree nodes render with. `<GenerativeUI>` provides it; wrap
  * your own chrome in it when you draw `useGenerativeUI`'s `Component` yourself and it may be a tree.
  */
-declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
+declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, fallbackText, componentVersions, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
 /** What `<GenuiProvider>` hands every `<GenerativeUI>` / `useGenerativeUI` below it. */
 interface GenuiProviderValue extends Partial<GenerativeUIOptions> {
     fallback?: GenerativeUIFallback;
@@ -720,7 +746,7 @@ declare function useGenerativeUI(part: unknown, options?: Partial<GenerativeUIOp
 interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
     /** A transcript `ui` block, a `data-ui` message part, or a stored `{ id, component, props, version? }`. */
     part: TranscriptUiBlock | GenerativeUIItem | unknown;
-    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, else nothing. */
+    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, then the item's persisted text. */
     fallback?: GenerativeUIFallback;
     /** Drawn while a resolver or an async validation is pending. Default: the provider's, else nothing. */
     loading?: ReactNode;
@@ -738,4 +764,4 @@ interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
  */
 declare function GenerativeUI({ part, registry, catalog, resolveComponent, treeRenderer, fallback: ownFallback, loading: ownLoading, onError: ownOnError, }: GenerativeUIProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 
-export { type TranscriptQuestionOption as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type CoercibleQuestion as D, type DescribeToolCallOptions as E, type ElicitationBlockOptions as F, type GenerativeUIItem as G, type GroupToolActivityOptions as H, type RawAnswer as I, type ResolvedReading as J, type ResolvedResultView as K, type RetrievedPassage as L, type MessageUsageInfo as M, type ToolActivityGroup as N, type ToolCallDescription as O, type ToolCallState as P, type ToolCallStatus as Q, type ResolveComponent as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type TranscriptApproval as V, type TranscriptApprovalStatus as W, type TranscriptElicitationBlock as X, type TranscriptElicitationOutcome as Y, type TranscriptFilesBlock as Z, type TranscriptQuestion as _, GENUI_TREE_COMPONENT as a, type TranscriptReasoningBlock as a0, type TranscriptSettleState as a1, type TranscriptSource as a2, type TranscriptSourcesBlock as a3, type TranscriptTextBlock as a4, type TranscriptToolBlock as a5, type TranscriptToolCall as a6, buildTranscriptBlocks as a7, coerceAnswer as a8, correctedCallIds as a9, describeTimestamp as aa, describeToolCall as ab, describeUsage as ac, extractMessageText as ad, fillTemplate as ae, formatRelativeTime as af, groupToolActivity as ag, inferResultView as ah, isActionCall as ai, phraseFor as aj, readPath as ak, resolveResultView as al, toolCallState as am, toolCatalogFrom as an, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, type TranscriptBlock as t, useGenerativeUI as u, type TimestampInfo as v, type TranscriptFile as w, type ToolCatalog as x, type AnyToolUIPart as y, type ApprovalBlockOptions as z };
+export { type TranscriptQuestion as $, type ApproveOptions as A, type ApprovalBlockOptions as B, type ChatStatus as C, type BuildBlocksOptions as D, type CoercibleQuestion as E, type DescribeToolCallOptions as F, type GenerativeUIItem as G, type ElicitationBlockOptions as H, type GroupToolActivityOptions as I, type RawAnswer as J, type ResolvedReading as K, type ResolvedResultView as L, type MessageUsageInfo as M, type RetrievedPassage as N, type ToolActivityGroup as O, type ToolCallDescription as P, type ToolCallState as Q, type ResolveComponent as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type ToolCallStatus as V, type TranscriptApproval as W, type TranscriptApprovalStatus as X, type TranscriptElicitationBlock as Y, type TranscriptElicitationOutcome as Z, type TranscriptFilesBlock as _, GENUI_TREE_COMPONENT as a, type TranscriptQuestionOption as a0, type TranscriptReasoningBlock as a1, type TranscriptSettleState as a2, type TranscriptSource as a3, type TranscriptSourcesBlock as a4, type TranscriptTextBlock as a5, type TranscriptToolBlock as a6, type TranscriptToolCall as a7, buildTranscriptBlocks as a8, coerceAnswer as a9, correctedCallIds as aa, describeTimestamp as ab, describeToolCall as ac, describeUsage as ad, extractMessageText as ae, fillTemplate as af, formatRelativeTime as ag, groupToolActivity as ah, inferResultView as ai, isActionCall as aj, phraseFor as ak, proposalNeedsPolling as al, readPath as am, reconcileProposalMessages as an, resolveResultView as ao, toolCallState as ap, toolCatalogFrom as aq, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, type ApprovalTarget as t, useGenerativeUI as u, type TranscriptBlock as v, type TimestampInfo as w, type TranscriptFile as x, type ToolCatalog as y, type AnyToolUIPart as z };

package/dist/{generative-ui-VTZ1EADD.d.ts → generative-ui-DOe2RsoO.d.ts}

@@ -1,7 +1,19 @@
 import * as React from 'react';
 import { ComponentType, ReactNode } from 'react';
-import { ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ElicitationInput } from '@dudousxd/nestjs-agent-core';
-import { ToolUIPart, DynamicToolUIPart, UIMessage } from 'ai';
+import { ActionProposal, StoredMessage, ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ToolConfirmation, ElicitationInput } from '@dudousxd/nestjs-agent-core';
+import { UIMessage, ToolUIPart, DynamicToolUIPart } from 'ai';
+
+type ApprovalTarget = {
+    kind: 'legacy';
+    toolCallId: string;
+} | {
+    kind: 'proposal';
+    proposalId: string;
+    threadId?: string;
+};
+declare function proposalNeedsPolling(proposal: ActionProposal): boolean;
+/** Patch proposal metadata and append outcome facts; never replace live text with stored rows. */
+declare function reconcileProposalMessages(current: UIMessage[], proposals: ActionProposal[], facts: StoredMessage[]): UIMessage[];
 
 /** What a form control can hand over: a field's value, a checkbox's state, a picked date, a list. */
 type RawAnswer = string | number | boolean | Date | null | undefined | readonly RawAnswer[];
@@ -96,7 +108,7 @@ declare function resolveResultView(output: unknown, view: ToolResultView | undef
  *  - `done` / `failed` / `denied` — settled. A tool that RETURNS `{ error }` has failed just as much
  *    as one that threw; the two arrive differently and read the same to a person.
  */
-type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied';
+type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied' | 'queued' | 'executing' | 'succeeded';
 interface ToolCallState {
     status: ToolCallStatus;
     isSettled: boolean;
@@ -136,6 +148,8 @@ interface ToolCallDescription {
     presentation: ToolPresentation | null;
 }
 interface DescribeToolCallOptions {
+    /** Resolved strings from the call preflight override the tool catalog templates. */
+    confirmation?: ToolConfirmation;
     /** Words for a tool the catalog does not describe. Default `Working` / `Done`. */
     fallback?: {
         running: string;
@@ -263,13 +277,16 @@ interface TranscriptSettleState {
     run: () => void;
 }
 /** How an approval stands. */
-type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'superseded';
 /**
  * Who has to settle a parked call, until when, and — once it settled — how. From the stream's
  * `approval-requested` / `approval-settled` frames, or the same parts a reloaded thread carries.
  * `null` on a call whose runner never said (the call can still be awaiting approval).
  */
 interface TranscriptApproval {
+    target?: ApprovalTarget;
+    executionStatus?: 'queued' | 'executing' | 'succeeded' | 'failed' | null;
+    confirmation?: ToolConfirmation;
     /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
     approver: string;
     /** ISO-8601; `null` when the request never lapses. Pair with `useApprovalCountdown`. */
@@ -371,6 +388,8 @@ interface TranscriptUiBlock {
     props: Record<string, unknown>;
     /** Schema version of `props`; `null` when the server did not stamp one. */
     version: number | null;
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     /** The tool call that pushed it (`ctx.emitUi`); `null` for a component pushed outside a tool. */
     toolCallId: string | null;
 }
@@ -516,8 +535,8 @@ interface ElicitationBlockOptions {
 interface ApprovalBlockOptions {
     canApprove: boolean;
     canReject: boolean;
-    approve: (toolCallId: string, options?: ApproveOptions) => void;
-    reject: (toolCallId: string) => void;
+    approve: (toolCallId: string, options?: ApproveOptions, target?: ApprovalTarget) => void;
+    reject: (toolCallId: string, target?: ApprovalTarget) => void;
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
     errorOf: (toolCallId: string) => string | null;
@@ -580,6 +599,8 @@ declare function formatRelativeTime(date: Date): string;
 declare const GENUI_TREE_COMPONENT = "genui:tree";
 /** One pushed component, normalized from whatever carried it (a transcript block, a `data-ui` part, a stored entry). */
 interface GenerativeUIItem {
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     id: string;
     component: string;
     props: Record<string, unknown>;
@@ -624,6 +645,9 @@ type ValidationLike = {
  * object does too.
  */
 interface GenuiCatalogLike {
+    get?(name: string): {
+        version?: number;
+    } | undefined;
     has(name: string): boolean;
     validate(name: string, props: unknown): Promise<ValidationLike>;
     validateSync?(name: string, props: unknown): ValidationLike | undefined;
@@ -678,6 +702,8 @@ declare function GenuiTree({ root }: {
     root?: GenerativeUIElement;
 }): React.JSX.Element | null;
 interface GenerativeUIScopeProps extends GenerativeUIOptions {
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     fallback?: GenerativeUIFallback;
     loading?: ReactNode;
     onError?: (error: unknown, item: GenerativeUIItem) => void;
@@ -687,7 +713,7 @@ interface GenerativeUIScopeProps extends GenerativeUIOptions {
  * The registry, catalog and fallbacks tree nodes render with. `<GenerativeUI>` provides it; wrap
  * your own chrome in it when you draw `useGenerativeUI`'s `Component` yourself and it may be a tree.
  */
-declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
+declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, fallbackText, componentVersions, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
 /** What `<GenuiProvider>` hands every `<GenerativeUI>` / `useGenerativeUI` below it. */
 interface GenuiProviderValue extends Partial<GenerativeUIOptions> {
     fallback?: GenerativeUIFallback;
@@ -720,7 +746,7 @@ declare function useGenerativeUI(part: unknown, options?: Partial<GenerativeUIOp
 interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
     /** A transcript `ui` block, a `data-ui` message part, or a stored `{ id, component, props, version? }`. */
     part: TranscriptUiBlock | GenerativeUIItem | unknown;
-    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, else nothing. */
+    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, then the item's persisted text. */
     fallback?: GenerativeUIFallback;
     /** Drawn while a resolver or an async validation is pending. Default: the provider's, else nothing. */
     loading?: ReactNode;
@@ -738,4 +764,4 @@ interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
  */
 declare function GenerativeUI({ part, registry, catalog, resolveComponent, treeRenderer, fallback: ownFallback, loading: ownLoading, onError: ownOnError, }: GenerativeUIProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 
-export { type TranscriptQuestionOption as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type CoercibleQuestion as D, type DescribeToolCallOptions as E, type ElicitationBlockOptions as F, type GenerativeUIItem as G, type GroupToolActivityOptions as H, type RawAnswer as I, type ResolvedReading as J, type ResolvedResultView as K, type RetrievedPassage as L, type MessageUsageInfo as M, type ToolActivityGroup as N, type ToolCallDescription as O, type ToolCallState as P, type ToolCallStatus as Q, type ResolveComponent as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type TranscriptApproval as V, type TranscriptApprovalStatus as W, type TranscriptElicitationBlock as X, type TranscriptElicitationOutcome as Y, type TranscriptFilesBlock as Z, type TranscriptQuestion as _, GENUI_TREE_COMPONENT as a, type TranscriptReasoningBlock as a0, type TranscriptSettleState as a1, type TranscriptSource as a2, type TranscriptSourcesBlock as a3, type TranscriptTextBlock as a4, type TranscriptToolBlock as a5, type TranscriptToolCall as a6, buildTranscriptBlocks as a7, coerceAnswer as a8, correctedCallIds as a9, describeTimestamp as aa, describeToolCall as ab, describeUsage as ac, extractMessageText as ad, fillTemplate as ae, formatRelativeTime as af, groupToolActivity as ag, inferResultView as ah, isActionCall as ai, phraseFor as aj, readPath as ak, resolveResultView as al, toolCallState as am, toolCatalogFrom as an, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, type TranscriptBlock as t, useGenerativeUI as u, type TimestampInfo as v, type TranscriptFile as w, type ToolCatalog as x, type AnyToolUIPart as y, type ApprovalBlockOptions as z };
+export { type TranscriptQuestion as $, type ApproveOptions as A, type ApprovalBlockOptions as B, type ChatStatus as C, type BuildBlocksOptions as D, type CoercibleQuestion as E, type DescribeToolCallOptions as F, type GenerativeUIItem as G, type ElicitationBlockOptions as H, type GroupToolActivityOptions as I, type RawAnswer as J, type ResolvedReading as K, type ResolvedResultView as L, type MessageUsageInfo as M, type RetrievedPassage as N, type ToolActivityGroup as O, type ToolCallDescription as P, type ToolCallState as Q, type ResolveComponent as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type ToolCallStatus as V, type TranscriptApproval as W, type TranscriptApprovalStatus as X, type TranscriptElicitationBlock as Y, type TranscriptElicitationOutcome as Z, type TranscriptFilesBlock as _, GENUI_TREE_COMPONENT as a, type TranscriptQuestionOption as a0, type TranscriptReasoningBlock as a1, type TranscriptSettleState as a2, type TranscriptSource as a3, type TranscriptSourcesBlock as a4, type TranscriptTextBlock as a5, type TranscriptToolBlock as a6, type TranscriptToolCall as a7, buildTranscriptBlocks as a8, coerceAnswer as a9, correctedCallIds as aa, describeTimestamp as ab, describeToolCall as ac, describeUsage as ad, extractMessageText as ae, fillTemplate as af, formatRelativeTime as ag, groupToolActivity as ah, inferResultView as ai, isActionCall as aj, phraseFor as ak, proposalNeedsPolling as al, readPath as am, reconcileProposalMessages as an, resolveResultView as ao, toolCallState as ap, toolCatalogFrom as aq, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, type ApprovalTarget as t, useGenerativeUI as u, type TranscriptBlock as v, type TimestampInfo as w, type TranscriptFile as x, type ToolCatalog as y, type AnyToolUIPart as z };

package/dist/genui-json-render.cjs

@@ -65,6 +65,10 @@ function toGenerativeUIItem(part) {
   return {
     id,
     component: source.component,
+    ...isRecord(source.componentVersions) && Object.values(source.componentVersions).every(
+      (version) => typeof version === "number" && Number.isSafeInteger(version) && version > 0
+    ) ? { componentVersions: { ...source.componentVersions } } : {},
+    ...typeof source.fallbackText === "string" ? { fallbackText: source.fallbackText } : {},
     props: isRecord(source.props) ? source.props : {},
     version: typeof source.version === "number" ? source.version : null,
     toolCallId: typeof source.toolCallId === "string" ? source.toolCallId : null
@@ -170,20 +174,29 @@ function useValidatedProps(catalog, name, props) {
 function useGenerativeUIState(part, options, fallbackTree) {
   const item = (0, import_react2.useMemo)(() => toGenerativeUIItem(part), [part]);
   const name = item?.component ?? "";
+  const definition = options.catalog?.get?.(name);
+  const incompatible = item?.fallbackText !== void 0 && item.version !== null && definition !== void 0 && item.version !== (definition.version ?? 1);
   const resolution = useResolvedComponent(
     name,
     item?.version ?? null,
-    options.registry,
+    incompatible ? {} : options.registry,
     item === null ? void 0 : options.resolveComponent,
     fallbackTree
   );
   const empty = (0, import_react2.useMemo)(() => ({}), []);
   const validation = useValidatedProps(
-    item === null || name === GENUI_TREE_COMPONENT ? void 0 : options.catalog,
+    item === null || name === GENUI_TREE_COMPONENT || incompatible ? void 0 : options.catalog,
     name,
     item?.props ?? empty
   );
   if (item === null) return null;
+  if (name === GENUI_TREE_COMPONENT && item.fallbackText !== void 0 && (!isRecord(item.props.root) || typeof item.props.root.type !== "string"))
+    return {
+      status: "problem",
+      reason: "invalid",
+      item,
+      issues: [{ path: ["root"], message: "Invalid UI tree root" }]
+    };
   if (resolution.status === "loading") return { status: "loading", item };
   if (resolution.status === "unknown") return { status: "problem", reason: "unknown", item };
   if (resolution.status === "error") {
@@ -201,7 +214,8 @@ var import_jsx_runtime = require("react/jsx-runtime");
 var TreeScopeContext = (0, import_react3.createContext)(null);
 function renderFallback(fallback, problem) {
   if (typeof fallback === "function") return fallback(problem);
-  return fallback ?? null;
+  if (fallback !== void 0) return fallback;
+  return problem.item.fallbackText !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: { whiteSpace: "pre-wrap" }, children: problem.item.fallbackText }) : null;
 }
 var ItemBoundary = class extends import_react3.Component {
   state = { error: void 0, failed: false };
@@ -233,28 +247,42 @@ function nodeItem(node, id) {
 function TreeNode({ node, id }) {
   const scope = (0, import_react3.useContext)(TreeScopeContext);
   const item = (0, import_react3.useMemo)(() => nodeItem(node, id), [node, id]);
+  const storedVersion = scope?.componentVersions?.[node.type];
+  const definition = scope?.options.catalog?.get?.(node.type);
+  const incompatible = storedVersion !== void 0 && definition !== void 0 && storedVersion !== (definition.version ?? 1);
   const resolution = useResolvedComponent(
     node.type,
-    null,
-    scope?.options.registry ?? {},
+    storedVersion ?? null,
+    incompatible ? {} : scope?.options.registry ?? {},
     scope?.options.resolveComponent
   );
-  const validation = useValidatedProps(scope?.options.catalog, node.type, item.props);
+  const validation = useValidatedProps(
+    incompatible ? void 0 : scope?.options.catalog,
+    node.type,
+    item.props
+  );
   if (scope === null) return null;
   if (resolution.status === "loading" || validation.status === "pending") return scope.loading;
   if (resolution.status === "unknown") {
+    if (scope.fallback === void 0 && scope.fallbackText !== void 0)
+      throw new Error("Unknown tree component");
     return renderFallback(scope.fallback, { reason: "unknown", item });
   }
   if (resolution.status === "error") {
+    if (scope.fallback === void 0 && scope.fallbackText !== void 0) throw resolution.error;
     return renderFallback(scope.fallback, { reason: "error", item, error: resolution.error });
   }
   if (validation.status === "invalid") {
+    if (scope.fallback === void 0 && scope.fallbackText !== void 0)
+      throw new Error("Invalid tree component");
     return renderFallback(scope.fallback, { reason: "invalid", item, issues: validation.issues });
   }
   const Renderer2 = resolution.Component;
   const children = Array.isArray(node.children) ? node.children : [];
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Renderer2, { ...validation.props, children: children.length > 0 ? children.map((child, index) => {
     const childId = `${id}.${index}`;
+    if (scope.fallback === void 0 && scope.fallbackText !== void 0)
+      return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TreeNode, { node: child, id: childId }, childId);
     return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       ItemBoundary,
       {
@@ -276,6 +304,8 @@ function GenerativeUIScope({
   catalog,
   resolveComponent,
   fallback,
+  fallbackText,
+  componentVersions,
   loading = null,
   onError,
   children
@@ -288,10 +318,21 @@ function GenerativeUIScope({
         ...resolveComponent !== void 0 ? { resolveComponent } : {}
       },
       fallback,
+      ...componentVersions !== void 0 ? { componentVersions } : {},
+      ...fallbackText !== void 0 ? { fallbackText } : {},
       loading,
       onError
     }),
-    [registry, catalog, resolveComponent, fallback, loading, onError]
+    [
+      registry,
+      catalog,
+      resolveComponent,
+      fallback,
+      fallbackText,
+      componentVersions,
+      loading,
+      onError
+    ]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TreeScopeContext.Provider, { value: scope, children });
 }
@@ -351,7 +392,7 @@ function GenerativeUI({
   onError: ownOnError
 }) {
   const provided = (0, import_react3.useContext)(GenuiContext);
-  const fallback = ownFallback ?? provided?.fallback;
+  const fallback = ownFallback !== void 0 ? ownFallback : provided?.fallback;
   const loading = ownLoading ?? provided?.loading ?? null;
   const onError = ownOnError ?? provided?.onError;
   const options = useMergedOptions({
@@ -376,6 +417,8 @@ function GenerativeUI({
     GenerativeUIScope,
     {
       ...options,
+      ...state.item.componentVersions !== void 0 ? { componentVersions: state.item.componentVersions } : {},
+      ...state.item.fallbackText !== void 0 ? { fallbackText: state.item.fallbackText } : {},
       fallback,
       loading,
       ...onError !== void 0 ? { onError } : {},