@copilotkit/react-core 1.51.3-next.6 → 1.51.3-next.7

package/dist/test-helpers/copilot-context.js

@@ -0,0 +1,128 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+
+// src/test-helpers/copilot-context.ts
+var copilot_context_exports = {};
+__export(copilot_context_exports, {
+  createTestCopilotContext: () => createTestCopilotContext
+});
+module.exports = __toCommonJS(copilot_context_exports);
+var noop = () => {
+};
+var copilotApiConfig = {
+  chatApiEndpoint: "http://localhost",
+  headers: {}
+};
+function createTestCopilotContext(overrides = {}) {
+  return __spreadValues({
+    actions: {},
+    setAction: noop,
+    removeAction: noop,
+    setRegisteredActions: () => "action-id",
+    removeRegisteredAction: noop,
+    chatComponentsCache: { current: { actions: {}, coAgentStateRenders: {} } },
+    getFunctionCallHandler: () => () => __async(this, null, function* () {
+    }),
+    addContext: () => "context-id",
+    removeContext: noop,
+    getAllContext: () => [],
+    getContextString: () => "",
+    addDocumentContext: () => "document-id",
+    removeDocumentContext: noop,
+    getDocumentsContext: () => [],
+    isLoading: false,
+    setIsLoading: noop,
+    chatSuggestionConfiguration: {},
+    addChatSuggestionConfiguration: noop,
+    removeChatSuggestionConfiguration: noop,
+    chatInstructions: "",
+    setChatInstructions: noop,
+    additionalInstructions: [],
+    setAdditionalInstructions: noop,
+    copilotApiConfig,
+    showDevConsole: false,
+    coagentStates: {},
+    setCoagentStates: noop,
+    coagentStatesRef: { current: {} },
+    setCoagentStatesWithRef: noop,
+    agentSession: null,
+    setAgentSession: noop,
+    agentLock: null,
+    threadId: "",
+    setThreadId: noop,
+    runId: null,
+    setRunId: noop,
+    chatAbortControllerRef: { current: null },
+    forwardedParameters: {},
+    availableAgents: [],
+    extensions: {},
+    setExtensions: noop,
+    interruptActions: {},
+    setInterruptAction: noop,
+    removeInterruptAction: noop,
+    interruptEventQueue: {},
+    addInterruptEvent: noop,
+    resolveInterruptEvent: noop,
+    onError: noop,
+    bannerError: null,
+    setBannerError: noop,
+    internalErrorHandlers: {},
+    setInternalErrorHandler: noop,
+    removeInternalErrorHandler: noop
+  }, overrides);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createTestCopilotContext
+});
+//# sourceMappingURL=copilot-context.js.map

