@copilotkit/react-core 1.70.2 → 1.71.0

package/dist/index.umd.js

@@ -36,6 +36,133 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 react = __toESM(react);
 react_markdown = __toESM(react_markdown);
 
+//#region src/v2/lib/react-core.ts
+	var CopilotKitCoreReact = class extends _copilotkit_core.CopilotKitCore {
+		constructor(config) {
+			super(config);
+			this._renderToolCalls = [];
+			this._hookRenderToolCalls = /* @__PURE__ */ new Map();
+			this._cachedMergedRenderToolCalls = null;
+			this._renderCustomMessages = [];
+			this._renderActivityMessages = [];
+			this._interruptElement = null;
+			this._renderToolCalls = config.renderToolCalls ?? [];
+			this._renderCustomMessages = config.renderCustomMessages ?? [];
+			this._renderActivityMessages = config.renderActivityMessages ?? [];
+		}
+		get renderCustomMessages() {
+			return this._renderCustomMessages;
+		}
+		get renderActivityMessages() {
+			return this._renderActivityMessages;
+		}
+		get renderToolCalls() {
+			if (this._hookRenderToolCalls.size === 0) return this._renderToolCalls;
+			if (this._cachedMergedRenderToolCalls) return this._cachedMergedRenderToolCalls;
+			const merged = /* @__PURE__ */ new Map();
+			for (const rc of this._renderToolCalls) merged.set(`${rc.agentId ?? ""}:${rc.name}`, rc);
+			for (const [key, rc] of this._hookRenderToolCalls) merged.set(key, rc);
+			this._cachedMergedRenderToolCalls = Array.from(merged.values());
+			return this._cachedMergedRenderToolCalls;
+		}
+		setRenderActivityMessages(renderers) {
+			this._renderActivityMessages = renderers;
+		}
+		setRenderCustomMessages(renderers) {
+			this._renderCustomMessages = renderers;
+		}
+		setRenderToolCalls(renderToolCalls) {
+			this._renderToolCalls = renderToolCalls;
+			this._cachedMergedRenderToolCalls = null;
+			this._notifyRenderToolCallsChanged();
+		}
+		addHookRenderToolCall(entry) {
+			const key = `${entry.agentId ?? ""}:${entry.name}`;
+			this._hookRenderToolCalls.set(key, entry);
+			this._cachedMergedRenderToolCalls = null;
+			this._notifyRenderToolCallsChanged();
+		}
+		removeHookRenderToolCall(name, agentId) {
+			const key = `${agentId ?? ""}:${name}`;
+			if (this._hookRenderToolCalls.delete(key)) {
+				this._cachedMergedRenderToolCalls = null;
+				this._notifyRenderToolCallsChanged();
+			}
+		}
+		_notifyRenderToolCallsChanged() {
+			this.notifySubscribers((subscriber) => {
+				const reactSubscriber = subscriber;
+				if (reactSubscriber.onRenderToolCallsChanged) reactSubscriber.onRenderToolCallsChanged({
+					copilotkit: this,
+					renderToolCalls: this.renderToolCalls
+				});
+			}, "Subscriber onRenderToolCallsChanged error:");
+		}
+		get interruptElement() {
+			return this._interruptElement;
+		}
+		setInterruptElement(element) {
+			this._interruptElement = element;
+			this.notifySubscribers((subscriber) => {
+				subscriber.onInterruptElementChanged?.({
+					copilotkit: this,
+					interruptElement: this._interruptElement
+				});
+			}, "Subscriber onInterruptElementChanged error:");
+		}
+		subscribe(subscriber) {
+			return super.subscribe(subscriber);
+		}
+		/**
+		* Wait for pending React state updates before the follow-up agent run.
+		*
+		* When a frontend tool handler calls setState(), React 18 batches the update
+		* and schedules a commit via its internal scheduler (MessageChannel). The
+		* useAgentContext hook registers context via useLayoutEffect, which runs
+		* synchronously after React commits that batch.
+		*
+		* Awaiting a zero-delay timeout yields to the macrotask queue. React's
+		* MessageChannel task runs first, committing the pending state and running
+		* useLayoutEffect (which updates the context store). The follow-up runAgent
+		* call then reads fresh context.
+		*/
+		async waitForPendingFrameworkUpdates() {
+			await new Promise((resolve) => setTimeout(resolve, 0));
+		}
+	};
+
+//#endregion
+//#region src/v2/context.ts
+	const CopilotKitContext = (0, react.createContext)(null);
+	const useCopilotKit = () => {
+		const context = (0, react.useContext)(CopilotKitContext);
+		const [, forceUpdate] = (0, react.useReducer)((x) => x + 1, 0);
+		if (!context) throw new Error("useCopilotKit must be used within CopilotKitProvider");
+		(0, react.useEffect)(() => {
+			const subscription = context.copilotkit.subscribe({
+				onRuntimeConnectionStatusChanged: () => {
+					forceUpdate();
+				},
+				onHeadersChanged: () => {
+					forceUpdate();
+				}
+			});
+			return () => {
+				subscription.unsubscribe();
+			};
+		}, []);
+		return context;
+	};
+	const LicenseContext = (0, react.createContext)({
+		status: null,
+		license: null,
+		checkFeature: () => true,
+		getLimit: () => null
+	});
+	const CopilotKitAgentIdContext = (0, react.createContext)(void 0);
+	const useDefaultAgentId = () => (0, react.useContext)(CopilotKitAgentIdContext);
+
+//#endregion
 //#region src/v2/lib/shallow-stable-ref.ts
 /**
 	* Shallow equality comparison for objects.
@@ -90,7 +217,12 @@ react_markdown = __toESM(react_markdown);
 		assistantMessageToolbarCopyCodeCopiedLabel: "Copied",
 		assistantMessageToolbarCopyMessageLabel: "Copy",
 		assistantMessageToolbarInspectorLabel: "View in Inspector",
-		assistantMessageToolbarInspectorLocalOnlyLabel: "Development Only",
+		assistantMessageToolbarInspectorDescription: "Open this message in the Inspector",
+		assistantMessageToolbarInspectorLocalOnlyLabel: "Local only",
+		assistantMessageToolbarInspectorLocalOnlyDescription: "Only visible on localhost or loopback hosts in development. Never shown in production.",
+		assistantMessageToolbarInspectorTitle: "CopilotKit Inspector",
+		assistantMessageToolbarInspectorHideLabel: "Hide this icon",
+		assistantMessageToolbarInspectorHideDescription: "Until you reload this page",
 		assistantMessageToolbarThumbsUpLabel: "Good response",
 		assistantMessageToolbarThumbsDownLabel: "Bad response",
 		assistantMessageToolbarReadAloudLabel: "Read aloud",
@@ -131,7 +263,8 @@ react_markdown = __toESM(react_markdown);
 			...parentConfig?.labels,
 			...stableLabels
 		}), [stableLabels, parentConfig?.labels]);
-		const resolvedAgentId = agentId ?? parentConfig?.agentId ?? _copilotkit_shared.DEFAULT_AGENT_ID;
+		const providerAgentId = useDefaultAgentId();
+		const resolvedAgentId = agentId ?? parentConfig?.agentId ?? providerAgentId ?? _copilotkit_shared.DEFAULT_AGENT_ID;
 		const threadIdPropIsAuthoritative = threadId !== void 0 && hasExplicitThreadId !== false;
 		const isThreadIdControlled = threadIdPropIsAuthoritative;
 		const [activeThreadOverride, setActiveThreadOverride] = (0, react.useState)(null);
@@ -339,131 +472,6 @@ react_markdown = __toESM(react_markdown);
 	};
 	ControlledModalOpenScope.displayName = "ControlledModalOpenScope";
 
-//#endregion
-//#region src/v2/lib/react-core.ts
-	var CopilotKitCoreReact = class extends _copilotkit_core.CopilotKitCore {
-		constructor(config) {
-			super(config);
-			this._renderToolCalls = [];
-			this._hookRenderToolCalls = /* @__PURE__ */ new Map();
-			this._cachedMergedRenderToolCalls = null;
-			this._renderCustomMessages = [];
-			this._renderActivityMessages = [];
-			this._interruptElement = null;
-			this._renderToolCalls = config.renderToolCalls ?? [];
-			this._renderCustomMessages = config.renderCustomMessages ?? [];
-			this._renderActivityMessages = config.renderActivityMessages ?? [];
-		}
-		get renderCustomMessages() {
-			return this._renderCustomMessages;
-		}
-		get renderActivityMessages() {
-			return this._renderActivityMessages;
-		}
-		get renderToolCalls() {
-			if (this._hookRenderToolCalls.size === 0) return this._renderToolCalls;
-			if (this._cachedMergedRenderToolCalls) return this._cachedMergedRenderToolCalls;
-			const merged = /* @__PURE__ */ new Map();
-			for (const rc of this._renderToolCalls) merged.set(`${rc.agentId ?? ""}:${rc.name}`, rc);
-			for (const [key, rc] of this._hookRenderToolCalls) merged.set(key, rc);
-			this._cachedMergedRenderToolCalls = Array.from(merged.values());
-			return this._cachedMergedRenderToolCalls;
-		}
-		setRenderActivityMessages(renderers) {
-			this._renderActivityMessages = renderers;
-		}
-		setRenderCustomMessages(renderers) {
-			this._renderCustomMessages = renderers;
-		}
-		setRenderToolCalls(renderToolCalls) {
-			this._renderToolCalls = renderToolCalls;
-			this._cachedMergedRenderToolCalls = null;
-			this._notifyRenderToolCallsChanged();
-		}
-		addHookRenderToolCall(entry) {
-			const key = `${entry.agentId ?? ""}:${entry.name}`;
-			this._hookRenderToolCalls.set(key, entry);
-			this._cachedMergedRenderToolCalls = null;
-			this._notifyRenderToolCallsChanged();
-		}
-		removeHookRenderToolCall(name, agentId) {
-			const key = `${agentId ?? ""}:${name}`;
-			if (this._hookRenderToolCalls.delete(key)) {
-				this._cachedMergedRenderToolCalls = null;
-				this._notifyRenderToolCallsChanged();
-			}
-		}
-		_notifyRenderToolCallsChanged() {
-			this.notifySubscribers((subscriber) => {
-				const reactSubscriber = subscriber;
-				if (reactSubscriber.onRenderToolCallsChanged) reactSubscriber.onRenderToolCallsChanged({
-					copilotkit: this,
-					renderToolCalls: this.renderToolCalls
-				});
-			}, "Subscriber onRenderToolCallsChanged error:");
-		}
-		get interruptElement() {
-			return this._interruptElement;
-		}
-		setInterruptElement(element) {
-			this._interruptElement = element;
-			this.notifySubscribers((subscriber) => {
-				subscriber.onInterruptElementChanged?.({
-					copilotkit: this,
-					interruptElement: this._interruptElement
-				});
-			}, "Subscriber onInterruptElementChanged error:");
-		}
-		subscribe(subscriber) {
-			return super.subscribe(subscriber);
-		}
-		/**
-		* Wait for pending React state updates before the follow-up agent run.
-		*
-		* When a frontend tool handler calls setState(), React 18 batches the update
-		* and schedules a commit via its internal scheduler (MessageChannel). The
-		* useAgentContext hook registers context via useLayoutEffect, which runs
-		* synchronously after React commits that batch.
-		*
-		* Awaiting a zero-delay timeout yields to the macrotask queue. React's
-		* MessageChannel task runs first, committing the pending state and running
-		* useLayoutEffect (which updates the context store). The follow-up runAgent
-		* call then reads fresh context.
-		*/
-		async waitForPendingFrameworkUpdates() {
-			await new Promise((resolve) => setTimeout(resolve, 0));
-		}
-	};
-
-//#endregion
-//#region src/v2/context.ts
-	const CopilotKitContext = (0, react.createContext)(null);
-	const useCopilotKit = () => {
-		const context = (0, react.useContext)(CopilotKitContext);
-		const [, forceUpdate] = (0, react.useReducer)((x) => x + 1, 0);
-		if (!context) throw new Error("useCopilotKit must be used within CopilotKitProvider");
-		(0, react.useEffect)(() => {
-			const subscription = context.copilotkit.subscribe({
-				onRuntimeConnectionStatusChanged: () => {
-					forceUpdate();
-				},
-				onHeadersChanged: () => {
-					forceUpdate();
-				}
-			});
-			return () => {
-				subscription.unsubscribe();
-			};
-		}, []);
-		return context;
-	};
-	const LicenseContext = (0, react.createContext)({
-		status: null,
-		license: null,
-		checkFeature: () => true,
-		getLimit: () => null
-	});
-
 //#endregion
 //#region src/v2/hooks/use-render-tool-call.tsx
 /**
@@ -504,6 +512,29 @@ react_markdown = __toESM(react_markdown);
 		if (prevProps.RenderComponent !== nextProps.RenderComponent) return false;
 		return true;
 	});
+	const IS_DEVELOPMENT$1 = process.env.NODE_ENV !== "production";
+	/**
+	* Reports tool calls that resolved to no renderer.
+	*
+	* A tool call with no renderer paints an empty message container and says
+	* nothing else, so the only signal a developer gets today is a blank space in
+	* the chat. This names the call and the renderers that *are* registered, which
+	* is the whole diagnosis when the cause is a name that does not match.
+	*
+	* @param toolNames - The unmatched tool names collected during render.
+	* @param registered - The registry as it stands now, re-read at report time.
+	* @param alreadyWarned - Names already reported, mutated to keep this once per name.
+	*/
+	function warnAboutUnrenderedToolCalls(toolNames, registered, alreadyWarned) {
+		const registeredNames = Array.from(new Set(registered.map((rc) => rc.name)));
+		const hasWildcard = registeredNames.includes("*");
+		for (const toolName of toolNames) {
+			if (hasWildcard || registeredNames.includes(toolName)) continue;
+			if (alreadyWarned.has(toolName)) continue;
+			alreadyWarned.add(toolName);
+			console.warn(`[CopilotKit] The agent called the tool "${toolName}", and no renderer is registered for it, so that message rendered nothing. ` + (registeredNames.length === 0 ? "No tool-call renderers are registered. " : `Registered renderers: ${registeredNames.map((name) => `"${name}"`).join(", ")}. `) + `Register one with useRenderTool({ name: "${toolName}", ... }), or call useDefaultRenderTool() for a built-in card that covers every tool the agent calls. This warning is development-only.`);
+		}
+	}
 	/**
 	* Hook that returns a function to render tool calls based on the render functions
 	* defined in CopilotKitProvider.
@@ -513,13 +544,18 @@ react_markdown = __toESM(react_markdown);
 	function useRenderToolCall$1() {
 		const { copilotkit, executingToolCallIds } = useCopilotKit();
 		const agentId = useCopilotChatConfiguration()?.agentId ?? _copilotkit_shared.DEFAULT_AGENT_ID;
+		const unrenderedToolNames = (0, react.useRef)(/* @__PURE__ */ new Set());
+		const warnedToolNames = (0, react.useRef)(/* @__PURE__ */ new Set());
 		const renderToolCalls = (0, react.useSyncExternalStore)((callback) => {
 			return copilotkit.subscribe({ onRenderToolCallsChanged: callback }).unsubscribe;
 		}, () => copilotkit.renderToolCalls, () => copilotkit.renderToolCalls);
