@tambo-ai/react 0.67.1 → 0.69.0

package/README.md

@@ -241,20 +241,18 @@ const InteractableNote = withInteractable(Note, {
 Connect to Linear, Slack, databases, or your own MCP servers. Tambo supports the full MCP protocol: tools, prompts, elicitations, and sampling.
 
 ```tsx
-import { TamboMcpProvider, MCPTransport } from "@tambo-ai/react/mcp";
+import { MCPTransport } from "@tambo-ai/react/mcp";
 
 const mcpServers = [
   {
     name: "filesystem",
-    url: "http://localhost:3001/mcp",
+    url: "http://localhost:8261/mcp",
     transport: MCPTransport.HTTP,
   },
 ];
 
 <TamboProvider components={components} mcpServers={mcpServers}>
-  <TamboMcpProvider>
-    <App />
-  </TamboMcpProvider>
+  <App />
 </TamboProvider>;
 ```
 

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

@@ -13,11 +13,17 @@ describe("Context Helpers (prebuilt functions)", () => {
             const context = (0, index_1.currentTimeContextHelper)();
             // Should not be null (error case)
             expect(context).not.toBeNull();
+            // Type guard: ensure context is an object
+            expect(typeof context).toBe("object");
+            if (typeof context !== "object" || context === null) {
+                throw new Error("Expected context to be a non-null object");
+            }
             // Shape: { timestamp: string }
             expect(context).toHaveProperty("timestamp");
-            expect(typeof context.timestamp).toBe("string");
+            const contextObj = context;
+            expect(typeof contextObj.timestamp).toBe("string");
             // Verify timestamp string parses
-            expect(() => new Date(context.timestamp)).not.toThrow();
+            expect(() => new Date(contextObj.timestamp)).not.toThrow();
         });
     });
     describe("currentPageContextHelper", () => {
@@ -28,11 +34,17 @@ describe("Context Helpers (prebuilt functions)", () => {
                 expect(context).toBeNull();
                 return;
             }
+            // Type guard: ensure context is an object
+            expect(typeof context).toBe("object");
+            if (typeof context !== "object") {
+                throw new Error("Expected context to be an object");
+            }
             // Shape: { url: string, title: string }
             expect(context).toHaveProperty("url");
             expect(context).toHaveProperty("title");
-            expect(typeof context.url).toBe("string");
-            expect(typeof context.title).toBe("string");
+            const contextObj = context;
+            expect(typeof contextObj.url).toBe("string");
+            expect(typeof contextObj.title).toBe("string");
         });
     });
 });

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

@@ -1 +1 @@
-{"version":3,"file":"context-helpers.test.js","sourceRoot":"","sources":["../../src/context-helpers/context-helpers.test.ts"],"names":[],"mappings":";;AAAA,mCAA6E;AAE7E;;;;;GAKG;AACH,QAAQ,CAAC,sCAAsC,EAAE,GAAG,EAAE;IACpD,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACxC,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;YAC9D,MAAM,OAAO,GAAG,IAAA,gCAAwB,GAAE,CAAC;YAE3C,kCAAkC;YAClC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAE/B,+BAA+B;YAC/B,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;YAC5C,MAAM,CAAC,OAAO,OAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAEjD,iCAAiC;YACjC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,OAAQ,CAAC,SAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACrE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACxC,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;YAClE,MAAM,OAAO,GAAG,IAAA,gCAAwB,GAAE,CAAC;YAE3C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,sDAAsD;gBACtD,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;gBAC3B,OAAO;YACT,CAAC;YAED,wCAAwC;YACxC,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YACtC,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;YAExC,MAAM,CAAC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1C,MAAM,CAAC,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { currentPageContextHelper, currentTimeContextHelper } from \"./index\";\n\n/**\n * Tests for prebuilt context helper functions.\n *\n * These helpers now return raw values (or null) instead of { name, context }.\n * The provider is responsible for wrapping values as { name, context }.\n */\ndescribe(\"Context Helpers (prebuilt functions)\", () => {\n  describe(\"currentTimeContextHelper\", () => {\n    it(\"should return user time context with required fields\", () => {\n      const context = currentTimeContextHelper();\n\n      // Should not be null (error case)\n      expect(context).not.toBeNull();\n\n      // Shape: { timestamp: string }\n      expect(context).toHaveProperty(\"timestamp\");\n      expect(typeof context!.timestamp).toBe(\"string\");\n\n      // Verify timestamp string parses\n      expect(() => new Date(context!.timestamp as string)).not.toThrow();\n    });\n  });\n\n  describe(\"currentPageContextHelper\", () => {\n    it(\"should return page context in browser, or null otherwise\", () => {\n      const context = currentPageContextHelper();\n\n      if (context === null) {\n        // Non-browser environments should return null to skip\n        expect(context).toBeNull();\n        return;\n      }\n\n      // Shape: { url: string, title: string }\n      expect(context).toHaveProperty(\"url\");\n      expect(context).toHaveProperty(\"title\");\n\n      expect(typeof context.url).toBe(\"string\");\n      expect(typeof context.title).toBe(\"string\");\n    });\n  });\n});\n"]}
+{"version":3,"file":"context-helpers.test.js","sourceRoot":"","sources":["../../src/context-helpers/context-helpers.test.ts"],"names":[],"mappings":";;AAAA,mCAA6E;AAE7E;;;;;GAKG;AACH,QAAQ,CAAC,sCAAsC,EAAE,GAAG,EAAE;IACpD,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACxC,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;YAC9D,MAAM,OAAO,GAAG,IAAA,gCAAwB,GAAE,CAAC;YAE3C,kCAAkC;YAClC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAE/B,0CAA0C;YAC1C,MAAM,CAAC,OAAO,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACtC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACpD,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;YAC9D,CAAC;YAED,+BAA+B;YAC/B,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;YAC5C,MAAM,UAAU,GAAG,OAAkC,CAAC;YACtD,MAAM,CAAC,OAAO,UAAU,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAEnD,iCAAiC;YACjC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,SAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACvE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACxC,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;YAClE,MAAM,OAAO,GAAG,IAAA,gCAAwB,GAAE,CAAC;YAE3C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,sDAAsD;gBACtD,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;gBAC3B,OAAO;YACT,CAAC;YAED,0CAA0C;YAC1C,MAAM,CAAC,OAAO,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACtC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;YACtD,CAAC;YAED,wCAAwC;YACxC,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YACtC,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;YAExC,MAAM,UAAU,GAAG,OAAkC,CAAC;YACtD,MAAM,CAAC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC7C,MAAM,CAAC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { currentPageContextHelper, currentTimeContextHelper } from \"./index\";\n\n/**\n * Tests for prebuilt context helper functions.\n *\n * These helpers now return raw values (or null) instead of { name, context }.\n * The provider is responsible for wrapping values as { name, context }.\n */\ndescribe(\"Context Helpers (prebuilt functions)\", () => {\n  describe(\"currentTimeContextHelper\", () => {\n    it(\"should return user time context with required fields\", () => {\n      const context = currentTimeContextHelper();\n\n      // Should not be null (error case)\n      expect(context).not.toBeNull();\n\n      // Type guard: ensure context is an object\n      expect(typeof context).toBe(\"object\");\n      if (typeof context !== \"object\" || context === null) {\n        throw new Error(\"Expected context to be a non-null object\");\n      }\n\n      // Shape: { timestamp: string }\n      expect(context).toHaveProperty(\"timestamp\");\n      const contextObj = context as Record<string, unknown>;\n      expect(typeof contextObj.timestamp).toBe(\"string\");\n\n      // Verify timestamp string parses\n      expect(() => new Date(contextObj.timestamp as string)).not.toThrow();\n    });\n  });\n\n  describe(\"currentPageContextHelper\", () => {\n    it(\"should return page context in browser, or null otherwise\", () => {\n      const context = currentPageContextHelper();\n\n      if (context === null) {\n        // Non-browser environments should return null to skip\n        expect(context).toBeNull();\n        return;\n      }\n\n      // Type guard: ensure context is an object\n      expect(typeof context).toBe(\"object\");\n      if (typeof context !== \"object\") {\n        throw new Error(\"Expected context to be an object\");\n      }\n\n      // Shape: { url: string, title: string }\n      expect(context).toHaveProperty(\"url\");\n      expect(context).toHaveProperty(\"title\");\n\n      const contextObj = context as Record<string, unknown>;\n      expect(typeof contextObj.url).toBe(\"string\");\n      expect(typeof contextObj.title).toBe(\"string\");\n    });\n  });\n});\n"]}