package/dist/test-helpers/copilot-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/test-helpers/copilot-context.ts"],"sourcesContent":["import type { CopilotContextParams, CopilotApiConfig } from \"../context\";\n\nconst noop = () => {};\n\nconst copilotApiConfig: CopilotApiConfig = {\n  chatApiEndpoint: \"http://localhost\",\n  headers: {},\n};\n\nexport function createTestCopilotContext(\n  overrides: Partial<CopilotContextParams> = {},\n): CopilotContextParams {\n  return {\n    actions: {},\n    setAction: noop,\n    removeAction: noop,\n\n    setRegisteredActions: () => \"action-id\",\n    removeRegisteredAction: noop,\n\n    chatComponentsCache: { current: { actions: {}, coAgentStateRenders: {} } },\n    getFunctionCallHandler: () => async () => {},\n\n    addContext: () => \"context-id\",\n    removeContext: noop,\n    getAllContext: () => [],\n    getContextString: () => \"\",\n\n    addDocumentContext: () => \"document-id\",\n    removeDocumentContext: noop,\n    getDocumentsContext: () => [],\n\n    isLoading: false,\n    setIsLoading: noop,\n\n    chatSuggestionConfiguration: {},\n    addChatSuggestionConfiguration: noop,\n    removeChatSuggestionConfiguration: noop,\n\n    chatInstructions: \"\",\n    setChatInstructions: noop,\n\n    additionalInstructions: [],\n    setAdditionalInstructions: noop,\n\n    copilotApiConfig,\n\n    showDevConsole: false,\n\n    coagentStates: {},\n    setCoagentStates: noop,\n    coagentStatesRef: { current: {} },\n    setCoagentStatesWithRef: noop,\n\n    agentSession: null,\n    setAgentSession: noop,\n\n    agentLock: null,\n\n    threadId: \"\",\n    setThreadId: noop,\n\n    runId: null,\n    setRunId: noop,\n\n    chatAbortControllerRef: { current: null },\n\n    forwardedParameters: {},\n    availableAgents: [],\n\n    extensions: {},\n    setExtensions: noop,\n\n    interruptActions: {},\n    setInterruptAction: noop,\n    removeInterruptAction: noop,\n    interruptEventQueue: {},\n    addInterruptEvent: noop,\n    resolveInterruptEvent: noop,\n\n    onError: noop,\n\n    bannerError: null,\n    setBannerError: noop,\n    internalErrorHandlers: {},\n    setInternalErrorHandler: noop,\n    removeInternalErrorHandler: noop,\n\n    ...overrides,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,IAAM,OAAO,MAAM;AAAC;AAEpB,IAAM,mBAAqC;AAAA,EACzC,iBAAiB;AAAA,EACjB,SAAS,CAAC;AACZ;AAEO,SAAS,yBACd,YAA2C,CAAC,GACtB;AACtB,SAAO;AAAA,IACL,SAAS,CAAC;AAAA,IACV,WAAW;AAAA,IACX,cAAc;AAAA,IAEd,sBAAsB,MAAM;AAAA,IAC5B,wBAAwB;AAAA,IAExB,qBAAqB,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,qBAAqB,CAAC,EAAE,EAAE;AAAA,IACzE,wBAAwB,MAAM,MAAY;AAAA,IAAC;AAAA,IAE3C,YAAY,MAAM;AAAA,IAClB,eAAe;AAAA,IACf,eAAe,MAAM,CAAC;AAAA,IACtB,kBAAkB,MAAM;AAAA,IAExB,oBAAoB,MAAM;AAAA,IAC1B,uBAAuB;AAAA,IACvB,qBAAqB,MAAM,CAAC;AAAA,IAE5B,WAAW;AAAA,IACX,cAAc;AAAA,IAEd,6BAA6B,CAAC;AAAA,IAC9B,gCAAgC;AAAA,IAChC,mCAAmC;AAAA,IAEnC,kBAAkB;AAAA,IAClB,qBAAqB;AAAA,IAErB,wBAAwB,CAAC;AAAA,IACzB,2BAA2B;AAAA,IAE3B;AAAA,IAEA,gBAAgB;AAAA,IAEhB,eAAe,CAAC;AAAA,IAChB,kBAAkB;AAAA,IAClB,kBAAkB,EAAE,SAAS,CAAC,EAAE;AAAA,IAChC,yBAAyB;AAAA,IAEzB,cAAc;AAAA,IACd,iBAAiB;AAAA,IAEjB,WAAW;AAAA,IAEX,UAAU;AAAA,IACV,aAAa;AAAA,IAEb,OAAO;AAAA,IACP,UAAU;AAAA,IAEV,wBAAwB,EAAE,SAAS,KAAK;AAAA,IAExC,qBAAqB,CAAC;AAAA,IACtB,iBAAiB,CAAC;AAAA,IAElB,YAAY,CAAC;AAAA,IACb,eAAe;AAAA,IAEf,kBAAkB,CAAC;AAAA,IACnB,oBAAoB;AAAA,IACpB,uBAAuB;AAAA,IACvB,qBAAqB,CAAC;AAAA,IACtB,mBAAmB;AAAA,IACnB,uBAAuB;AAAA,IAEvB,SAAS;AAAA,IAET,aAAa;AAAA,IACb,gBAAgB;AAAA,IAChB,uBAAuB,CAAC;AAAA,IACxB,yBAAyB;AAAA,IACzB,4BAA4B;AAAA,KAEzB;AAEP;","names":[]}