-		return (0, react.useCallback)(({ toolCall, toolMessage }) => {
+		const renderToolCall = (0, react.useCallback)(({ toolCall, toolMessage }) => {
 			const exactMatches = renderToolCalls.filter((rc) => rc.name === toolCall.function.name);
 			const renderConfig = exactMatches.find((rc) => rc.agentId === agentId) || exactMatches.find((rc) => !rc.agentId) || exactMatches[0] || renderToolCalls.find((rc) => rc.name === "*");
-			if (!renderConfig) return null;
+			if (!renderConfig) {
+				if (IS_DEVELOPMENT$1) unrenderedToolNames.current.add(toolCall.function.name);
+				return null;
+			}
 			const RenderComponent = renderConfig.render;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ToolCallRenderer, {
 				toolCall,
@@ -532,25 +568,43 @@ react_markdown = __toESM(react_markdown);
 			executingToolCallIds,
 			agentId
 		]);
+		(0, react.useEffect)(() => {
+			if (!IS_DEVELOPMENT$1) return;
+			if (unrenderedToolNames.current.size === 0) return;
+			const timer = setTimeout(() => {
+				const pending = Array.from(unrenderedToolNames.current);
+				unrenderedToolNames.current.clear();
+				warnAboutUnrenderedToolCalls(pending, copilotkit.renderToolCalls, warnedToolNames.current);
+			}, 0);
+			return () => clearTimeout(timer);
+		});
+		return renderToolCall;
 	}
 
 //#endregion
 //#region src/v2/components/CopilotKitInspector.tsx
-	const CopilotKitInspector = ({ core, openRequest }) => {
+	const CopilotKitInspector = ({ core, openRequest, onVisibilityChange }) => {
 		const mountRef = react.useRef(null);
 		const inspectorRef = react.useRef(null);
 		const latestCoreRef = react.useRef(core ?? null);
 		const latestOpenRequestRef = react.useRef(openRequest);
+		const visibilityCallbackRef = react.useRef(onVisibilityChange);
+		visibilityCallbackRef.current = onVisibilityChange;
 		latestCoreRef.current = core ?? null;
 		latestOpenRequestRef.current = openRequest;
 		react.useEffect(() => {
 			let mounted = true;
 			let inspector = null;
+			const handleVisibilityChange = (event) => {
+				const visible = event.detail?.visible;
+				visibilityCallbackRef.current?.(visible === true);
+			};
 			import("@copilotkit/web-inspector").then((mod) => {
 				if (!mounted || !mountRef.current) return;
 				mod.defineWebInspector?.();
 				inspector = mountRef.current.ownerDocument.createElement(mod.WEB_INSPECTOR_TAG);
 				mod.configureWebInspectorElement(inspector, latestCoreRef.current);
+				inspector.addEventListener("cpk-inspector-visibility-change", handleVisibilityChange);
 				mountRef.current.appendChild(inspector);
 				inspectorRef.current = inspector;
 				const request = latestOpenRequestRef.current;
@@ -560,7 +614,9 @@ react_markdown = __toESM(react_markdown);
 			});
 			return () => {
 				mounted = false;
+				inspector?.removeEventListener("cpk-inspector-visibility-change", handleVisibilityChange);
 				inspector?.remove();
+				visibilityCallbackRef.current?.(false);
 				if (inspectorRef.current === inspector) inspectorRef.current = null;
 			};
 		}, []);
@@ -1978,6 +2034,95 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		a2ui_operations: zod.z.array(zod.z.any()).optional(),
 		...A2UILifecycleFields
 	}).passthrough();
+	const IS_DEVELOPMENT = process.env.NODE_ENV !== "production";
+	/**
+	* How long to wait for a surface to report its first paint before giving up on
+	* the loader cross-over. Reaching it also means `onReady` never fired, which is
+	* the signal the warning below reports.
+	*/
+	const PAINT_FALLBACK_MS = 8e3;
+	/**
+	* Names the operation kinds a surface received, for a warning that has to say
+	* what did arrive as well as what did not.
+	*
+	* @param operations - The operations grouped under one surface.
+	* @returns A comma-separated list of operation keys, or "none".
+	*/
+	function describeOperationKinds(operations) {
+		const kinds = /* @__PURE__ */ new Set();
+		for (const operation of operations) {
+			if (!operation || typeof operation !== "object") continue;
+			for (const key of Object.keys(operation)) if (key !== "version") kinds.add(key);
+		}
+		return kinds.size === 0 ? "none" : Array.from(kinds).join(", ");
+	}
+	/**
+	* Reports surfaces that received operations and never painted.
+	*
+	* Reaching {@link PAINT_FALLBACK_MS} with no `onReady` means the operations were
+	* accepted, were not malformed enough to raise the provider's error state, and
+	* still put nothing on screen. Left alone that is invisible: the loader drops,
+	* the turn finishes, and the only trace is an empty placeholder above the reply.
+	*
+	* `surfaceHasRenderableContent` already knows which half is missing, so the
+	* warning says which rather than making the reader re-derive it.
+	*
+	* @param grouped - Operations grouped by surface id.
+	*/
+	function warnAboutUnpaintedSurfaces(grouped) {
+		for (const [surfaceId, operations] of grouped) {
+			if (surfaceHasRenderableContent(operations)) continue;
+			const cause = operations.filter((o) => o?.updateComponents).length === 0 ? "no updateComponents operation arrived, so the surface was never given anything to draw" : "its components address their values by \"path\" and no updateDataModel carried a non-empty value, so every bound component drew empty";
+			console.warn(`[CopilotKit] A2UI surface "${surfaceId}" received operations and never painted after ${String(PAINT_FALLBACK_MS)}ms: ${cause}. Operations received: ${describeOperationKinds(operations)}. The payload was accepted, so check what the agent sent rather than the client wiring. This warning is development-only.`);
+		}
+	}
+	/**
+	* Names the component ids a surface was sent, for a warning about the one id
+	* that is missing.
+	*
+	* @param operations - The operations grouped under one surface.
+	* @returns A quoted, comma-separated list of ids, or "none".
+	*/
+	function describeComponentIds(operations) {
+		const ids = [];
+		for (const operation of operations) {
+			const components = operation?.updateComponents?.components;
+			if (!Array.isArray(components)) continue;
+			for (const component of components) {
+				const id = component?.id;
+				if (typeof id === "string" && !ids.includes(id)) ids.push(id);
+			}
+		}
+		return ids.length === 0 ? "none" : ids.map((id) => `"${id}"`).join(", ");
+	}
+	/**
+	* Reports a surface that is still waiting for its {@link ROOT_COMPONENT_ID}
+	* component once its operations have stopped arriving.
+	*
+	* Both renderers begin walking a surface at that one id, and treat an id they
+	* cannot find as not arrived yet — an animated placeholder. That is right while
+	* operations stream. Once they have stopped it is not waiting, it is stuck, and
+	* every other check calls it healthy: the surface exists, `processMessages` did
+	* not throw, the component types were never reached, and
+	* `surfaceHasRenderableContent` says yes on the strength of components plus a
+	* data model, so `onReady` fires and the never-painted report is suppressed.
+	* A complete, accepted payload therefore animates a grey box forever in silence.
+	*
+	* Reads the live components model rather than scanning the operations for the
+	* id, so it covers every way the root can fail to resolve — not only a payload
+	* that never named one.
+	*
+	* @param surfaceId - The surface the operations were addressed to.
+	* @param operations - The operations processed for that surface.
+	* @param surface - The live surface model, already known to exist.
+	*/
+	function warnAboutUnresolvedRoot(surfaceId, operations, surface) {
+		if (surface?.componentsModel?.get?.(_copilotkit_a2ui_renderer.ROOT_COMPONENT_ID)) return;
+		const componentOps = operations.filter((o) => o?.updateComponents);
+		if (componentOps.length === 0) return;
+		const cause = componentOps.some((o) => o.updateComponents?.components?.some?.((c) => c?.id === _copilotkit_a2ui_renderer.ROOT_COMPONENT_ID)) ? `a component with id "${_copilotkit_a2ui_renderer.ROOT_COMPONENT_ID}" WAS sent, so the components did not reach the surface's model — check for an A2UI render error above, or a catalog that took none of them` : `the components it received are named ${describeComponentIds(operations)}, and none of them is "${_copilotkit_a2ui_renderer.ROOT_COMPONENT_ID}" — rename the entry-point component to "${_copilotkit_a2ui_renderer.ROOT_COMPONENT_ID}", and make every other component reachable from it through child/children`;
+		console.warn(`[CopilotKit] A2UI surface "${surfaceId}" has no "${_copilotkit_a2ui_renderer.ROOT_COMPONENT_ID}" component ${String(PAINT_FALLBACK_MS)}ms after its last operations were processed, so it is showing the placeholder for a component that has not arrived yet and will keep showing it: ${cause}. Operations received: ${describeOperationKinds(operations)}. This warning is development-only.`);
+	}
 	function createA2UIMessageRenderer(options) {
 		const { theme, catalog, loadingComponent, recovery, onAction } = options;
 		const showAfterMs = recovery?.showAfterMs ?? 2e3;
@@ -2011,6 +2156,8 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 					return groups;
 				}, [operations]);
 				const hasOps = groupedOperations.size > 0;
+				const groupedOperationsRef = (0, react.useRef)(groupedOperations);
+				groupedOperationsRef.current = groupedOperations;
 				const renderLifecycle = (c) => {
 					const status = c?.status;
 					const debugExposure = resolveDebugExposure(c, optionDebugExposure);
@@ -2042,7 +2189,10 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 						readyRef.current = false;
 						return;
 					}
-					const t = setTimeout(() => setSurfaceReady(true), 8e3);
+					const t = setTimeout(() => {
+						setSurfaceReady(true);
+						if (IS_DEVELOPMENT && !readyRef.current) warnAboutUnpaintedSurfaces(groupedOperationsRef.current);
+					}, PAINT_FALLBACK_MS);
 					return () => clearTimeout(t);
 				}, [hasOps]);
 				if (!hasOps) return renderLifecycle(content);
