@copilotkit/react-core 1.59.4 → 1.59.5

package/dist/{copilotkit-LdQ8w20l.cjs → copilotkit-CFfEVdV4.cjs}

@@ -2954,210 +2954,110 @@ const OpenGenerativeUIToolRenderer = function OpenGenerativeUIToolRenderer(props
 };
 
 //#endregion
-//#region src/v2/a2ui/A2UIMessageRenderer.tsx
-/**
-* The container key used to wrap A2UI operations for explicit detection.
-* Must match A2UI_OPERATIONS_KEY in @ag-ui/a2ui-middleware and copilotkit.a2ui (Python).
-*/
-const A2UI_OPERATIONS_KEY = "a2ui_operations";
-let initialized = false;
-function ensureInitialized() {
-	if (!initialized) {
-		(0, _copilotkit_a2ui_renderer.initializeDefaultCatalog)();
-		(0, _copilotkit_a2ui_renderer.injectStyles)();
-		initialized = true;
-	}
-}
-function createA2UIMessageRenderer(options) {
-	const { theme, catalog, loadingComponent } = options;
-	return {
-		activityType: "a2ui-surface",
-		content: zod.z.any(),
-		render: ({ content, agent }) => {
-			ensureInitialized();
-			const [operations, setOperations] = (0, react.useState)([]);
-			const { copilotkit } = useCopilotKit();
-			const lastContentRef = (0, react.useRef)(null);
-			(0, react.useEffect)(() => {
-				if (content === lastContentRef.current) return;
-				lastContentRef.current = content;
-				const incoming = content?.[A2UI_OPERATIONS_KEY];
-				if (!content || !Array.isArray(incoming)) {
-					setOperations([]);
-					return;
-				}
-				setOperations(incoming);
-			}, [content]);
-			const groupedOperations = (0, react.useMemo)(() => {
-				const groups = /* @__PURE__ */ new Map();
-				for (const operation of operations) {
-					const surfaceId = getOperationSurfaceId(operation) ?? _copilotkit_a2ui_renderer.DEFAULT_SURFACE_ID;
-					if (!groups.has(surfaceId)) groups.set(surfaceId, []);
-					groups.get(surfaceId).push(operation);
-				}
-				return groups;
-			}, [operations]);
-			if (!groupedOperations.size) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(loadingComponent ?? DefaultA2UILoading, {});
-			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-				className: "cpk:flex cpk:min-h-0 cpk:flex-1 cpk:flex-col cpk:gap-6 cpk:overflow-auto cpk:py-6",
-				children: Array.from(groupedOperations.entries()).map(([surfaceId, ops]) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReactSurfaceHost, {
-					surfaceId,
-					operations: ops,
-					theme,
-					agent,
-					copilotkit,
-					catalog
-				}, surfaceId))
-			});
-		}
-	};
-}
+//#region src/v2/a2ui/A2UIRecoveryStates.tsx
 /**
-* Renders a single A2UI surface using the React renderer.
-* Wraps A2UIProvider + A2UIRenderer and bridges actions back to CopilotKit.
+* The pre-paint lifecycle fields the middleware stamps onto the `a2ui-surface`
+* activity content (alongside `a2ui_operations` on paint). `.passthrough()` keeps
+* `a2ui_operations` and any future fields intact.
 */
-function ReactSurfaceHost({ surfaceId, operations, theme, agent, copilotkit, catalog }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-		className: "cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4",
-		children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(_copilotkit_a2ui_renderer.A2UIProvider, {
-			onAction: (0, react.useCallback)(async (message) => {
-				if (!agent) return;
-				message.userAction;
-				try {
-					copilotkit.setProperties({
-						...copilotkit.properties,
-						a2uiAction: message
-					});
-					await copilotkit.runAgent({ agent });
-				} finally {
-					if (copilotkit.properties) {
-						const { a2uiAction, ...rest } = copilotkit.properties;
-						copilotkit.setProperties(rest);
-					}
-				}
-			}, [agent, copilotkit]),
-			theme,
-			catalog,
-			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SurfaceMessageProcessor, {
-				surfaceId,
-				operations
-			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UISurfaceOrError, { surfaceId })]
-		})
-	});
+const A2UILifecycleFields = {
+	status: zod.z.enum([
+		"building",
+		"retrying",
+		"failed"
+	]).optional(),
+	attempt: zod.z.number().optional(),
+	maxAttempts: zod.z.number().optional(),
+	progressTokens: zod.z.number().optional(),
+	error: zod.z.string().optional(),
+	errors: zod.z.array(zod.z.any()).optional(),
+	attempts: zod.z.array(zod.z.any()).optional(),
+	debugExposure: zod.z.enum([
+		"hidden",
+		"collapsed",
+		"verbose"
+	]).optional()
+};
+/** Server-stamped debugExposure wins; else the client option; else "collapsed". */
+function resolveDebugExposure(content, optionDebugExposure) {
+	return content?.debugExposure ?? optionDebugExposure;
 }