package/dist/test-helpers/copilot-context.mjs

@@ -0,0 +1,74 @@
+import {
+  __async,
+  __spreadValues
+} from "../chunk-SKC7AJIV.mjs";
+
+// src/test-helpers/copilot-context.ts
+var noop = () => {
+};
+var copilotApiConfig = {
+  chatApiEndpoint: "http://localhost",
+  headers: {}
+};
+function createTestCopilotContext(overrides = {}) {
+  return __spreadValues({
+    actions: {},
+    setAction: noop,
+    removeAction: noop,
+    setRegisteredActions: () => "action-id",
+    removeRegisteredAction: noop,
+    chatComponentsCache: { current: { actions: {}, coAgentStateRenders: {} } },
+    getFunctionCallHandler: () => () => __async(this, null, function* () {
+    }),
+    addContext: () => "context-id",
+    removeContext: noop,
+    getAllContext: () => [],
+    getContextString: () => "",
+    addDocumentContext: () => "document-id",
+    removeDocumentContext: noop,
+    getDocumentsContext: () => [],
+    isLoading: false,
+    setIsLoading: noop,
+    chatSuggestionConfiguration: {},
+    addChatSuggestionConfiguration: noop,
+    removeChatSuggestionConfiguration: noop,
+    chatInstructions: "",
+    setChatInstructions: noop,
+    additionalInstructions: [],
+    setAdditionalInstructions: noop,
+    copilotApiConfig,
+    showDevConsole: false,
+    coagentStates: {},
+    setCoagentStates: noop,
+    coagentStatesRef: { current: {} },
+    setCoagentStatesWithRef: noop,
+    agentSession: null,
+    setAgentSession: noop,
+    agentLock: null,
+    threadId: "",
+    setThreadId: noop,
+    runId: null,
+    setRunId: noop,
+    chatAbortControllerRef: { current: null },
+    forwardedParameters: {},
+    availableAgents: [],
+    extensions: {},
+    setExtensions: noop,
+    interruptActions: {},
+    setInterruptAction: noop,
+    removeInterruptAction: noop,
+    interruptEventQueue: {},
+    addInterruptEvent: noop,
+    resolveInterruptEvent: noop,
+    onError: noop,
+    bannerError: null,
+    setBannerError: noop,
+    internalErrorHandlers: {},
+    setInternalErrorHandler: noop,
+    removeInternalErrorHandler: noop
+  }, overrides);
+}
+export {
+  createTestCopilotContext
+};
+//# sourceMappingURL=copilot-context.mjs.map