@@ -2166,8 +2316,21 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			const hash = JSON.stringify(operations);
 			if (hash === lastHashRef.current) return;
 			lastHashRef.current = hash;
-			processMessages(getSurface(surfaceId) ? operations.filter((op) => !op?.createSurface) : operations);
+			const ops = getSurface(surfaceId) ? operations.filter((op) => !op?.createSurface) : operations;
+			processMessages(ops);
 			if (onReady && surfaceHasRenderableContent(operations)) onReady();
+			if (!IS_DEVELOPMENT) return;
+			if (!getSurface(surfaceId)) {
+				const missingSurfaceCheck = setTimeout(() => {
+					if (getSurface(surfaceId)) return;
+					console.warn(`[CopilotKit] A2UI processed ${String(ops.length)} operation(s) addressed to surface "${surfaceId}" and no surface by that id exists, so this card rendered nothing. Operations received: ${describeOperationKinds(ops)}. A createSurface for "${surfaceId}" has to arrive before, or with, the operations that target it. This warning is development-only.`);
+				}, 0);
+				return () => clearTimeout(missingSurfaceCheck);
+			}
+			const unresolvedRootCheck = setTimeout(() => {
+				warnAboutUnresolvedRoot(surfaceId, operations, getSurface(surfaceId));
+			}, PAINT_FALLBACK_MS);
+			return () => clearTimeout(unresolvedRootCheck);
 		}, [
 			processMessages,
 			getSurface,
@@ -2194,10 +2357,26 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			return Object.values(v).some((x) => Array.isArray(x) ? x.length > 0 : x !== null && x !== void 0 && x !== "");
 		});
 	}