-/**
-* Renders the A2UI surface, or an error message if processing failed.
-* Must be a child of A2UIProvider to access the error state.
-*/
-function A2UISurfaceOrError({ surfaceId }) {
-	const error = (0, _copilotkit_a2ui_renderer.useA2UIError)();
-	if (error) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-		className: "cpk:rounded-lg cpk:border cpk:border-red-200 cpk:bg-red-50 cpk:p-3 cpk:text-sm cpk:text-red-700",
-		children: ["A2UI render error: ", error]
-	});
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_copilotkit_a2ui_renderer.A2UIRenderer, {
-		surfaceId,
-		className: "cpk:flex cpk:flex-1"
+/** building: the generic skeleton + optional live token count. */
+function A2UIBuildingState({ content }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIGeneratingSkeleton, {
+		label: "Building interface",
+		tokens: typeof content?.progressTokens === "number" ? content.progressTokens : void 0
 	});
 }
 /**
-* Processes A2UI operations into the provider's message processor.
-* Must be a child of A2UIProvider to access the actions context.
+* retrying: stays the generic skeleton through fast/transient retries; only once
+* the retry is perceptible (after `showAfterMs`, or once `attempt` crosses
+* `showAfterAttempts`) does the sub-label reveal "Retrying generation… (N/M)".
 */
-function SurfaceMessageProcessor({ surfaceId, operations }) {
-	const { processMessages, getSurface } = (0, _copilotkit_a2ui_renderer.useA2UIActions)();
-	const lastHashRef = (0, react.useRef)("");
+function A2UIRetryingState({ content, showAfterMs, showAfterAttempts, debugExposure }) {
+	const attempt = typeof content?.attempt === "number" ? content.attempt : void 0;
+	const maxAttempts = typeof content?.maxAttempts === "number" ? content.maxAttempts : void 0;
+	const immediate = attempt !== void 0 && attempt >= showAfterAttempts;
+	const [revealed, setRevealed] = (0, react.useState)(immediate);
 	(0, react.useEffect)(() => {
-		const hash = JSON.stringify(operations);
-		if (hash === lastHashRef.current) return;
-		lastHashRef.current = hash;
-		processMessages(getSurface(surfaceId) ? operations.filter((op) => !op?.createSurface) : operations);
-	}, [
-		processMessages,
-		getSurface,
-		surfaceId,
-		operations
-	]);
-	return null;
+		if (immediate) {
+			setRevealed(true);
+			return;
+		}
+		const timer = setTimeout(() => setRevealed(true), showAfterMs);
+		return () => clearTimeout(timer);
+	}, [immediate, showAfterMs]);
+	const tokens = typeof content?.progressTokens === "number" ? content.progressTokens : void 0;
+	if (!revealed) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIGeneratingSkeleton, {
+		label: "Building interface",
+		tokens
+	});
+	const label = attempt !== void 0 && maxAttempts !== void 0 ? `Retrying generation… (${attempt}/${maxAttempts} attempts)` : "Retrying generation…";
+	const errors = Array.isArray(content?.errors) ? content.errors : [];
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIGeneratingSkeleton, {
+		label,
+		tokens,
+		children: debugExposure !== "hidden" && errors.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIDebugDetails, {
+			label: "validation issues",
+			open: debugExposure === "verbose",
+			payload: {
+				attempt: content?.attempt,
+				errors
+			}
+		})
+	});
 }