package/dist/context-helpers/current-interactables-context-helper.d.ts

@@ -22,7 +22,7 @@ export declare const currentInteractablesContextHelper: ContextHelperFn;
  * Creates an interactables context helper with access to the current components.
  * This is used internally by TamboInteractableProvider.
  * @param components Array of interactable components
- * @returns Context helper function
+ * @returns A context helper function that returns component metadata or null if no components exist
  */
-export declare const createInteractablesContextHelper: (components: any[]) => ContextHelperFn;
+export declare const createInteractablesContextHelper: (components: unknown[]) => ContextHelperFn;
 //# sourceMappingURL=current-interactables-context-helper.d.ts.map

package/dist/context-helpers/current-interactables-context-helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"current-interactables-context-helper.d.ts","sourceRoot":"","sources":["../../src/context-helpers/current-interactables-context-helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAI/C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC3C,YAAY,GAAG,EAAE,KAChB,eAqBF,CAAC"}
+{"version":3,"file":"current-interactables-context-helper.d.ts","sourceRoot":"","sources":["../../src/context-helpers/current-interactables-context-helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAI/C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC3C,YAAY,OAAO,EAAE,KACpB,eAyCF,CAAC"}

package/dist/context-helpers/current-interactables-context-helper.js

@@ -29,7 +29,7 @@ exports.currentInteractablesContextHelper = currentInteractablesContextHelper;
  * Creates an interactables context helper with access to the current components.
  * This is used internally by TamboInteractableProvider.
  * @param components Array of interactable components
- * @returns Context helper function
+ * @returns A context helper function that returns component metadata or null if no components exist
  */
 const createInteractablesContextHelper = (components) => {
     return () => {
@@ -37,17 +37,36 @@ const createInteractablesContextHelper = (components) => {
             return null; // No interactable components on the page
         }
         return {
-            description: "These are the interactable components currently visible on the page that you can read and modify. Each component has an id, componentName, current props, current state,and optional schema. You can use tools to update these components on behalf of the user. Don't tell the user the ID of the components, only the name, unless they ask for it.",
-            components: components.map((component) => ({
-                id: component.id,
-                componentName: component.name,
-                description: component.description,
-                props: component.props,
-                propsSchema: component.propsSchema
-                    ? "Available - use component-specific update tools"
-                    : "Not specified",
-                state: component.state,
-            })),
+            components: components.map((component) => {
+                // Type guard: ensure component is an object with the expected properties
+                if (typeof component !== "object" || component === null) {
+                    return {
+                        id: "unknown",
+                        componentName: "unknown",
+                        description: "invalid component",
+                        props: undefined,
+                        propsSchema: "Not specified",
+                        state: undefined,
+                        isSelectedForInteraction: false,
+                        stateSchema: "Not specified",
+                    };
+                }
+                const comp = component;
+                return {
+                    id: String(comp.id ?? "unknown"),
+                    componentName: String(comp.name ?? "unknown"),
+                    description: String(comp.description ?? ""),
+                    props: comp.props,
+                    propsSchema: comp.propsSchema
+                        ? "Available - use component-specific update tools"
+                        : "Not specified",
+                    state: comp.state,
+                    isSelectedForInteraction: comp.isSelectedForInteraction ?? false,
+                    stateSchema: comp.stateSchema
+                        ? "Available - use component-specific update tools"
+                        : "Not specified",
+                };
+            }),
         };
     };
 };

package/dist/context-helpers/current-interactables-context-helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"current-interactables-context-helper.js","sourceRoot":"","sources":["../../src/context-helpers/current-interactables-context-helper.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;GAiBG;AACI,MAAM,iCAAiC,GAAoB,GAAG,EAAE;IACrE,mFAAmF;IACnF,wEAAwE;IACxE,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAJW,QAAA,iCAAiC,qCAI5C;AAEF;;;;;GAKG;AACI,MAAM,gCAAgC,GAAG,CAC9C,UAAiB,EACA,EAAE;IACnB,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,OAAO,IAAI,CAAC,CAAC,yCAAyC;QACxD,CAAC;QAED,OAAO;YACL,WAAW,EACT,uVAAuV;YACzV,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;gBACzC,EAAE,EAAE,SAAS,CAAC,EAAE;gBAChB,aAAa,EAAE,SAAS,CAAC,IAAI;gBAC7B,WAAW,EAAE,SAAS,CAAC,WAAW;gBAClC,KAAK,EAAE,SAAS,CAAC,KAAK;gBACtB,WAAW,EAAE,SAAS,CAAC,WAAW;oBAChC,CAAC,CAAC,iDAAiD;oBACnD,CAAC,CAAC,eAAe;gBACnB,KAAK,EAAE,SAAS,CAAC,KAAK;aACvB,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,CAAC;AAvBW,QAAA,gCAAgC,oCAuB3C","sourcesContent":["import { ContextHelperFn } from \"./types\";\n\n/**\n * Prebuilt context helper that provides information about all interactable components currently on the page.\n * This gives the AI awareness of what components it can interact with and their current state.\n * @returns an object with description and components, or null to skip including this context.\n * To disable this helper, override it with a function that returns null:\n * @example\n * ```tsx\n * // To disable the default interactables context\n * const { addContextHelper } = useTamboContextHelpers();\n * addContextHelper(\"interactables\", () => null);\n *\n * // To customize the context\n * addContextHelper(\"interactables\", () => ({\n *   description: \"Custom description\",\n *   components: getCustomComponentsSubset()\n * }));\n * ```\n */\nexport const currentInteractablesContextHelper: ContextHelperFn = () => {\n  // This will be provided by the interactable provider when it registers this helper\n  // Since we're provider-only now, this function gets replaced at runtime\n  return null;\n};\n\n/**\n * Creates an interactables context helper with access to the current components.\n * This is used internally by TamboInteractableProvider.\n * @param components Array of interactable components\n * @returns Context helper function\n */\nexport const createInteractablesContextHelper = (\n  components: any[],\n): ContextHelperFn => {\n  return () => {\n    if (!Array.isArray(components) || components.length === 0) {\n      return null; // No interactable components on the page\n    }\n\n    return {\n      description:\n        \"These are the interactable components currently visible on the page that you can read and modify. Each component has an id, componentName, current props, current state,and optional schema. You can use tools to update these components on behalf of the user. Don't tell the user the ID of the components, only the name, unless they ask for it.\",\n      components: components.map((component) => ({\n        id: component.id,\n        componentName: component.name,\n        description: component.description,\n        props: component.props,\n        propsSchema: component.propsSchema\n          ? \"Available - use component-specific update tools\"\n          : \"Not specified\",\n        state: component.state,\n      })),\n    };\n  };\n};\n"]}
+{"version":3,"file":"current-interactables-context-helper.js","sourceRoot":"","sources":["../../src/context-helpers/current-interactables-context-helper.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;GAiBG;AACI,MAAM,iCAAiC,GAAoB,GAAG,EAAE;IACrE,mFAAmF;IACnF,wEAAwE;IACxE,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAJW,QAAA,iCAAiC,qCAI5C;AAEF;;;;;GAKG;AACI,MAAM,gCAAgC,GAAG,CAC9C,UAAqB,EACJ,EAAE;IACnB,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,OAAO,IAAI,CAAC,CAAC,yCAAyC;QACxD,CAAC;QAED,OAAO;YACL,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;gBACvC,yEAAyE;gBACzE,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;oBACxD,OAAO;wBACL,EAAE,EAAE,SAAS;wBACb,aAAa,EAAE,SAAS;wBACxB,WAAW,EAAE,mBAAmB;wBAChC,KAAK,EAAE,SAAS;wBAChB,WAAW,EAAE,eAAe;wBAC5B,KAAK,EAAE,SAAS;wBAChB,wBAAwB,EAAE,KAAK;wBAC/B,WAAW,EAAE,eAAe;qBAC7B,CAAC;gBACJ,CAAC;gBAED,MAAM,IAAI,GAAG,SAAoC,CAAC;gBAClD,OAAO;oBACL,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,SAAS,CAAC;oBAChC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC;oBAC7C,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;oBAC3C,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,WAAW,EAAE,IAAI,CAAC,WAAW;wBAC3B,CAAC,CAAC,iDAAiD;wBACnD,CAAC,CAAC,eAAe;oBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,wBAAwB,EACrB,IAAI,CAAC,wBAAgD,IAAI,KAAK;oBACjE,WAAW,EAAE,IAAI,CAAC,WAAW;wBAC3B,CAAC,CAAC,iDAAiD;wBACnD,CAAC,CAAC,eAAe;iBACpB,CAAC;YACJ,CAAC,CAAC;SACH,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,CAAC;AA3CW,QAAA,gCAAgC,oCA2C3C","sourcesContent":["import { ContextHelperFn } from \"./types\";\n\n/**\n * Prebuilt context helper that provides information about all interactable components currently on the page.\n * This gives the AI awareness of what components it can interact with and their current state.\n * @returns an object with description and components, or null to skip including this context.\n * To disable this helper, override it with a function that returns null:\n * @example\n * ```tsx\n * // To disable the default interactables context\n * const { addContextHelper } = useTamboContextHelpers();\n * addContextHelper(\"interactables\", () => null);\n *\n * // To customize the context\n * addContextHelper(\"interactables\", () => ({\n *   description: \"Custom description\",\n *   components: getCustomComponentsSubset()\n * }));\n * ```\n */\nexport const currentInteractablesContextHelper: ContextHelperFn = () => {\n  // This will be provided by the interactable provider when it registers this helper\n  // Since we're provider-only now, this function gets replaced at runtime\n  return null;\n};\n\n/**\n * Creates an interactables context helper with access to the current components.\n * This is used internally by TamboInteractableProvider.\n * @param components Array of interactable components\n * @returns A context helper function that returns component metadata or null if no components exist\n */\nexport const createInteractablesContextHelper = (\n  components: unknown[],\n): ContextHelperFn => {\n  return () => {\n    if (!Array.isArray(components) || components.length === 0) {\n      return null; // No interactable components on the page\n    }\n\n    return {\n      components: components.map((component) => {\n        // Type guard: ensure component is an object with the expected properties\n        if (typeof component !== \"object\" || component === null) {\n          return {\n            id: \"unknown\",\n            componentName: \"unknown\",\n            description: \"invalid component\",\n            props: undefined,\n            propsSchema: \"Not specified\",\n            state: undefined,\n            isSelectedForInteraction: false,\n            stateSchema: \"Not specified\",\n          };\n        }\n\n        const comp = component as Record<string, unknown>;\n        return {\n          id: String(comp.id ?? \"unknown\"),\n          componentName: String(comp.name ?? \"unknown\"),\n          description: String(comp.description ?? \"\"),\n          props: comp.props,\n          propsSchema: comp.propsSchema\n            ? \"Available - use component-specific update tools\"\n            : \"Not specified\",\n          state: comp.state,\n          isSelectedForInteraction:\n            (comp.isSelectedForInteraction as boolean | undefined) ?? false,\n          stateSchema: comp.stateSchema\n            ? \"Available - use component-specific update tools\"\n            : \"Not specified\",\n        };\n      }),\n    };\n  };\n};\n"]}

package/dist/context-helpers/registry.d.ts

@@ -2,13 +2,13 @@
  * Global context helpers registry.
  * Consumers can add/remove helpers and resolve additional context anywhere.
  */
-export type HelperFn = () => any | null | undefined | Promise<any | null | undefined>;
+export type HelperFn = () => unknown | null | undefined | Promise<unknown | null | undefined>;
 /**
  * Resolve all helpers to AdditionalContext entries, skipping null/undefined and errors.
  * @returns The resolved additional context.
  */
 export declare function resolveAdditionalContext(helpers: Record<string, HelperFn>): Promise<{
     name: string;
-    context: any;
+    context: unknown;
 }[]>;
 //# sourceMappingURL=registry.d.ts.map

package/dist/context-helpers/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/context-helpers/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,QAAQ,GAAG,MACnB,GAAG,GACH,IAAI,GACJ,SAAS,GACT,OAAO,CAAC,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEpC;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAChC,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAE,EAAE,CAAC,CAkB3C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/context-helpers/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,QAAQ,GAAG,MACnB,OAAO,GACP,IAAI,GACJ,SAAS,GACT,OAAO,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAExC;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAChC,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,EAAE,CAAC,CAkB/C"}

package/dist/context-helpers/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/context-helpers/registry.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAYH,4DAoBC;AAxBD;;;GAGG;AACI,KAAK,UAAU,wBAAwB,CAC5C,OAAiC;IAEjC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE;QAC/B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAC;YACzB,IAAI,KAAK,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC/B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,gCAAgC,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9D,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAAqC,CAAC;AACrE,CAAC","sourcesContent":["/**\n * Global context helpers registry.\n * Consumers can add/remove helpers and resolve additional context anywhere.\n */\n\nexport type HelperFn = () =>\n  | any\n  | null\n  | undefined\n  | Promise<any | null | undefined>;\n\n/**\n * Resolve all helpers to AdditionalContext entries, skipping null/undefined and errors.\n * @returns The resolved additional context.\n */\nexport async function resolveAdditionalContext(\n  helpers: Record<string, HelperFn>,\n): Promise<{ name: string; context: any }[]> {\n  const entries = Object.entries(helpers);\n  if (entries.length === 0) return [];\n\n  const results = await Promise.all(\n    entries.map(async ([name, fn]) => {\n      try {\n        const value = await fn();\n        if (value == null) return null;\n        return { name, context: value };\n      } catch (error) {\n        console.error(`Error running context helper ${name}:`, error);\n        return null;\n      }\n    }),\n  );\n\n  return results.filter(Boolean) as { name: string; context: any }[];\n}\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/context-helpers/registry.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAYH,4DAoBC;AAxBD;;;GAGG;AACI,KAAK,UAAU,wBAAwB,CAC5C,OAAiC;IAEjC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE;QAC/B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAC;YACzB,IAAI,KAAK,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC/B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,gCAAgC,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9D,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAAyC,CAAC;AACzE,CAAC","sourcesContent":["/**\n * Global context helpers registry.\n * Consumers can add/remove helpers and resolve additional context anywhere.\n */\n\nexport type HelperFn = () =>\n  | unknown\n  | null\n  | undefined\n  | Promise<unknown | null | undefined>;\n\n/**\n * Resolve all helpers to AdditionalContext entries, skipping null/undefined and errors.\n * @returns The resolved additional context.\n */\nexport async function resolveAdditionalContext(\n  helpers: Record<string, HelperFn>,\n): Promise<{ name: string; context: unknown }[]> {\n  const entries = Object.entries(helpers);\n  if (entries.length === 0) return [];\n\n  const results = await Promise.all(\n    entries.map(async ([name, fn]) => {\n      try {\n        const value = await fn();\n        if (value == null) return null;\n        return { name, context: value };\n      } catch (error) {\n        console.error(`Error running context helper ${name}:`, error);\n        return null;\n      }\n    }),\n  );\n\n  return results.filter(Boolean) as { name: string; context: unknown }[];\n}\n"]}

package/dist/context-helpers/types.d.ts

@@ -5,13 +5,13 @@ export interface AdditionalContext {
     /** The name of the context type */
     name: string;
     /** The context data */
-    context: any;
+    context: unknown;
 }
 /**
  * A context helper is a function that returns data to include in the context,
  * or null/undefined to skip including anything.
  */
-export type ContextHelperFn = () => any | null | undefined | Promise<any | null | undefined>;
+export type ContextHelperFn = () => unknown | null | undefined | Promise<unknown | null | undefined>;
 /**
  * A collection of context helpers keyed by their context name.
  * The key becomes the AdditionalContext.name sent to the model.

package/dist/context-helpers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/context-helpers/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,OAAO,EAAE,GAAG,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAC1B,GAAG,GACH,IAAI,GACJ,SAAS,GACT,OAAO,CAAC,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEpC;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/context-helpers/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAC1B,OAAO,GACP,IAAI,GACJ,SAAS,GACT,OAAO,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAExC;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC"}

package/dist/context-helpers/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/context-helpers/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Interface for additional context that can be added to messages\n */\nexport interface AdditionalContext {\n  /** The name of the context type */\n  name: string;\n  /** The context data */\n  context: any;\n}\n\n/**\n * A context helper is a function that returns data to include in the context,\n * or null/undefined to skip including anything.\n */\nexport type ContextHelperFn = () =>\n  | any\n  | null\n  | undefined\n  | Promise<any | null | undefined>;\n\n/**\n * A collection of context helpers keyed by their context name.\n * The key becomes the AdditionalContext.name sent to the model.\n */\nexport type ContextHelpers = Record<string, ContextHelperFn>;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/context-helpers/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Interface for additional context that can be added to messages\n */\nexport interface AdditionalContext {\n  /** The name of the context type */\n  name: string;\n  /** The context data */\n  context: unknown;\n}\n\n/**\n * A context helper is a function that returns data to include in the context,\n * or null/undefined to skip including anything.\n */\nexport type ContextHelperFn = () =>\n  | unknown\n  | null\n  | undefined\n  | Promise<unknown | null | undefined>;\n\n/**\n * A collection of context helpers keyed by their context name.\n * The key becomes the AdditionalContext.name sent to the model.\n */\nexport type ContextHelpers = Record<string, ContextHelperFn>;\n"]}

package/dist/hoc/with-tambo-interactable.d.ts

@@ -1,14 +1,47 @@
 import React from "react";
 import { SupportedSchema } from "../schema";
-export interface InteractableConfig {
+export interface InteractableConfig<Props = Record<string, unknown>, State = Record<string, unknown>> {
+    /**
+     * The name of the component, used for identification in Tambo.
+     */
     componentName: string;
+    /**
+     * A brief description of the component's purpose and functionality. LLM will
+     * use this to understand how to interact with it.
+     */
     description: string;
-    propsSchema?: SupportedSchema;
+    /**
+     * Optional schema for component props. If provided, prop updates will be
+     * validated against this schema.
+     */
+    propsSchema?: SupportedSchema<Props>;
+    /**
+     * Optional schema for component state. If provided, state updates will be
+     * validated against this schema.
+     */
+    stateSchema?: SupportedSchema<State>;
 }
+/**
+ * Props injected by withTamboInteractable HOC. These can be passed to the wrapped
+ * component to customize interactable behavior.
+ */
 export interface WithTamboInteractableProps {
+    /**
+     * Optional ID to use for this interactable component instance.
+     * If not provided, a unique ID will be generated automatically.
+     */
     interactableId?: string;
+    /**
+     * Callback fired when the component has been registered as interactable.
+     * @param id - The assigned interactable component ID
+     */
     onInteractableReady?: (id: string) => void;
-    onPropsUpdate?: (newProps: Record<string, any>) => void;
+    /**
+     * Callback fired when the component's serializable props are updated by Tambo
+     * through a tool call. Note: Only serializable props are tracked.
+     * @param newProps - The updated serializable props
+     */
+    onPropsUpdate?: (newProps: Record<string, unknown>) => void;
 }
 /**
  * Higher-Order Component that makes any component interactable by tambo.
@@ -17,6 +50,16 @@ export interface WithTamboInteractableProps {
  * @returns A new component that is automatically registered as interactable
  * @example
  * ```tsx
+ * const MyNote: React.FC<{ title: string; content: string }> = ({ title, content }) => {
+ *   const [isPinned, setIsPinned] = useTamboComponentState("isPinned", false);
+ *   return (
+ *     <div style={{ border: isPinned ? "2px solid gold" : "1px solid gray", order: isPinned ? -1 : 0 }}>
+ *       <h2>{title}</h2>
+ *       <p>{content}</p>
+ *     </div>
+ *   );
+ * };
+ *
  * const MyInteractableNote = withTamboInteractable(MyNote, {
  *   componentName: "MyNote",
  *   description: "A note component",
@@ -24,11 +67,14 @@ export interface WithTamboInteractableProps {
  *     title: z.string(),
  *     content: z.string(),
  *   }),
+ *  stateSchema: z.object({
+ *    isPinned: z.boolean(),
+ *  }),
  * });
  *
  * // Usage
  * <MyInteractableNote title="My Note" content="This is my note" />
  * ```
  */
-export declare function withTamboInteractable<P extends object>(WrappedComponent: React.ComponentType<P>, config: InteractableConfig): React.FC<P & WithTamboInteractableProps>;
+export declare function withTamboInteractable<ComponentProps extends object>(WrappedComponent: React.ComponentType<ComponentProps>, config: InteractableConfig): React.FC<ComponentProps & WithTamboInteractableProps>;
 //# sourceMappingURL=with-tambo-interactable.d.ts.map

package/dist/hoc/with-tambo-interactable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"with-tambo-interactable.d.ts","sourceRoot":"","sources":["../../src/hoc/with-tambo-interactable.tsx"],"names":[],"mappings":"AACA,OAAO,KAAmD,MAAM,OAAO,CAAC;AAIxE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA0B;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EACxC,MAAM,EAAE,kBAAkB,4CAgH3B"}
+{"version":3,"file":"with-tambo-interactable.d.ts","sourceRoot":"","sources":["../../src/hoc/with-tambo-interactable.tsx"],"names":[],"mappings":"AACA,OAAO,KAAmD,MAAM,OAAO,CAAC;AAIxE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,kBAAkB,CACjC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE/B;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IACrC;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,SAAS,MAAM,EACjE,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,cAAc,CAAC,EACrD,MAAM,EAAE,kBAAkB,yDAsH3B"}

package/dist/hoc/with-tambo-interactable.js

@@ -45,6 +45,16 @@ const tambo_interactable_provider_1 = require("../providers/tambo-interactable-p
  * @returns A new component that is automatically registered as interactable
  * @example
  * ```tsx
+ * const MyNote: React.FC<{ title: string; content: string }> = ({ title, content }) => {
+ *   const [isPinned, setIsPinned] = useTamboComponentState("isPinned", false);
+ *   return (
+ *     <div style={{ border: isPinned ? "2px solid gold" : "1px solid gray", order: isPinned ? -1 : 0 }}>
+ *       <h2>{title}</h2>
+ *       <p>{content}</p>
+ *     </div>
+ *   );
+ * };
+ *
  * const MyInteractableNote = withTamboInteractable(MyNote, {
  *   componentName: "MyNote",
  *   description: "A note component",
@@ -52,6 +62,9 @@ const tambo_interactable_provider_1 = require("../providers/tambo-interactable-p
  *     title: z.string(),
  *     content: z.string(),
  *   }),
+ *  stateSchema: z.object({
+ *    isPinned: z.boolean(),
+ *  }),
  * });
  *
  * // Usage
@@ -64,9 +77,10 @@ function withTamboInteractable(WrappedComponent, config) {
         const { addInteractableComponent, updateInteractableComponentProps, getInteractableComponent, } = (0, tambo_interactable_provider_1.useTamboInteractable)();
         const [interactableId, setInteractableId] = (0, react_1.useState)(null);
         const isInitialized = (0, react_1.useRef)(false);
-        const lastParentProps = (0, react_1.useRef)({});
-        // Extract interactable-specific props
-        const { onInteractableReady, onPropsUpdate, ...componentProps } = props;
+        const lastSerializedProps = (0, react_1.useRef)({});
+        // Extract interactable-specific props from component props
+        const { interactableId: _providedId, // Reserved for future use
+        onInteractableReady, onPropsUpdate, ...componentProps } = props;
         // Get the current interactable component to track prop updates
         const currentInteractable = interactableId
             ? getInteractableComponent(interactableId)
@@ -83,6 +97,7 @@ function withTamboInteractable(WrappedComponent, config) {
                     component: WrappedComponent,
                     props: componentProps,
                     propsSchema: config.propsSchema,
+                    stateSchema: config.stateSchema,
                 });
                 setInteractableId(id);
                 onInteractableReady?.(id);
@@ -97,12 +112,12 @@ function withTamboInteractable(WrappedComponent, config) {
         (0, react_1.useEffect)(() => {
             if (interactableId && isInitialized.current) {
                 // Only update if the props are different from what we last sent
-                const lastPropsString = JSON.stringify(lastParentProps.current);
+                const lastPropsString = JSON.stringify(lastSerializedProps.current);
                 const currentPropsString = JSON.stringify(componentProps);
                 if (lastPropsString !== currentPropsString) {
                     updateInteractableComponentProps(interactableId, componentProps);
                     onPropsUpdate?.(componentProps);
-                    lastParentProps.current = componentProps;
+                    lastSerializedProps.current = componentProps;
                 }
             }
         }, [

package/dist/hoc/with-tambo-interactable.js.map

@@ -1 +1 @@
-{"version":3,"file":"with-tambo-interactable.js","sourceRoot":"","sources":["../../src/hoc/with-tambo-interactable.tsx"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\nimport React, { useCallback, useEffect, useRef, useState } from \"react\";\nimport { TamboMessageProvider } from \"../hooks/use-current-message\";\nimport { TamboThreadMessage } from \"../model/generate-component-response\";\nimport { useTamboInteractable } from \"../providers/tambo-interactable-provider\";\nimport { SupportedSchema } from \"../schema\";\n\nexport interface InteractableConfig {\n  componentName: string;\n  description: string;\n  propsSchema?: SupportedSchema;\n}\n\nexport interface WithTamboInteractableProps {\n  interactableId?: string;\n  onInteractableReady?: (id: string) => void;\n  onPropsUpdate?: (newProps: Record<string, any>) => void;\n}\n\n/**\n * Higher-Order Component that makes any component interactable by tambo.\n * @param WrappedComponent - The component to make interactable\n * @param config - Configuration for the interactable component\n * @returns A new component that is automatically registered as interactable\n * @example\n * ```tsx\n * const MyInteractableNote = withTamboInteractable(MyNote, {\n *   componentName: \"MyNote\",\n *   description: \"A note component\",\n *   propsSchema: z.object({\n *     title: z.string(),\n *     content: z.string(),\n *   }),\n * });\n *\n * // Usage\n * <MyInteractableNote title=\"My Note\" content=\"This is my note\" />\n * ```\n */\nexport function withTamboInteractable<P extends object>(\n  WrappedComponent: React.ComponentType<P>,\n  config: InteractableConfig,\n) {\n  const displayName =\n    WrappedComponent.displayName ?? WrappedComponent.name ?? \"Component\";\n\n  const TamboInteractableWrapper: React.FC<P & WithTamboInteractableProps> = (\n    props,\n  ) => {\n    const {\n      addInteractableComponent,\n      updateInteractableComponentProps,\n      getInteractableComponent,\n    } = useTamboInteractable();\n\n    const [interactableId, setInteractableId] = useState<string | null>(null);\n    const isInitialized = useRef(false);\n    const lastParentProps = useRef<Record<string, any>>({});\n\n    // Extract interactable-specific props\n    const { onInteractableReady, onPropsUpdate, ...componentProps } = props;\n\n    // Get the current interactable component to track prop updates\n    const currentInteractable = interactableId\n      ? getInteractableComponent(interactableId)\n      : null;\n\n    // Use the props from the interactable component if available, otherwise use the passed props\n    // We need to be careful not to create a loop, so we only use stored props if they're different from passed props\n    const effectiveProps = currentInteractable?.props ?? componentProps;\n\n    // Memoize the registration function\n    const registerComponent = useCallback(() => {\n      if (!isInitialized.current) {\n        const id = addInteractableComponent({\n          name: config.componentName,\n          description: config.description,\n          component: WrappedComponent,\n          props: componentProps,\n          propsSchema: config.propsSchema,\n        });\n\n        setInteractableId(id);\n        onInteractableReady?.(id);\n        isInitialized.current = true;\n      }\n    }, [addInteractableComponent, componentProps, onInteractableReady]);\n\n    // Register the component as interactable on mount (only once)\n    useEffect(() => {\n      registerComponent();\n    }, [registerComponent]);\n\n    // Update the interactable component when props change from parent\n    useEffect(() => {\n      if (interactableId && isInitialized.current) {\n        // Only update if the props are different from what we last sent\n        const lastPropsString = JSON.stringify(lastParentProps.current);\n        const currentPropsString = JSON.stringify(componentProps);\n\n        if (lastPropsString !== currentPropsString) {\n          updateInteractableComponentProps(interactableId, componentProps);\n          onPropsUpdate?.(componentProps);\n          lastParentProps.current = componentProps;\n        }\n      }\n    }, [\n      interactableId,\n      componentProps,\n      updateInteractableComponentProps,\n      onPropsUpdate,\n    ]);\n\n    // If the interactable ID is not yet set, render the component without provider\n    if (!interactableId) {\n      return <WrappedComponent {...(effectiveProps as P)} />;\n    }\n\n    // Create a minimal message with interactable metadata\n    // This allows useTamboCurrentComponent to work with standalone interactable components\n    const minimalMessage: TamboThreadMessage = {\n      id: interactableId,\n      role: \"assistant\" as const,\n      content: [],\n      threadId: \"\",\n      createdAt: new Date().toISOString(),\n      component: {\n        componentName: config.componentName,\n        componentState: {},\n        message: \"\",\n        props: effectiveProps,\n      },\n      componentState: {},\n    };\n\n    // Wrap with TamboMessageProvider including interactable metadata\n    return (\n      <TamboMessageProvider\n        message={minimalMessage}\n        interactableMetadata={{\n          id: interactableId,\n          componentName: config.componentName,\n          description: config.description,\n        }}\n      >\n        <WrappedComponent {...(effectiveProps as P)} />\n      </TamboMessageProvider>\n    );\n  };\n\n  TamboInteractableWrapper.displayName = `withTamboInteractable(${displayName})`;\n\n  return TamboInteractableWrapper;\n}\n"]}
+{"version":3,"file":"with-tambo-interactable.js","sourceRoot":"","sources":["../../src/hoc/with-tambo-interactable.tsx"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\nimport React, { useCallback, useEffect, useRef, useState } from \"react\";\nimport { TamboMessageProvider } from \"../hooks/use-current-message\";\nimport { TamboThreadMessage } from \"../model/generate-component-response\";\nimport { useTamboInteractable } from \"../providers/tambo-interactable-provider\";\nimport { SupportedSchema } from \"../schema\";\n\nexport interface InteractableConfig<\n  Props = Record<string, unknown>,\n  State = Record<string, unknown>,\n> {\n  /**\n   * The name of the component, used for identification in Tambo.\n   */\n  componentName: string;\n  /**\n   * A brief description of the component's purpose and functionality. LLM will\n   * use this to understand how to interact with it.\n   */\n  description: string;\n  /**\n   * Optional schema for component props. If provided, prop updates will be\n   * validated against this schema.\n   */\n  propsSchema?: SupportedSchema<Props>;\n  /**\n   * Optional schema for component state. If provided, state updates will be\n   * validated against this schema.\n   */\n  stateSchema?: SupportedSchema<State>;\n}\n\n/**\n * Props injected by withTamboInteractable HOC. These can be passed to the wrapped\n * component to customize interactable behavior.\n */\nexport interface WithTamboInteractableProps {\n  /**\n   * Optional ID to use for this interactable component instance.\n   * If not provided, a unique ID will be generated automatically.\n   */\n  interactableId?: string;\n  /**\n   * Callback fired when the component has been registered as interactable.\n   * @param id - The assigned interactable component ID\n   */\n  onInteractableReady?: (id: string) => void;\n  /**\n   * Callback fired when the component's serializable props are updated by Tambo\n   * through a tool call. Note: Only serializable props are tracked.\n   * @param newProps - The updated serializable props\n   */\n  onPropsUpdate?: (newProps: Record<string, unknown>) => void;\n}\n\n/**\n * Higher-Order Component that makes any component interactable by tambo.\n * @param WrappedComponent - The component to make interactable\n * @param config - Configuration for the interactable component\n * @returns A new component that is automatically registered as interactable\n * @example\n * ```tsx\n * const MyNote: React.FC<{ title: string; content: string }> = ({ title, content }) => {\n *   const [isPinned, setIsPinned] = useTamboComponentState(\"isPinned\", false);\n *   return (\n *     <div style={{ border: isPinned ? \"2px solid gold\" : \"1px solid gray\", order: isPinned ? -1 : 0 }}>\n *       <h2>{title}</h2>\n *       <p>{content}</p>\n *     </div>\n *   );\n * };\n *\n * const MyInteractableNote = withTamboInteractable(MyNote, {\n *   componentName: \"MyNote\",\n *   description: \"A note component\",\n *   propsSchema: z.object({\n *     title: z.string(),\n *     content: z.string(),\n *   }),\n *  stateSchema: z.object({\n *    isPinned: z.boolean(),\n *  }),\n * });\n *\n * // Usage\n * <MyInteractableNote title=\"My Note\" content=\"This is my note\" />\n * ```\n */\nexport function withTamboInteractable<ComponentProps extends object>(\n  WrappedComponent: React.ComponentType<ComponentProps>,\n  config: InteractableConfig,\n) {\n  const displayName =\n    WrappedComponent.displayName ?? WrappedComponent.name ?? \"Component\";\n\n  const TamboInteractableWrapper: React.FC<\n    ComponentProps & WithTamboInteractableProps\n  > = (props) => {\n    const {\n      addInteractableComponent,\n      updateInteractableComponentProps,\n      getInteractableComponent,\n    } = useTamboInteractable();\n\n    const [interactableId, setInteractableId] = useState<string | null>(null);\n    const isInitialized = useRef(false);\n    const lastSerializedProps = useRef<Record<string, unknown>>({});\n\n    // Extract interactable-specific props from component props\n    const {\n      interactableId: _providedId, // Reserved for future use\n      onInteractableReady,\n      onPropsUpdate,\n      ...componentProps\n    } = props;\n\n    // Get the current interactable component to track prop updates\n    const currentInteractable = interactableId\n      ? getInteractableComponent(interactableId)\n      : null;\n\n    // Use the props from the interactable component if available, otherwise use the passed props\n    // We need to be careful not to create a loop, so we only use stored props if they're different from passed props\n    const effectiveProps = currentInteractable?.props ?? componentProps;\n\n    // Memoize the registration function\n    const registerComponent = useCallback(() => {\n      if (!isInitialized.current) {\n        const id = addInteractableComponent({\n          name: config.componentName,\n          description: config.description,\n          component: WrappedComponent,\n          props: componentProps,\n          propsSchema: config.propsSchema,\n          stateSchema: config.stateSchema,\n        });\n\n        setInteractableId(id);\n        onInteractableReady?.(id);\n        isInitialized.current = true;\n      }\n    }, [addInteractableComponent, componentProps, onInteractableReady]);\n\n    // Register the component as interactable on mount (only once)\n    useEffect(() => {\n      registerComponent();\n    }, [registerComponent]);\n\n    // Update the interactable component when props change from parent\n    useEffect(() => {\n      if (interactableId && isInitialized.current) {\n        // Only update if the props are different from what we last sent\n        const lastPropsString = JSON.stringify(lastSerializedProps.current);\n        const currentPropsString = JSON.stringify(componentProps);\n\n        if (lastPropsString !== currentPropsString) {\n          updateInteractableComponentProps(interactableId, componentProps);\n          onPropsUpdate?.(componentProps);\n          lastSerializedProps.current = componentProps;\n        }\n      }\n    }, [\n      interactableId,\n      componentProps,\n      updateInteractableComponentProps,\n      onPropsUpdate,\n    ]);\n\n    // If the interactable ID is not yet set, render the component without provider\n    if (!interactableId) {\n      return <WrappedComponent {...(effectiveProps as ComponentProps)} />;\n    }\n\n    // Create a minimal message with interactable metadata\n    // This allows useTamboCurrentComponent to work with standalone interactable components\n    const minimalMessage: TamboThreadMessage = {\n      id: interactableId,\n      role: \"assistant\" as const,\n      content: [],\n      threadId: \"\",\n      createdAt: new Date().toISOString(),\n      component: {\n        componentName: config.componentName,\n        componentState: {},\n        message: \"\",\n        props: effectiveProps,\n      },\n      componentState: {},\n    };\n\n    // Wrap with TamboMessageProvider including interactable metadata\n    return (\n      <TamboMessageProvider\n        message={minimalMessage}\n        interactableMetadata={{\n          id: interactableId,\n          componentName: config.componentName,\n          description: config.description,\n        }}\n      >\n        <WrappedComponent {...(effectiveProps as ComponentProps)} />\n      </TamboMessageProvider>\n    );\n  };\n\n  TamboInteractableWrapper.displayName = `withTamboInteractable(${displayName})`;\n\n  return TamboInteractableWrapper;\n}\n"]}

package/dist/hooks/use-component-state.d.ts

@@ -11,11 +11,11 @@ type StateUpdateResult<T> = [currentState: T, setState: (newState: T) => void];
  * @param initialValue - Optional initial value for the state, used if no componentState value exists in the Tambo message containing this hook usage.
  * @param setFromProp - Optional value used to set the state value, only while no componentState value exists in the Tambo message containing this hook usage. Use this to allow streaming updates from a prop to the state value.
  * @param debounceTime - Optional debounce time in milliseconds (default: 500ms) to limit API calls.
- * @returns A tuple containing:
- *   - The current state value
- *   - A setter function to update the state (updates UI immediately, debounces server sync)
+ * @returns A tuple of [currentState, setState] similar to React's useState
  * @example
+ * ```tsx
  * const [count, setCount] = useTamboComponentState("counter", 0);
+ * ```
  *
  * Use `setFromProp` to seed state from streamed props. During streaming,
  * state updates as new prop values arrive. Once streaming completes,
@@ -23,11 +23,6 @@ type StateUpdateResult<T> = [currentState: T, setState: (newState: T) => void];
  *
  * Pair with `useTamboStreamStatus` to disable inputs while streaming.
  * @see {@link https://docs.tambo.co/concepts/streaming/streaming-best-practices}
- * @param keyName - Unique key within the message's componentState
- * @param initialValue - Default value if no componentState exists
- * @param setFromProp - Seeds state from props (updates during streaming, then user edits take over)
- * @param debounceTime - Server sync debounce in ms (default: 500)
- * @returns A tuple of [currentState, setState] similar to React's useState
  */
 export declare function useTamboComponentState<S = undefined>(keyName: string, initialValue?: S, setFromProp?: S, debounceTime?: number): StateUpdateResult<S | undefined>;
 export declare function useTamboComponentState<S>(keyName: string, initialValue: S, setFromProp?: S, debounceTime?: number): StateUpdateResult<S>;

package/dist/hooks/use-component-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-component-state.d.ts","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"AAOA,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,SAAS,EAClD,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,CAAC,EAChB,WAAW,CAAC,EAAE,CAAC,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,iBAAiB,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AACpC,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,EACf,WAAW,CAAC,EAAE,CAAC,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,iBAAiB,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"use-component-state.d.ts","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"AAQA,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,SAAS,EAClD,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,CAAC,EAChB,WAAW,CAAC,EAAE,CAAC,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,iBAAiB,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AACpC,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,EACf,WAAW,CAAC,EAAE,CAAC,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,iBAAiB,CAAC,CAAC,CAAC,CAAC"}

package/dist/hooks/use-component-state.js

@@ -2,6 +2,7 @@
 "use client";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useTamboComponentState = useTamboComponentState;
+const fast_equals_1 = require("fast-equals");
 const react_1 = require("react");
 const use_debounce_1 = require("use-debounce");
 const __1 = require("..");
@@ -101,6 +102,13 @@ function useTamboComponentState(keyName, initialValue, setFromProp, debounceTime
         setInteractableState,
         componentId,
     ]);
+    // Sync from interactable provider to local state when state changes externally (e.g., from Tambo tool call)
+    (0, react_1.useEffect)(() => {
+        if (!componentId)
+            return;
+        // only update if different
+        setLocalState((prev) => (0, fast_equals_1.deepEqual)(prev, interactableState) ? prev : interactableState);
+    }, [componentId, interactableState]);
     // For editable fields that are set from a prop to allow streaming updates, don't overwrite a fetched state value set from the thread message with prop value on initial load.
     (0, react_1.useEffect)(() => {
         if (setFromProp !== undefined && !initializedFromThreadMessage) {

package/dist/hooks/use-component-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-component-state.js","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\nimport { useCallback, useContext, useEffect, useState } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { TamboThreadMessage, useTamboClient, useTamboThread } from \"..\";\nimport { useTamboInteractable } from \"../providers/tambo-interactable-provider\";\nimport { TamboMessageContext } from \"./use-current-message\";\n\ntype StateUpdateResult<T> = [currentState: T, setState: (newState: T) => void];\n\n/**\n * A React hook that acts like useState, but also automatically updates the thread message's componentState.\n * If used within an interactable component (wrapped with withTamboInteractable), it updates the\n * interactable provider's global state (sent to Tambo on every request) instead of the remote thread message state.\n * For generated components, it updates both the local and remote thread message's componentState.\n *\n * Benefits: Passes user changes to AI, and when threads are returned, state is preserved.\n * Works in both generative and interactable component contexts.\n * @param keyName - The unique key to identify this state value within the message's componentState object\n * @param initialValue - Optional initial value for the state, used if no componentState value exists in the Tambo message containing this hook usage.\n * @param setFromProp - Optional value used to set the state value, only while no componentState value exists in the Tambo message containing this hook usage. Use this to allow streaming updates from a prop to the state value.\n * @param debounceTime - Optional debounce time in milliseconds (default: 500ms) to limit API calls.\n * @returns A tuple containing:\n *   - The current state value\n *   - A setter function to update the state (updates UI immediately, debounces server sync)\n * @example\n * const [count, setCount] = useTamboComponentState(\"counter\", 0);\n *\n * Use `setFromProp` to seed state from streamed props. During streaming,\n * state updates as new prop values arrive. Once streaming completes,\n * user edits take precedence over the original prop value.\n *\n * Pair with `useTamboStreamStatus` to disable inputs while streaming.\n * @see {@link https://docs.tambo.co/concepts/streaming/streaming-best-practices}\n * @param keyName - Unique key within the message's componentState\n * @param initialValue - Default value if no componentState exists\n * @param setFromProp - Seeds state from props (updates during streaming, then user edits take over)\n * @param debounceTime - Server sync debounce in ms (default: 500)\n * @returns A tuple of [currentState, setState] similar to React's useState\n */\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  setFromProp?: S,\n  debounceTime?: number,\n): StateUpdateResult<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  setFromProp?: S,\n  debounceTime?: number,\n): StateUpdateResult<S>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  setFromProp?: S,\n  debounceTime = 500,\n): StateUpdateResult<S> {\n  const message = useContext(TamboMessageContext);\n  const { updateThreadMessage } = useTamboThread();\n  const client = useTamboClient();\n  const componentId = message?.interactableMetadata?.id ?? null;\n  const { setInteractableState, getInteractableComponentState } =\n    useTamboInteractable();\n  const messageState = message?.componentState?.[keyName];\n  const interactableState = componentId\n    ? getInteractableComponentState(componentId)?.[keyName]\n    : undefined;\n  const initialState =\n    (interactableState as S) ?? (messageState as S) ?? initialValue;\n  const [localState, setLocalState] = useState<S | undefined>(initialState);\n  const [initializedFromThreadMessage, setInitializedFromThreadMessage] =\n    useState(messageState ? true : false);\n\n  // Optimistically update the local thread message's componentState\n  const updateLocalThreadMessage = useCallback(\n    async (newState: S, existingMessage: TamboThreadMessage | null) => {\n      if (!existingMessage) {\n        return;\n      }\n      const updatedMessage = {\n        threadId: existingMessage.threadId,\n        componentState: {\n          ...existingMessage.componentState,\n          [keyName]: newState,\n        },\n      };\n      await updateThreadMessage(existingMessage.id, updatedMessage, false);\n    },\n    [updateThreadMessage, keyName],\n  );\n\n  // Debounced callback to update the remote thread message's componentState\n  const updateRemoteThreadMessage = useDebouncedCallback(\n    async (newState: S, existingMessage: TamboThreadMessage | null) => {\n      if (!existingMessage) {\n        return;\n      }\n      await client.beta.threads.messages.updateComponentState(\n        existingMessage.id,\n        {\n          id: existingMessage.threadId,\n          state: { [keyName]: newState },\n        },\n      );\n    },\n    debounceTime,\n  );\n\n  const setValue = useCallback(\n    (newState: S) => {\n      setLocalState(newState);\n      if (componentId) {\n        // For interactable components, update the interactable provider's state\n        setInteractableState(componentId, keyName, newState);\n      } else if (message) {\n        // For generated components, update both local and remote thread message state\n        void updateLocalThreadMessage(newState, message);\n        void updateRemoteThreadMessage(newState, message);\n      }\n    },\n    [\n      message,\n      updateLocalThreadMessage,\n      updateRemoteThreadMessage,\n      setInteractableState,\n      componentId,\n      keyName,\n    ],\n  );\n\n  const existingInteractableState = componentId\n    ? getInteractableComponentState(componentId)?.[keyName]\n    : undefined;\n  const shouldUpdateInteractableInitial =\n    !!componentId &&\n    existingInteractableState === undefined &&\n    initialValue !== undefined;\n\n  // Set initial value in interactable state if we're in an interactable context and there's no existing state\n  useEffect(() => {\n    if (!shouldUpdateInteractableInitial) {\n      return;\n    }\n    setInteractableState(componentId, keyName, initialValue!);\n  }, [\n    shouldUpdateInteractableInitial,\n    componentId,\n    keyName,\n    initialValue,\n    setInteractableState,\n  ]);\n\n  const shouldSyncFromMessage =\n    !!message && messageState !== undefined && messageState !== null;\n\n  // Mirror the thread message's componentState value to the local state and interactable state\n  useEffect(() => {\n    if (!shouldSyncFromMessage) {\n      return;\n    }\n    setInitializedFromThreadMessage(true);\n    const stateValue = messageState as S;\n    setLocalState(stateValue);\n    if (componentId) {\n      setInteractableState(componentId, keyName, stateValue);\n    }\n  }, [\n    shouldSyncFromMessage,\n    messageState,\n    keyName,\n    setInteractableState,\n    componentId,\n  ]);\n\n  // For editable fields that are set from a prop to allow streaming updates, don't overwrite a fetched state value set from the thread message with prop value on initial load.\n  useEffect(() => {\n    if (setFromProp !== undefined && !initializedFromThreadMessage) {\n      setLocalState(setFromProp as S);\n    }\n  }, [setFromProp, initializedFromThreadMessage]);\n\n  // Ensure pending changes are flushed on unmount (only for generated components)\n  useEffect(() => {\n    // Only flush remote updates for generated components, not interactable components\n    if (componentId) {\n      return;\n    }\n    return () => {\n      async function flushUpdates() {\n        try {\n          await updateRemoteThreadMessage.flush();\n        } catch (error) {\n          console.error(\n            \"Failed to flush pending thread message updates:\",\n            error,\n          );\n        }\n      }\n      // Fire-and-forget cleanup (errors handled inside)\n      void flushUpdates();\n    };\n  }, [updateRemoteThreadMessage, componentId]);\n\n  return [localState as S, setValue];\n}\n"]}
+{"version":3,"file":"use-component-state.js","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\nimport { deepEqual } from \"fast-equals\";\nimport { useCallback, useContext, useEffect, useState } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { TamboThreadMessage, useTamboClient, useTamboThread } from \"..\";\nimport { useTamboInteractable } from \"../providers/tambo-interactable-provider\";\nimport { TamboMessageContext } from \"./use-current-message\";\n\ntype StateUpdateResult<T> = [currentState: T, setState: (newState: T) => void];\n\n/**\n * A React hook that acts like useState, but also automatically updates the thread message's componentState.\n * If used within an interactable component (wrapped with withTamboInteractable), it updates the\n * interactable provider's global state (sent to Tambo on every request) instead of the remote thread message state.\n * For generated components, it updates both the local and remote thread message's componentState.\n *\n * Benefits: Passes user changes to AI, and when threads are returned, state is preserved.\n * Works in both generative and interactable component contexts.\n * @param keyName - The unique key to identify this state value within the message's componentState object\n * @param initialValue - Optional initial value for the state, used if no componentState value exists in the Tambo message containing this hook usage.\n * @param setFromProp - Optional value used to set the state value, only while no componentState value exists in the Tambo message containing this hook usage. Use this to allow streaming updates from a prop to the state value.\n * @param debounceTime - Optional debounce time in milliseconds (default: 500ms) to limit API calls.\n * @returns A tuple of [currentState, setState] similar to React's useState\n * @example\n * ```tsx\n * const [count, setCount] = useTamboComponentState(\"counter\", 0);\n * ```\n *\n * Use `setFromProp` to seed state from streamed props. During streaming,\n * state updates as new prop values arrive. Once streaming completes,\n * user edits take precedence over the original prop value.\n *\n * Pair with `useTamboStreamStatus` to disable inputs while streaming.\n * @see {@link https://docs.tambo.co/concepts/streaming/streaming-best-practices}\n */\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  setFromProp?: S,\n  debounceTime?: number,\n): StateUpdateResult<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  setFromProp?: S,\n  debounceTime?: number,\n): StateUpdateResult<S>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  setFromProp?: S,\n  debounceTime = 500,\n): StateUpdateResult<S> {\n  const message = useContext(TamboMessageContext);\n  const { updateThreadMessage } = useTamboThread();\n  const client = useTamboClient();\n  const componentId = message?.interactableMetadata?.id ?? null;\n  const { setInteractableState, getInteractableComponentState } =\n    useTamboInteractable();\n  const messageState = message?.componentState?.[keyName];\n  const interactableState = componentId\n    ? getInteractableComponentState(componentId)?.[keyName]\n    : undefined;\n  const initialState =\n    (interactableState as S) ?? (messageState as S) ?? initialValue;\n  const [localState, setLocalState] = useState<S | undefined>(initialState);\n  const [initializedFromThreadMessage, setInitializedFromThreadMessage] =\n    useState(messageState ? true : false);\n\n  // Optimistically update the local thread message's componentState\n  const updateLocalThreadMessage = useCallback(\n    async (newState: S, existingMessage: TamboThreadMessage | null) => {\n      if (!existingMessage) {\n        return;\n      }\n      const updatedMessage = {\n        threadId: existingMessage.threadId,\n        componentState: {\n          ...existingMessage.componentState,\n          [keyName]: newState,\n        },\n      };\n      await updateThreadMessage(existingMessage.id, updatedMessage, false);\n    },\n    [updateThreadMessage, keyName],\n  );\n\n  // Debounced callback to update the remote thread message's componentState\n  const updateRemoteThreadMessage = useDebouncedCallback(\n    async (newState: S, existingMessage: TamboThreadMessage | null) => {\n      if (!existingMessage) {\n        return;\n      }\n      await client.beta.threads.messages.updateComponentState(\n        existingMessage.id,\n        {\n          id: existingMessage.threadId,\n          state: { [keyName]: newState },\n        },\n      );\n    },\n    debounceTime,\n  );\n\n  const setValue = useCallback(\n    (newState: S) => {\n      setLocalState(newState);\n      if (componentId) {\n        // For interactable components, update the interactable provider's state\n        setInteractableState(componentId, keyName, newState);\n      } else if (message) {\n        // For generated components, update both local and remote thread message state\n        void updateLocalThreadMessage(newState, message);\n        void updateRemoteThreadMessage(newState, message);\n      }\n    },\n    [\n      message,\n      updateLocalThreadMessage,\n      updateRemoteThreadMessage,\n      setInteractableState,\n      componentId,\n      keyName,\n    ],\n  );\n\n  const existingInteractableState = componentId\n    ? getInteractableComponentState(componentId)?.[keyName]\n    : undefined;\n  const shouldUpdateInteractableInitial =\n    !!componentId &&\n    existingInteractableState === undefined &&\n    initialValue !== undefined;\n\n  // Set initial value in interactable state if we're in an interactable context and there's no existing state\n  useEffect(() => {\n    if (!shouldUpdateInteractableInitial) {\n      return;\n    }\n    setInteractableState(componentId, keyName, initialValue!);\n  }, [\n    shouldUpdateInteractableInitial,\n    componentId,\n    keyName,\n    initialValue,\n    setInteractableState,\n  ]);\n\n  const shouldSyncFromMessage =\n    !!message && messageState !== undefined && messageState !== null;\n\n  // Mirror the thread message's componentState value to the local state and interactable state\n  useEffect(() => {\n    if (!shouldSyncFromMessage) {\n      return;\n    }\n    setInitializedFromThreadMessage(true);\n    const stateValue = messageState as S;\n    setLocalState(stateValue);\n    if (componentId) {\n      setInteractableState(componentId, keyName, stateValue);\n    }\n  }, [\n    shouldSyncFromMessage,\n    messageState,\n    keyName,\n    setInteractableState,\n    componentId,\n  ]);\n\n  // Sync from interactable provider to local state when state changes externally (e.g., from Tambo tool call)\n  useEffect(() => {\n    if (!componentId) return;\n    // only update if different\n    setLocalState((prev) =>\n      deepEqual(prev, interactableState) ? prev : (interactableState as S),\n    );\n  }, [componentId, interactableState]);\n\n  // For editable fields that are set from a prop to allow streaming updates, don't overwrite a fetched state value set from the thread message with prop value on initial load.\n  useEffect(() => {\n    if (setFromProp !== undefined && !initializedFromThreadMessage) {\n      setLocalState(setFromProp as S);\n    }\n  }, [setFromProp, initializedFromThreadMessage]);\n\n  // Ensure pending changes are flushed on unmount (only for generated components)\n  useEffect(() => {\n    // Only flush remote updates for generated components, not interactable components\n    if (componentId) {\n      return;\n    }\n    return () => {\n      async function flushUpdates() {\n        try {\n          await updateRemoteThreadMessage.flush();\n        } catch (error) {\n          console.error(\n            \"Failed to flush pending thread message updates:\",\n            error,\n          );\n        }\n      }\n      // Fire-and-forget cleanup (errors handled inside)\n      void flushUpdates();\n    };\n  }, [updateRemoteThreadMessage, componentId]);\n\n  return [localState as S, setValue];\n}\n"]}