+	/**
+	* Resolves the surface an operation addresses.
+	*
+	* The nested v0.9 `surfaceId` wins, because that is the id `MessageProcessor`
+	* creates the surface under. Grouping by a top-level `surfaceId` instead files
+	* the operations against a surface that never exists, which paints nothing —
+	* the silence the missing-surface report above now names. A top-level
+	* `surfaceId` is not the v0.9 shape, so it is honoured only when no nested id is
+	* present. `getSurfaceId` in `@copilotkit/a2ui-renderer`'s web-components path
+	* resolves it in the same order; the two disagreeing is what OSS-1048 recorded.
+	*
+	* @param operation - One A2UI operation, of any shape.
+	* @returns The surface id, or null when the operation names none.
+	*/
 	function getOperationSurfaceId(operation) {
 		if (!operation || typeof operation !== "object") return null;
+		const nested = operation?.createSurface?.surfaceId ?? operation?.updateComponents?.surfaceId ?? operation?.updateDataModel?.surfaceId ?? operation?.deleteSurface?.surfaceId;
+		if (typeof nested === "string") return nested;
 		if (typeof operation.surfaceId === "string") return operation.surfaceId;
-		return operation?.createSurface?.surfaceId ?? operation?.updateComponents?.surfaceId ?? operation?.updateDataModel?.surfaceId ?? operation?.deleteSurface?.surfaceId ?? null;
+		return null;
 	}
 
 //#endregion