-/**
-* Default loading component shown while an A2UI surface is generating.
-* Displays an animated shimmer skeleton.
-*/
-function DefaultA2UILoading() {
+/** failed: a clean hard-failure card that replaces the skeleton in place. */
+function A2UIRecoveryFailure({ content, debugExposure }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-		className: "cpk:flex cpk:flex-col cpk:gap-3 cpk:rounded-xl cpk:border cpk:border-gray-100 cpk:bg-gray-50/50 cpk:p-5",
-		style: { minHeight: 120 },
+		className: "cpk:rounded-lg cpk:border cpk:border-amber-200 cpk:bg-amber-50 cpk:p-3 cpk:text-sm cpk:text-amber-800",
 		children: [
-			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-				className: "cpk:flex cpk:items-center cpk:gap-2",
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-					className: "cpk:h-3 cpk:w-3 cpk:rounded-full cpk:bg-gray-200",
-					style: { animation: "cpk-a2ui-pulse 1.5s ease-in-out infinite" }
-				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-					className: "cpk:text-xs cpk:font-medium cpk:text-gray-400",
-					children: "Generating UI..."
-				})]
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "cpk:font-medium",
+				children: "Couldn't generate the UI"
 			}),
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-				className: "cpk:flex cpk:flex-col cpk:gap-2",
-				children: [
-					.8,
-					.6,
-					.4
-				].map((width, i) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-					className: "cpk:h-3 cpk:rounded cpk:bg-gray-200/70",
-					style: {
-						width: `${width * 100}%`,
-						animation: `cpk-a2ui-pulse 1.5s ease-in-out ${i * .15}s infinite`
-					}
-				}, i))
+				className: "cpk:mt-1 cpk:text-xs cpk:text-amber-700",
+				children: "Something went wrong rendering this. You can keep chatting and try again."
 			}),
-			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: `
-        @keyframes cpk-a2ui-pulse {
-          0%, 100% { opacity: 0.4; }
-          50% { opacity: 1; }
-        }
-      ` })
+			debugExposure !== "hidden" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIDebugDetails, {
+				label: "developer details",
+				open: debugExposure === "verbose",
+				payload: {
+					error: content?.error,
+					attempts: content?.attempts
+				}
+			})
 		]
 	});
 }
-function getOperationSurfaceId(operation) {
-	if (!operation || typeof operation !== "object") return null;
-	if (typeof operation.surfaceId === "string") return operation.surfaceId;
-	return operation?.createSurface?.surfaceId ?? operation?.updateComponents?.surfaceId ?? operation?.updateDataModel?.surfaceId ?? operation?.deleteSurface?.surfaceId ?? null;
-}
-
-//#endregion
-//#region src/v2/a2ui/A2UIToolCallRenderer.tsx
-/**
-* Tool name used by the dynamic A2UI generation secondary LLM.
-* This renderer is auto-registered when A2UI is enabled.
-*/
-const RENDER_A2UI_TOOL_NAME = "render_a2ui";
 /**
-* Built-in progress indicator for dynamic A2UI generation.
-* Shows a skeleton wireframe that progressively reveals as tokens stream in.
-*
-* Registered automatically when A2UI is enabled. Users can override by
-* providing their own `useRenderTool({ name: "render_a2ui", ... })`.
+* Animated wireframe skeleton with a label, an optional live token count, and an
+* optional debug-detail slot below it. Pure CSS animation (no data dependency).
+* The `tokens` count drives a progressive reveal of skeleton rows.
 */
-function A2UIProgressIndicator({ parameters }) {
-	const lastRef = (0, react.useRef)({
-		time: 0,
-		tokens: 0
-	});
-	const now = Date.now();
-	let { tokens } = lastRef.current;
-	if (now - lastRef.current.time > 200) {
-		const chars = JSON.stringify(parameters ?? {}).length;
-		tokens = Math.round(chars / 4);
-		lastRef.current = {
-			time: now,
-			tokens
-		};
-	}
-	const phase = tokens < 50 ? 0 : tokens < 200 ? 1 : tokens < 400 ? 2 : 3;
+function A2UIGeneratingSkeleton({ label, tokens, children }) {
+	const phase = tokens == null ? 3 : tokens < 50 ? 0 : tokens < 200 ? 1 : tokens < 400 ? 2 : 3;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		style: {
 			margin: "12px 0",
@@ -3365,8 +3265,8 @@ function A2UIProgressIndicator({ parameters }) {
 						color: "#a1a1aa",
 						letterSpacing: "0.025em"
 					},
-					children: "Building interface"
-				}), tokens > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+					children: label
+				}), typeof tokens === "number" && tokens > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 					style: {
 						fontSize: 11,
 						color: "#d4d4d8",
@@ -3379,6 +3279,7 @@ function A2UIProgressIndicator({ parameters }) {
 					]
 				})]
 			}),