package/dist/test-helpers/copilot-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/test-helpers/copilot-context.ts"],"sourcesContent":["import type { CopilotContextParams, CopilotApiConfig } from \"../context\";\n\nconst noop = () => {};\n\nconst copilotApiConfig: CopilotApiConfig = {\n  chatApiEndpoint: \"http://localhost\",\n  headers: {},\n};\n\nexport function createTestCopilotContext(\n  overrides: Partial<CopilotContextParams> = {},\n): CopilotContextParams {\n  return {\n    actions: {},\n    setAction: noop,\n    removeAction: noop,\n\n    setRegisteredActions: () => \"action-id\",\n    removeRegisteredAction: noop,\n\n    chatComponentsCache: { current: { actions: {}, coAgentStateRenders: {} } },\n    getFunctionCallHandler: () => async () => {},\n\n    addContext: () => \"context-id\",\n    removeContext: noop,\n    getAllContext: () => [],\n    getContextString: () => \"\",\n\n    addDocumentContext: () => \"document-id\",\n    removeDocumentContext: noop,\n    getDocumentsContext: () => [],\n\n    isLoading: false,\n    setIsLoading: noop,\n\n    chatSuggestionConfiguration: {},\n    addChatSuggestionConfiguration: noop,\n    removeChatSuggestionConfiguration: noop,\n\n    chatInstructions: \"\",\n    setChatInstructions: noop,\n\n    additionalInstructions: [],\n    setAdditionalInstructions: noop,\n\n    copilotApiConfig,\n\n    showDevConsole: false,\n\n    coagentStates: {},\n    setCoagentStates: noop,\n    coagentStatesRef: { current: {} },\n    setCoagentStatesWithRef: noop,\n\n    agentSession: null,\n    setAgentSession: noop,\n\n    agentLock: null,\n\n    threadId: \"\",\n    setThreadId: noop,\n\n    runId: null,\n    setRunId: noop,\n\n    chatAbortControllerRef: { current: null },\n\n    forwardedParameters: {},\n    availableAgents: [],\n\n    extensions: {},\n    setExtensions: noop,\n\n    interruptActions: {},\n    setInterruptAction: noop,\n    removeInterruptAction: noop,\n    interruptEventQueue: {},\n    addInterruptEvent: noop,\n    resolveInterruptEvent: noop,\n\n    onError: noop,\n\n    bannerError: null,\n    setBannerError: noop,\n    internalErrorHandlers: {},\n    setInternalErrorHandler: noop,\n    removeInternalErrorHandler: noop,\n\n    ...overrides,\n  };\n}\n"],"mappings":";;;;;;AAEA,IAAM,OAAO,MAAM;AAAC;AAEpB,IAAM,mBAAqC;AAAA,EACzC,iBAAiB;AAAA,EACjB,SAAS,CAAC;AACZ;AAEO,SAAS,yBACd,YAA2C,CAAC,GACtB;AACtB,SAAO;AAAA,IACL,SAAS,CAAC;AAAA,IACV,WAAW;AAAA,IACX,cAAc;AAAA,IAEd,sBAAsB,MAAM;AAAA,IAC5B,wBAAwB;AAAA,IAExB,qBAAqB,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,qBAAqB,CAAC,EAAE,EAAE;AAAA,IACzE,wBAAwB,MAAM,MAAY;AAAA,IAAC;AAAA,IAE3C,YAAY,MAAM;AAAA,IAClB,eAAe;AAAA,IACf,eAAe,MAAM,CAAC;AAAA,IACtB,kBAAkB,MAAM;AAAA,IAExB,oBAAoB,MAAM;AAAA,IAC1B,uBAAuB;AAAA,IACvB,qBAAqB,MAAM,CAAC;AAAA,IAE5B,WAAW;AAAA,IACX,cAAc;AAAA,IAEd,6BAA6B,CAAC;AAAA,IAC9B,gCAAgC;AAAA,IAChC,mCAAmC;AAAA,IAEnC,kBAAkB;AAAA,IAClB,qBAAqB;AAAA,IAErB,wBAAwB,CAAC;AAAA,IACzB,2BAA2B;AAAA,IAE3B;AAAA,IAEA,gBAAgB;AAAA,IAEhB,eAAe,CAAC;AAAA,IAChB,kBAAkB;AAAA,IAClB,kBAAkB,EAAE,SAAS,CAAC,EAAE;AAAA,IAChC,yBAAyB;AAAA,IAEzB,cAAc;AAAA,IACd,iBAAiB;AAAA,IAEjB,WAAW;AAAA,IAEX,UAAU;AAAA,IACV,aAAa;AAAA,IAEb,OAAO;AAAA,IACP,UAAU;AAAA,IAEV,wBAAwB,EAAE,SAAS,KAAK;AAAA,IAExC,qBAAqB,CAAC;AAAA,IACtB,iBAAiB,CAAC;AAAA,IAElB,YAAY,CAAC;AAAA,IACb,eAAe;AAAA,IAEf,kBAAkB,CAAC;AAAA,IACnB,oBAAoB;AAAA,IACpB,uBAAuB;AAAA,IACvB,qBAAqB,CAAC;AAAA,IACtB,mBAAmB;AAAA,IACnB,uBAAuB;AAAA,IAEvB,SAAS;AAAA,IAET,aAAa;AAAA,IACb,gBAAgB;AAAA,IAChB,uBAAuB,CAAC;AAAA,IACxB,yBAAyB;AAAA,IACzB,4BAA4B;AAAA,KAEzB;AAEP;","names":[]}