@@ -2315,6 +2494,9 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 	const EMPTY_HEADERS = Object.freeze({});
 	const EMPTY_PROPERTIES = Object.freeze({});
 	const EMPTY_AGENTS = Object.freeze({});
+	/** Registration name of a catch-all tool: handles any otherwise-unhandled call. */
+	const WILDCARD_TOOL_NAME$1 = "*";
+	const HUMAN_IN_THE_LOOP_ABORTED_MESSAGE = "Human-in-the-loop interaction aborted";
 	const DEFAULT_DESIGN_SKILL = `When generating UI with generateSandboxedUi, follow these design principles inspired by shadcn/ui:
 
 - Use a minimal, flat aesthetic. Avoid drop shadows and gradients — rely on subtle borders (1px solid, light gray like #e5e7eb) to define surfaces.
@@ -2335,14 +2517,19 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		}, [value, warningMessage]);
 		return value;
 	}
-	const CopilotKitProvider = ({ children, runtimeUrl, headers: headersProp = EMPTY_HEADERS, credentials, publicApiKey, publicLicenseKey, licenseToken, properties = EMPTY_PROPERTIES, agents__unsafe_dev_only: agents = EMPTY_AGENTS, selfManagedAgents = EMPTY_AGENTS, renderToolCalls, renderActivityMessages, renderCustomMessages, frontendTools, humanInTheLoop, openGenerativeUI, enableInspector, useSingleEndpoint, onError, a2ui, defaultThrottleMs, debug }) => {
+	const CopilotKitProvider = ({ children, runtimeUrl, headers: headersProp = EMPTY_HEADERS, credentials, publicApiKey, publicLicenseKey, licenseToken, properties = EMPTY_PROPERTIES, agents__unsafe_dev_only: agents = EMPTY_AGENTS, selfManagedAgents = EMPTY_AGENTS, renderToolCalls, renderActivityMessages, renderCustomMessages, frontendTools, humanInTheLoop, openGenerativeUI, enableInspector, agentId, useSingleEndpoint, onError, a2ui, defaultThrottleMs, debug }) => {
 		const [shouldRenderInspector, setShouldRenderInspector] = (0, react.useState)(false);
+		const [inspectorVisible, setInspectorVisible] = (0, react.useState)(false);
 		(0, react.useEffect)(() => {
 			setShouldRenderInspector((0, _copilotkit_shared.shouldEnableInspector)({
 				enableInspector,
 				isBrowser: true,
 				isDevelopment: process.env.NODE_ENV === "development"
-			}));
+			}) && [
+				"localhost",
+				"127.0.0.1",
+				"[::1]"
+			].includes(window.location.hostname));
 		}, [enableInspector]);
 		const [inspectorOpenRequest, setInspectorOpenRequest] = (0, react.useState)(null);
 		const [runtimeA2UIEnabled, setRuntimeA2UIEnabled] = (0, react.useState)(false);
@@ -2358,9 +2545,15 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 			setInspectorOpenRequest({ ...request });
 		}, []);
 		const inspectorContextValue = (0, react.useMemo)(() => ({
-			isInspectorEnabled: shouldRenderInspector,
+			providerEnableInspector: enableInspector,
+			isInspectorEnabled: shouldRenderInspector && inspectorVisible,
 			openInspector: requestInspectorOpen
-		}), [shouldRenderInspector, requestInspectorOpen]);
+		}), [
+			enableInspector,
+			shouldRenderInspector,
+			inspectorVisible,
+			requestInspectorOpen
+		]);
 		const renderToolCallsList = useStableArrayProp(renderToolCalls, "renderToolCalls must be a stable array. If you want to dynamically add or remove tools, use `useFrontendTool` instead.", (initial, next) => {
 			const key = (rc) => `${rc?.agentId ?? ""}:${rc?.name ?? ""}`;
 			const setFrom = (arr) => new Set(arr.map(key));
@@ -2433,6 +2626,11 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		}
 		const chatApiEndpoint = runtimeUrl ?? (resolvedPublicKey ? COPILOT_CLOUD_CHAT_URL$1 : void 0);
 		const frontendToolsList = useStableArrayProp(frontendTools, "frontendTools must be a stable array. If you want to dynamically add or remove tools, use `useFrontendTool` instead.");
+		/**
+		* A `humanInTheLoop` prop tool call that is parked, waiting on the user.
+		* Keyed by tool call id, so parallel calls of one tool stay independent.
+		*/
+		const pendingHumanInTheLoopRef = (0, react.useRef)(/* @__PURE__ */ new Map());
 		const humanInTheLoopList = useStableArrayProp(humanInTheLoop, "humanInTheLoop must be a stable array. If you want to dynamically add or remove human-in-the-loop tools, use `useHumanInTheLoop` instead.");
 		const sandboxFunctionsList = useStableArrayProp(openGenerativeUI?.sandboxFunctions, "openGenerativeUI.sandboxFunctions must be a stable array.");
 		const processedHumanInTheLoopTools = (0, react.useMemo)(() => {
@@ -2445,20 +2643,52 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 					parameters: tool.parameters,
 					followUp: tool.followUp,
 					...tool.agentId && { agentId: tool.agentId },
-					handler: async () => {
-						return new Promise((resolve) => {
-							console.warn(`Human-in-the-loop tool '${tool.name}' called but no interactive handler is set up.`);
-							resolve(void 0);
+					handler: async (_args, context) => {
+						const signal = context?.signal;
+						const key = context?.toolCall?.id ?? tool.name;
+						return new Promise((resolve, reject) => {
+							if (signal?.aborted) {
+								reject(new Error(HUMAN_IN_THE_LOOP_ABORTED_MESSAGE));
+								return;
+							}
+							const pending = { resolve };
+							pendingHumanInTheLoopRef.current.set(key, pending);
+							if (signal) {
+								const onAbort = () => {
+									pendingHumanInTheLoopRef.current.delete(key);
+									reject(new Error(HUMAN_IN_THE_LOOP_ABORTED_MESSAGE));
+								};
+								signal.addEventListener("abort", onAbort, { once: true });
+								pending.detachAbort = () => {
+									signal.removeEventListener("abort", onAbort);
+								};
+							}
 						});
 					}
 				};
 				processedTools.push(frontendTool);
-				if (tool.render) processedRenderToolCalls.push({
-					name: tool.name,
-					args: tool.parameters,
-					render: tool.render,
-					...tool.agentId && { agentId: tool.agentId }
-				});
+				if (tool.render) {
+					const ToolComponent = tool.render;
+					const RenderComponent = (props) => (0, react.createElement)(ToolComponent, {
+						...props,
+						name: tool.name === WILDCARD_TOOL_NAME$1 ? props.name : tool.name,
+						description: tool.description || "",
+						agentId: tool.agentId,
+						respond: props.status === _copilotkit_core.ToolCallStatus.Executing ? async (result) => {
+							const pending = pendingHumanInTheLoopRef.current.get(props.toolCallId);
+							if (!pending) return;
+							pending.detachAbort?.();
+							pendingHumanInTheLoopRef.current.delete(props.toolCallId);
+							pending.resolve(result);
+						} : void 0
+					});
+					processedRenderToolCalls.push({
+						name: tool.name,
+						args: tool.parameters,
+						render: RenderComponent,
+						...tool.agentId && { agentId: tool.agentId }
+					});
+				}
 			});
 			return {
 				tools: processedTools,
@@ -2720,9 +2950,13 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 						}),
 						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)(CopilotKitInspectorContextProvider, {
 							value: inspectorContextValue,
-							children: [children, shouldRenderInspector ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(CopilotKitInspector, {
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(CopilotKitAgentIdContext.Provider, {
+								value: agentId,
+								children
+							}), shouldRenderInspector ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(CopilotKitInspector, {
 								core: copilotkit,
-								openRequest: inspectorOpenRequest
+								openRequest: inspectorOpenRequest,
+								onVisibilityChange: setInspectorVisible
 							}) : null]
 						}),
 						runtimeLicenseWarningStatus === "none" && !resolvedPublicKey && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LicenseWarningBanner, { type: "no_license" }),
@@ -2924,7 +3158,8 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 		if (runtimeAgentId != null && threadId == null) throw new Error(`useAgent: \`runtimeAgentId\` requires \`threadId\`. A proxied agent exists to scope a thread to a private instance; without a threadId it behaves like the shared agent while adding a registration and a local agentId to keep unique. Either pass the thread, e.g. useAgent({ agentId: "${agentId ?? "chat-1"}", runtimeAgentId: "${runtimeAgentId}", threadId }), or bind to the agent directly with useAgent({ agentId: "${runtimeAgentId}" }).`);
 		if (runtimeAgentId != null && agentId == null) throw new Error(`useAgent: \`runtimeAgentId\` requires an explicit \`agentId\`. The proxied agent is registered under \`agentId\`, and the usual fallbacks (chat configuration, then "${_copilotkit_shared.DEFAULT_AGENT_ID}") name agents that already exist — registering over one throws or shadows it. Pick a local id for this hook, e.g. useAgent({ agentId: "chat-1", runtimeAgentId: "${runtimeAgentId}", threadId }).`);
 		const chatConfig = useCopilotChatConfiguration();