+			children,
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: `
         @keyframes cpk-a2ui-fade {
           0%, 100% { opacity: 1; }
@@ -3392,6 +3293,20 @@ function A2UIProgressIndicator({ parameters }) {
 		]
 	});
 }
+function A2UIDebugDetails({ label, open, payload }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("details", {
+		open,
+		className: "cpk:mt-2 cpk:text-xs",
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("summary", {
+			className: "cpk:cursor-pointer cpk:text-gray-500",
+			children: label
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
+			className: "cpk:mt-1 cpk:overflow-auto cpk:rounded cpk:bg-gray-100 cpk:p-2 cpk:text-gray-700",
+			style: { fontSize: 11 },
+			children: JSON.stringify(payload, null, 2)
+		})]
+	});
+}
 function Dot() {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { style: {
 		width: 7,
@@ -3427,13 +3342,242 @@ function Row({ children, show, delay = 0 }) {
 		children
 	});
 }
+
+//#endregion
+//#region src/v2/a2ui/A2UIMessageRenderer.tsx
+/**
+* The container key used to wrap A2UI operations for explicit detection.
+* Must match A2UI_OPERATIONS_KEY in @ag-ui/a2ui-middleware and copilotkit.a2ui (Python).
+*/
+const A2UI_OPERATIONS_KEY = "a2ui_operations";
+let initialized = false;
+function ensureInitialized() {
+	if (!initialized) {
+		(0, _copilotkit_a2ui_renderer.initializeDefaultCatalog)();
+		(0, _copilotkit_a2ui_renderer.injectStyles)();
+		initialized = true;
+	}
+}
+/**
+* The `a2ui-surface` activity carries the WHOLE generative-UI lifecycle on one
+* stable messageId (OSS-162): pre-paint `status` ("building" | "retrying" |
+* "failed") with recovery detail, then `a2ui_operations` on paint. The states
+* swap in place, so the painted surface replaces the skeleton with no extra
+* coordination. `.passthrough()` preserves operations + any future fields.
+*/
+const A2UISurfaceContentSchema = zod.z.object({
+	a2ui_operations: zod.z.array(zod.z.any()).optional(),
+	...A2UILifecycleFields
+}).passthrough();
+function createA2UIMessageRenderer(options) {
+	const { theme, catalog, loadingComponent, recovery } = options;
+	const showAfterMs = recovery?.showAfterMs ?? 2e3;
+	const showAfterAttempts = recovery?.showAfterAttempts ?? 2;
+	const optionDebugExposure = recovery?.debugExposure ?? "collapsed";
+	return {
+		activityType: "a2ui-surface",
+		content: A2UISurfaceContentSchema,
+		render: ({ content, agent }) => {
+			ensureInitialized();
+			const [operations, setOperations] = (0, react.useState)([]);
+			const { copilotkit } = useCopilotKit();
+			const lastContentRef = (0, react.useRef)(null);
+			(0, react.useEffect)(() => {
+				if (content === lastContentRef.current) return;
+				lastContentRef.current = content;
+				const incoming = content?.[A2UI_OPERATIONS_KEY];
+				if (!content || !Array.isArray(incoming)) {
+					setOperations([]);
+					return;
+				}
+				setOperations(incoming);
+			}, [content]);
+			const groupedOperations = (0, react.useMemo)(() => {
+				const groups = /* @__PURE__ */ new Map();
+				for (const operation of operations) {
+					const surfaceId = getOperationSurfaceId(operation) ?? _copilotkit_a2ui_renderer.DEFAULT_SURFACE_ID;
+					if (!groups.has(surfaceId)) groups.set(surfaceId, []);
+					groups.get(surfaceId).push(operation);
+				}
+				return groups;
+			}, [operations]);
+			const hasOps = groupedOperations.size > 0;
+			const renderLifecycle = (c) => {
+				const status = c?.status;
+				const debugExposure = resolveDebugExposure(c, optionDebugExposure);
+				if (status === "failed") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIRecoveryFailure, {
+					content: c,
+					debugExposure
+				});
+				if (status === "retrying") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIRetryingState, {
+					content: c,
+					showAfterMs,
+					showAfterAttempts,
+					debugExposure
+				});
+				if (loadingComponent) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(loadingComponent, {});
+				return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIBuildingState, { content: c });
+			};
+			const lastLoaderContentRef = (0, react.useRef)(null);
+			if (!(Array.isArray(content?.[A2UI_OPERATIONS_KEY]) && content[A2UI_OPERATIONS_KEY].length > 0)) lastLoaderContentRef.current = content;
+			const [surfaceReady, setSurfaceReady] = (0, react.useState)(false);
+			const readyRef = (0, react.useRef)(false);
+			const markSurfaceReady = (0, react.useCallback)(() => {
+				if (readyRef.current) return;
+				readyRef.current = true;
+				requestAnimationFrame(() => setSurfaceReady(true));
+			}, []);
+			(0, react.useEffect)(() => {
+				if (!hasOps) {
+					setSurfaceReady(false);
+					readyRef.current = false;
+					return;
+				}
+				const t = setTimeout(() => setSurfaceReady(true), 8e3);
+				return () => clearTimeout(t);
+			}, [hasOps]);
+			if (!hasOps) return renderLifecycle(content);
+			const surfaces = /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "cpk:flex cpk:min-h-0 cpk:flex-1 cpk:flex-col cpk:gap-6 cpk:overflow-auto cpk:py-6",
+				children: Array.from(groupedOperations.entries()).map(([surfaceId, ops]) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReactSurfaceHost, {
+					surfaceId,
+					operations: ops,
+					theme,
+					agent,
+					copilotkit,
+					catalog,
+					onReady: markSurfaceReady
+				}, surfaceId))
+			});
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: { position: "relative" },
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					"aria-hidden": !surfaceReady,
+					style: surfaceReady ? void 0 : {
+						position: "absolute",
+						inset: 0,
+						opacity: 0,
+						pointerEvents: "none"
+					},
+					children: surfaces
+				}), !surfaceReady && renderLifecycle(lastLoaderContentRef.current ?? content)]
+			});
+		}
+	};
+}
+/**
+* Renders a single A2UI surface using the React renderer.
+* Wraps A2UIProvider + A2UIRenderer and bridges actions back to CopilotKit.
+*/
+function ReactSurfaceHost({ surfaceId, operations, theme, agent, copilotkit, catalog, onReady }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+		className: "cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4",
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(_copilotkit_a2ui_renderer.A2UIProvider, {
+			onAction: (0, react.useCallback)(async (message) => {
+				if (!agent) return;
+				message.userAction;
+				try {
+					copilotkit.setProperties({
+						...copilotkit.properties,
+						a2uiAction: message
+					});
+					await copilotkit.runAgent({ agent });
+				} finally {
+					if (copilotkit.properties) {
+						const { a2uiAction, ...rest } = copilotkit.properties;
+						copilotkit.setProperties(rest);
+					}
+				}
+			}, [agent, copilotkit]),
+			theme,
+			catalog,
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SurfaceMessageProcessor, {
+				surfaceId,
+				operations,
+				onReady
+			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UISurfaceOrError, { surfaceId })]
+		})
+	});
+}
 /**
-* Registers the built-in `render_a2ui` tool call renderer via the props-based
-* `setRenderToolCalls` mechanism (not `useRenderTool`).
+* Renders the A2UI surface, or an error message if processing failed.
+* Must be a child of A2UIProvider to access the error state.
+*/
+function A2UISurfaceOrError({ surfaceId }) {
+	const error = (0, _copilotkit_a2ui_renderer.useA2UIError)();
+	if (error) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: "cpk:rounded-lg cpk:border cpk:border-red-200 cpk:bg-red-50 cpk:p-3 cpk:text-sm cpk:text-red-700",
+		children: ["A2UI render error: ", error]
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_copilotkit_a2ui_renderer.A2UIRenderer, {
+		surfaceId,
+		className: "cpk:flex cpk:flex-1"
+	});
+}
+/**
+* Processes A2UI operations into the provider's message processor.
+* Must be a child of A2UIProvider to access the actions context.
+*/
+function SurfaceMessageProcessor({ surfaceId, operations, onReady }) {
+	const { processMessages, getSurface } = (0, _copilotkit_a2ui_renderer.useA2UIActions)();
+	const lastHashRef = (0, react.useRef)("");
+	(0, react.useEffect)(() => {
+		const hash = JSON.stringify(operations);
+		if (hash === lastHashRef.current) return;
+		lastHashRef.current = hash;
+		processMessages(getSurface(surfaceId) ? operations.filter((op) => !op?.createSurface) : operations);
+		if (onReady && surfaceHasRenderableContent(operations)) onReady();
+	}, [
+		processMessages,
+		getSurface,
+		surfaceId,
+		operations,
+		onReady
+	]);
+	return null;
+}
+/**
+* Whether the surface's operations are enough to paint a visible card yet.
+* A data-bound surface references its data via `path` and renders nothing until
+* the data model has ≥1 value; a static surface (no path refs) paints from its
+* components alone. Used to time the loader→surface cross-over to actual content
+* arrival rather than a fixed delay. (OSS-162)
+*/
+function surfaceHasRenderableContent(operations) {
+	const componentOps = operations.filter((o) => o?.updateComponents);
+	if (!componentOps.length) return false;
+	if (!JSON.stringify(componentOps).includes("\"path\"")) return true;
+	return operations.some((o) => {
+		const v = o?.updateDataModel?.value;
+		if (!v || typeof v !== "object") return false;
+		return Object.values(v).some((x) => Array.isArray(x) ? x.length > 0 : x !== null && x !== void 0 && x !== "");
+	});
+}
+function getOperationSurfaceId(operation) {
+	if (!operation || typeof operation !== "object") return null;
+	if (typeof operation.surfaceId === "string") return operation.surfaceId;
+	return operation?.createSurface?.surfaceId ?? operation?.updateComponents?.surfaceId ?? operation?.updateDataModel?.surfaceId ?? operation?.deleteSurface?.surfaceId ?? null;
+}
+
+//#endregion
+//#region src/v2/a2ui/A2UIToolCallRenderer.tsx
+/**
+* Tool name used by the dynamic A2UI generation secondary LLM.
+*/
+const RENDER_A2UI_TOOL_NAME = "render_a2ui";
+/**
+* Registers a no-op renderer for the `render_a2ui` tool call so its raw streamed
+* args are never surfaced in the transcript.
 *
-* This ensures user-registered `useRenderTool({ name: "render_a2ui", ... })`
-* hooks automatically override the built-in, since the merge logic in
-* react-core.ts gives hook-based entries priority over prop-based entries.
+* The generation skeleton / retry / failure UX is NO LONGER owned here (OSS-162):
+* the A2UI middleware drives the whole lifecycle on the `a2ui-surface` activity
+* (one stable messageId, building → retrying → failed → painted), rendered in
+* place by `createA2UIMessageRenderer`. Owning a skeleton per tool call caused a
+* duplicate skeleton on retries / multi-call generations and a skeleton that
+* lingered after the surface painted — both fixed by retiring it here.
+*
+* Users can still override with their own `useRenderTool({ name: "render_a2ui" })`
+* (hook-based entries take priority over this prop-based registration).
 */
 function A2UIBuiltInToolCallRenderer() {
 	const { copilotkit } = useCopilotKit();
@@ -3441,15 +3585,7 @@ function A2UIBuiltInToolCallRenderer() {
 		const renderer = defineToolCallRenderer({
 			name: RENDER_A2UI_TOOL_NAME,
 			args: zod.z.any(),
-			render: ({ status, args: parameters }) => {
-				if (status === "complete") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {});
-				const params = parameters;
-				const items = params?.items;
-				if (Array.isArray(items) && items.length > 0) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {});
-				const components = params?.components;
-				if (Array.isArray(components) && components.length > 2) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {});
-				return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(A2UIProgressIndicator, { parameters });
-			}
+			render: () => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {})
 		});
 		const existing = copilotkit._renderToolCalls ?? [];
 		copilotkit.setRenderToolCalls([...existing.filter((rc) => rc.name !== RENDER_A2UI_TOOL_NAME), renderer]);
@@ -3586,7 +3722,8 @@ const CopilotKitProvider = ({ children, runtimeUrl, headers: headersProp = EMPTY
 		if (runtimeA2UIEnabled) renderers.unshift(createA2UIMessageRenderer({
 			theme: a2ui?.theme ?? _copilotkit_a2ui_renderer.viewerTheme,
 			catalog: a2ui?.catalog,
-			loadingComponent: a2ui?.loadingComponent
+			loadingComponent: a2ui?.loadingComponent,
+			recovery: a2ui?.recovery
 		}));
 		return renderers;
 	}, [
@@ -11024,4 +11161,4 @@ Object.defineProperty(exports, 'useToast', {
     return useToast;
   }
 });
-//# sourceMappingURL=copilotkit-LdQ8w20l.cjs.map
+//# sourceMappingURL=copilotkit-CFfEVdV4.cjs.map