package/dist/types/index.mjs

@@ -1,4 +1,4 @@
 import "../chunk-FD6FGKYY.mjs";
-import "../chunk-6YOKPWQ7.mjs";
 import "../chunk-36KQV2NA.mjs";
+import "../chunk-6YOKPWQ7.mjs";
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.51.3-next.6",
+  "version": "1.51.3-next.7",
   "sideEffects": [
     "**/*.css"
   ],
@@ -59,10 +59,10 @@
     "@scarf/scarf": "^1.3.0",
     "react-markdown": "^8.0.7",
     "untruncate-json": "^0.0.1",
-    "@copilotkit/runtime-client-gql": "1.51.3-next.6",
-    "@copilotkit/shared": "1.51.3-next.6",
-    "@copilotkitnext/core": "1.51.3-next.6",
-    "@copilotkitnext/react": "1.51.3-next.6"
+    "@copilotkit/runtime-client-gql": "1.51.3-next.7",
+    "@copilotkit/shared": "1.51.3-next.7",
+    "@copilotkitnext/core": "1.51.3-next.7",
+    "@copilotkitnext/react": "1.51.3-next.7"
   },
   "keywords": [
     "copilotkit",

package/src/components/copilot-provider/copilotkit.tsx

@@ -19,6 +19,7 @@ import {
   CopilotChatConfigurationProvider,
   CopilotKitInspector,
   CopilotKitProvider as CopilotKitNextProvider,
+  useCopilotKit,
 } from "@copilotkitnext/react";
 import {
   CopilotContext,
@@ -26,6 +27,7 @@ import {
   ChatComponentsCache,
   AgentSession,
   AuthState,
+  useCopilotContext,
 } from "../../context/copilot-context";
 import useTree from "../../hooks/use-tree";
 import { CopilotChatSuggestionConfiguration, DocumentPointer } from "../../types";
@@ -89,6 +91,59 @@ export function CopilotKit({ children, ...props }: CopilotKitProps) {
   );
 }
 
+/**
+ * Bridge component that subscribes to v2.x copilotkit core error events
+ * and forwards them to v1.x error handling system.
+ * This ensures only ONE subscription exists regardless of how many times
+ * Chat components are rendered.
+ */
+function CopilotKitErrorBridge() {
+  const { copilotkit } = useCopilotKit();
+  const { onError, copilotApiConfig } = useCopilotContext();
+
+  useEffect(() => {
+    if (!copilotkit) return;
+
+    const subscription = copilotkit.subscribe({
+      onError: async (event) => {
+        // Convert v2.x error event to v1.x CopilotErrorEvent format
+        const errorEvent: CopilotErrorEvent = {
+          type: "error",
+          timestamp: Date.now(),
+          context: {
+            source: "agent",
+            request: {
+              operation: event.code || "unknown",
+              url: copilotApiConfig?.chatApiEndpoint,
+              startTime: Date.now(),
+            },
+            technical: {
+              environment: "browser",
+              userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+              stackTrace: event.error.stack,
+            },
+            // Add additional context from v2.x event
+            ...event.context,
+          },
+          error: event.error,
+        };
+
+        try {
+          await onError(errorEvent);
+        } catch (handlerError) {
+          console.error("Error in onError handler:", handlerError);
+        }
+      },
+    });
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [copilotkit, onError, copilotApiConfig]);
+
+  return null;
+}
+
 export function CopilotKitInternal(cpkProps: CopilotKitProps) {
   const { children, ...props } = cpkProps;
 
@@ -592,6 +647,7 @@ export function CopilotKitInternal(cpkProps: CopilotKitProps) {
         }}
       >
         <CopilotListeners />
+        <CopilotKitErrorBridge />
         <CoAgentStateRendersProvider>
           <MessagesTapProvider>
             <CopilotMessages>

package/src/context/coagent-state-renders-context.tsx

@@ -13,6 +13,7 @@ interface StateRenderClaim {
   stateRenderId: string;
   stateSnapshot?: any;
   runId?: string;
+  messageIndex?: number;
   locked?: boolean;
 }
 

package/src/hooks/__tests__/use-coagent-state-render-bridge.helpers.test.ts

@@ -0,0 +1,100 @@
+import {
+  ClaimAction,
+  resolveClaim,
+  selectSnapshot,
+  type ClaimsByMessageId,
+  type SnapshotCaches,
+  type StateRenderContext,
+} from "../use-coagent-state-render-bridge.helpers";
+
+describe("useCoAgentStateRenderBridge helpers", () => {
+  describe("resolveClaim", () => {
+    it("updates runId for an existing claim", () => {
+      const claims: ClaimsByMessageId = {
+        msg1: { stateRenderId: "render-a", runId: "pending" },
+      };
+      const context: StateRenderContext = {
+        agentId: "agent-1",
+        stateRenderId: "render-a",
+        messageId: "msg1",
+        runId: "run-123",
+      };
+
+      const result = resolveClaim({ claims, context, stateSnapshot: { step: 1 } });
+      expect(result.action).toBe(ClaimAction.Existing);
+      expect(result.canRender).toBe(true);
+      expect(result.updateRunId).toBe("run-123");
+    });
+
+    it("overrides when a newer message index arrives", () => {
+      const claims: ClaimsByMessageId = {
+        msg1: {
+          stateRenderId: "render-a",
+          runId: "run-1",
+          messageIndex: 0,
+          stateSnapshot: { step: 2 },
+        },
+      };
+      const context: StateRenderContext = {
+        agentId: "agent-1",
+        stateRenderId: "render-a",
+        messageId: "msg2",
+        runId: "run-1",
+        messageIndex: 1,
+      };
+
+      const result = resolveClaim({ claims, context, stateSnapshot: { step: 2 } });
+      expect(result.action).toBe(ClaimAction.Override);
+      expect(result.canRender).toBe(true);
+      expect(result.nextClaim).toMatchObject({
+        stateRenderId: "render-a",
+        runId: "run-1",
+        messageIndex: 1,
+      });
+      expect(result.lockOthers).toBe(true);
+    });
+
+  });
+
+  describe("selectSnapshot", () => {
+    const caches: SnapshotCaches = {
+      byStateRenderAndRun: {},
+      byMessageId: {},
+    };
+
+    it("prefers the explicit state snapshot prop", () => {
+      const result = selectSnapshot({
+        messageId: "msg1",
+        stateRenderId: "render-a",
+        effectiveRunId: "run-1",
+        stateSnapshotProp: "{\"phase\":\"planning\"}",
+        agentState: { phase: "ignored" },
+        agentMessages: [{ id: "assistant-1", role: "assistant" }],
+        caches,
+      });
+
+      expect(result.snapshot).toEqual({ phase: "planning" });
+      expect(result.hasSnapshotKeys).toBe(true);
+    });
+
+    it("falls back to cached snapshots for non-latest assistant messages", () => {
+      const result = selectSnapshot({
+        messageId: "msg-old",
+        stateRenderId: "render-a",
+        effectiveRunId: "run-1",
+        agentState: { phase: "live" },
+        agentMessages: [{ id: "assistant-latest", role: "assistant" }],
+        caches: {
+          byStateRenderAndRun: {
+            "render-a::run-1": { phase: "cached" },
+          },
+          byMessageId: {},
+        },
+      });
+
+      expect(result.snapshot).toBeUndefined();
+      expect(result.cachedSnapshot).toEqual({ phase: "cached" });
+      expect(result.snapshotForClaim).toEqual({ phase: "cached" });
+    });
+  });
+});