-		const resolvedAgentId = agentId ?? chatConfig?.agentId ?? _copilotkit_shared.DEFAULT_AGENT_ID;
+		const providerAgentId = useDefaultAgentId();
+		const resolvedAgentId = agentId ?? chatConfig?.agentId ?? providerAgentId ?? _copilotkit_shared.DEFAULT_AGENT_ID;
 		const { copilotkit } = useCopilotKit();
 		const providerThrottleMs = copilotkit.defaultThrottleMs;
 		const [, forceUpdate] = (0, react.useReducer)((x) => x + 1, 0);
@@ -3107,7 +3342,12 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 	function useSuggestions({ agentId } = {}) {
 		const { copilotkit } = useCopilotKit();
 		const config = useCopilotChatConfiguration();
-		const resolvedAgentId = (0, react.useMemo)(() => agentId ?? config?.agentId ?? _copilotkit_shared.DEFAULT_AGENT_ID, [agentId, config?.agentId]);
+		const providerAgentId = useDefaultAgentId();
+		const resolvedAgentId = (0, react.useMemo)(() => agentId ?? config?.agentId ?? providerAgentId ?? _copilotkit_shared.DEFAULT_AGENT_ID, [
+			agentId,
+			config?.agentId,
+			providerAgentId
+		]);
 		const [suggestions, setSuggestions] = (0, react.useState)(() => {
 			return copilotkit.getSuggestions(resolvedAgentId).suggestions;
 		});
@@ -6769,7 +7009,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 	*
 	* ### Example
 	* A great example of this is in our Perplexity Clone where we render the progress of an agent's internet search as it is happening.
-	* You can play around with it below or learn how to build it with its [demo](/coagents/videos/perplexity-clone).
+	* You can play around with it below or learn how to build it with the [state rendering guide](/generative-ui/state-rendering).
 	*
 	* <Callout type="info">
 	*   This example is hosted on Vercel and may take a few seconds to load.
@@ -6957,7 +7197,7 @@ window.parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/sandbox-proxy-
 	function useCopilotReadable({ description, value, convert, available = "enabled" }, dependencies) {
 		const { copilotkit } = useCopilotKit();
 		const ctxIdRef = (0, react.useRef)(void 0);
-		(0, react.useEffect)(() => {
+		(0, react.useLayoutEffect)(() => {
 			if (!copilotkit) return;
 			if (available === "disabled") return;
 			const id = copilotkit.addContext({