@tambo-ai/react 0.75.0 → 1.0.0-rc.4

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

@@ -1,8 +1,8 @@
 /**
- * Return type for useTamboV1ComponentState hook.
+ * Return type for useTamboComponentState hook.
  * Similar to useState but with additional metadata.
  */
-export type UseTamboV1ComponentStateReturn<S> = [
+export type UseTamboComponentStateReturn<S> = [
     currentState: S,
     setState: (newState: S | ((prev: S) => S)) => void,
     meta: {
@@ -18,7 +18,8 @@ export type UseTamboV1ComponentStateReturn<S> = [
  * to the Tambo backend. Server-side state updates are also reflected
  * in the component.
  *
- * Must be used within a component rendered via the component renderer.
+ * Can be used within rendered components, interactable components, or
+ * components awaiting provider context (acts as plain useState until context is available).
  * @param keyName - The unique key to identify this state value within the component's state
  * @param initialValue - Initial value for the state (used if no server state exists)
  * @param debounceTime - Debounce time in milliseconds (default: 500ms)
@@ -26,7 +27,7 @@ export type UseTamboV1ComponentStateReturn<S> = [
  * @example
  * ```tsx
  * function Counter() {
- *   const [count, setCount, { isPending }] = useTamboV1ComponentState('count', 0);
+ *   const [count, setCount, { isPending }] = useTamboComponentState('count', 0);
  *
  *   return (
  *     <div>
@@ -39,6 +40,6 @@ export type UseTamboV1ComponentStateReturn<S> = [
  * }
  * ```
  */
-export declare function useTamboV1ComponentState<S = undefined>(keyName: string, initialValue?: S, debounceTime?: number): UseTamboV1ComponentStateReturn<S | undefined>;
-export declare function useTamboV1ComponentState<S>(keyName: string, initialValue: S, debounceTime?: number): UseTamboV1ComponentStateReturn<S>;
+export declare function useTamboComponentState<S = undefined>(keyName: string, initialValue?: S, debounceTime?: number): UseTamboComponentStateReturn<S | undefined>;
+export declare function useTamboComponentState<S>(keyName: string, initialValue: S, debounceTime?: number): UseTamboComponentStateReturn<S>;
 //# sourceMappingURL=use-tambo-v1-component-state.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-tambo-v1-component-state.d.ts","sourceRoot":"","sources":["../../../src/v1/hooks/use-tambo-v1-component-state.ts"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,MAAM,MAAM,8BAA8B,CAAC,CAAC,IAAI;IAC9C,YAAY,EAAE,CAAC;IACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI;IAClD,IAAI,EAAE;QACJ,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,KAAK,EAAE,MAAM,IAAI,CAAC;KACnB;CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,SAAS,EACpD,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,CAAC,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,8BAA8B,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AACjD,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,8BAA8B,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"use-tambo-v1-component-state.d.ts","sourceRoot":"","sources":["../../../src/v1/hooks/use-tambo-v1-component-state.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,MAAM,MAAM,4BAA4B,CAAC,CAAC,IAAI;IAC5C,YAAY,EAAE,CAAC;IACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI;IAClD,IAAI,EAAE;QACJ,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,KAAK,EAAE,MAAM,IAAI,CAAC;KACnB;CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,SAAS,EAClD,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,CAAC,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,4BAA4B,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAC/C,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,4BAA4B,CAAC,CAAC,CAAC,CAAC"}

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

@@ -1,15 +1,19 @@
 "use strict";
 "use client";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useTamboV1ComponentState = useTamboV1ComponentState;
+exports.useTamboComponentState = useTamboComponentState;
 /**
- * useTamboV1ComponentState - Component State Hook for v1 API
+ * useTamboComponentState - Component State Hook
  *
  * Provides bidirectional state synchronization between React components
  * and the Tambo backend. State changes are debounced before syncing to
  * the server, and server state updates are reflected in the component.
  *
- * Must be used within a component rendered via the component renderer.
+ * Works in three modes:
+ * - **Rendered components**: syncs state bidirectionally with the server
+ * - **Interactable components**: syncs state via the interactable provider
+ * - **No context yet**: acts as plain useState (no side effects) until a
+ *   provider wraps the component (e.g., first render before withTamboInteractable)
  */
 const react_1 = require("react");
 const use_debounce_1 = require("use-debounce");
@@ -17,20 +21,30 @@ const fast_equals_1 = require("fast-equals");
 const tambo_client_provider_1 = require("../../providers/tambo-client-provider");
 const tambo_interactable_provider_1 = require("../../providers/tambo-interactable-provider");
 const component_renderer_1 = require("../utils/component-renderer");
+const tambo_v1_provider_1 = require("../providers/tambo-v1-provider");
 const tambo_v1_stream_context_1 = require("../providers/tambo-v1-stream-context");
 const thread_utils_1 = require("../utils/thread-utils");
-function useTamboV1ComponentState(keyName, initialValue, debounceTime = 500) {
+function useTamboComponentState(keyName, initialValue, debounceTime = 500) {
     const client = (0, tambo_client_provider_1.useTamboClient)();
-    const { componentId, threadId } = (0, component_renderer_1.useV1ComponentContent)();
+    const { userKey } = (0, tambo_v1_provider_1.useTamboConfig)();
+    const componentContent = (0, component_renderer_1.useComponentContentOptional)();
     const streamState = (0, tambo_v1_stream_context_1.useStreamState)();
     const { setInteractableState, getInteractableComponentState } = (0, tambo_interactable_provider_1.useTamboInteractable)();
-    // Interactable components use threadId="" (set by withTamboInteractable)
-    const isInteractable = threadId === "";
-    // Find the component content to get server state (only for v1-rendered components)
-    const componentContent = isInteractable
+    // componentContent is null on the first render of interactable components
+    // (before withTamboInteractable sets the interactableId and wraps with provider).
+    // When null, we act as plain useState with no side effects.
+    const isContextAvailable = componentContent !== null;
+    const componentId = componentContent?.componentId ?? "";
+    const threadId = componentContent?.threadId ?? "";
+    // Only treat as interactable when we have real context with threadId=""
+    // (set by withTamboInteractable). When context is missing entirely,
+    // neither interactable nor server-sync paths should run.
+    const isInteractable = isContextAvailable && threadId === "";
+    // Find the component content to get server state (only for rendered components)
+    const renderedContent = isInteractable
         ? undefined
         : (0, thread_utils_1.findComponentContent)(streamState, threadId, componentId);
-    const serverState = componentContent?.state;
+    const serverState = renderedContent?.state;
     const serverValue = serverState?.[keyName];
     // For interactable components, read state from the interactable provider
     const interactableState = isInteractable
@@ -47,9 +61,9 @@ function useTamboV1ComponentState(keyName, initialValue, debounceTime = 500) {
     const hasPendingLocalChangeRef = (0, react_1.useRef)(false);
     // Track in-flight sync requests to avoid stale completions clearing pending state
     const syncSeqRef = (0, react_1.useRef)(0);
-    // Debounced function to sync state to server (only used for v1-rendered components)
+    // Debounced function to sync state to server (only used for rendered components)
     const syncToServer = (0, use_debounce_1.useDebouncedCallback)(async (newState) => {
-        if (isInteractable)
+        if (!isContextAvailable || isInteractable)
             return;
         const seq = ++syncSeqRef.current;
         setIsPending(true);
@@ -59,6 +73,7 @@ function useTamboV1ComponentState(keyName, initialValue, debounceTime = 500) {
             await client.threads.state.updateState(componentId, {
                 threadId,
                 state: { [keyName]: newState },
+                userKey,
             });
             // Clear pending flag after successful sync
             hasPendingLocalChangeRef.current = false;
@@ -68,7 +83,7 @@ function useTamboV1ComponentState(keyName, initialValue, debounceTime = 500) {
             hasPendingLocalChangeRef.current = false;
             const syncError = err instanceof Error ? err : new Error(String(err));
             setError(syncError);
-            console.error(`[useTamboV1ComponentState] Failed to sync state for ${componentId}:`, syncError);
+            console.error(`[useTamboComponentState] Failed to sync state for ${componentId}:`, syncError);
         }
         finally {
             // Only clear isPending if this is the most recent request
@@ -83,18 +98,29 @@ function useTamboV1ComponentState(keyName, initialValue, debounceTime = 500) {
             const nextState = typeof newState === "function"
                 ? newState(prev)
                 : newState;
+            // No side effects when context isn't available yet (local-only update)
+            if (!isContextAvailable) {
+                return nextState;
+            }
             if (isInteractable) {
                 // For interactable components, update the interactable provider's state
                 setInteractableState(componentId, keyName, nextState);
             }
             else {
-                // For v1-rendered components, trigger debounced sync to server
+                // For rendered components, trigger debounced sync to server
                 hasPendingLocalChangeRef.current = true;
                 void syncToServer(nextState);
             }
             return nextState;
         });
-    }, [isInteractable, syncToServer, setInteractableState, componentId, keyName]);
+    }, [
+        isContextAvailable,
+        isInteractable,
+        syncToServer,
+        setInteractableState,
+        componentId,
+        keyName,
+    ]);
     // Set initial value in interactable state on mount if no existing state
     const existingInteractableState = isInteractable
         ? getInteractableComponentState(componentId)?.[keyName]
@@ -121,9 +147,9 @@ function useTamboV1ComponentState(keyName, initialValue, debounceTime = 500) {
             return;
         setLocalState((prev) => (0, fast_equals_1.deepEqual)(prev, interactableState) ? prev : interactableState);
     }, [isInteractable, interactableState]);
-    // Sync from server state when it changes (e.g., from streaming events) - v1-rendered only
+    // Sync from server state when it changes (e.g., from streaming events) - rendered components only
     (0, react_1.useEffect)(() => {
-        if (isInteractable)
+        if (!isContextAvailable || isInteractable)
             return;
         if (serverValue === undefined)
             return;
@@ -138,21 +164,21 @@ function useTamboV1ComponentState(keyName, initialValue, debounceTime = 500) {
         }
         // Use functional update to avoid localState in deps
         setLocalState((prev) => (0, fast_equals_1.deepEqual)(serverValue, prev) ? prev : serverValue);
-    }, [isInteractable, serverValue]);
-    // Flush pending updates on unmount (only for v1-rendered components)
+    }, [isContextAvailable, isInteractable, serverValue]);
+    // Flush pending updates on unmount (only for rendered components)
     (0, react_1.useEffect)(() => {
-        if (isInteractable)
+        if (!isContextAvailable || isInteractable)
             return;
         return () => {
             void syncToServer.flush();
         };
-    }, [isInteractable, syncToServer]);
-    // Flush function for immediate sync (noop for interactable)
+    }, [isContextAvailable, isInteractable, syncToServer]);
+    // Flush function for immediate sync (noop when context is unavailable or interactable)
     const flush = (0, react_1.useCallback)(() => {
-        if (isInteractable)
+        if (!isContextAvailable || isInteractable)
             return;
         void syncToServer.flush();
-    }, [isInteractable, syncToServer]);
+    }, [isContextAvailable, isInteractable, syncToServer]);
     return [localState, setState, { isPending, error, flush }];
 }
 //# sourceMappingURL=use-tambo-v1-component-state.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-tambo-v1-component-state.js","sourceRoot":"","sources":["../../../src/v1/hooks/use-tambo-v1-component-state.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n/**\n * useTamboV1ComponentState - Component State Hook for v1 API\n *\n * Provides bidirectional state synchronization between React components\n * and the Tambo backend. State changes are debounced before syncing to\n * the server, and server state updates are reflected in the component.\n *\n * Must be used within a component rendered via the component renderer.\n */\n\nimport { useCallback, useEffect, useState, useRef } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { deepEqual } from \"fast-equals\";\nimport { useTamboClient } from \"../../providers/tambo-client-provider\";\nimport { useTamboInteractable } from \"../../providers/tambo-interactable-provider\";\nimport { useV1ComponentContent } from \"../utils/component-renderer\";\nimport { useStreamState } from \"../providers/tambo-v1-stream-context\";\nimport { findComponentContent } from \"../utils/thread-utils\";\n\n/**\n * Return type for useTamboV1ComponentState hook.\n * Similar to useState but with additional metadata.\n */\nexport type UseTamboV1ComponentStateReturn<S> = [\n  currentState: S,\n  setState: (newState: S | ((prev: S) => S)) => void,\n  meta: {\n    isPending: boolean;\n    error: Error | null;\n    flush: () => void;\n  },\n];\n\n/**\n * Hook for managing component state with bidirectional server sync.\n *\n * This hook acts like useState but automatically syncs state changes\n * to the Tambo backend. Server-side state updates are also reflected\n * in the component.\n *\n * Must be used within a component rendered via the component renderer.\n * @param keyName - The unique key to identify this state value within the component's state\n * @param initialValue - Initial value for the state (used if no server state exists)\n * @param debounceTime - Debounce time in milliseconds (default: 500ms)\n * @returns Tuple of [currentState, setState, meta]\n * @example\n * ```tsx\n * function Counter() {\n *   const [count, setCount, { isPending }] = useTamboV1ComponentState('count', 0);\n *\n *   return (\n *     <div>\n *       <span>{count}</span>\n *       <button onClick={() => setCount(c => c + 1)} disabled={isPending}>\n *         Increment\n *       </button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useTamboV1ComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime?: number,\n): UseTamboV1ComponentStateReturn<S | undefined>;\nexport function useTamboV1ComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  debounceTime?: number,\n): UseTamboV1ComponentStateReturn<S>;\nexport function useTamboV1ComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime = 500,\n): UseTamboV1ComponentStateReturn<S> {\n  const client = useTamboClient();\n  const { componentId, threadId } = useV1ComponentContent();\n  const streamState = useStreamState();\n  const { setInteractableState, getInteractableComponentState } =\n    useTamboInteractable();\n\n  // Interactable components use threadId=\"\" (set by withTamboInteractable)\n  const isInteractable = threadId === \"\";\n\n  // Find the component content to get server state (only for v1-rendered components)\n  const componentContent = isInteractable\n    ? undefined\n    : findComponentContent(streamState, threadId, componentId);\n  const serverState = componentContent?.state as\n    | Record<string, unknown>\n    | undefined;\n  const serverValue = serverState?.[keyName] as S | undefined;\n\n  // For interactable components, read state from the interactable provider\n  const interactableState = isInteractable\n    ? (getInteractableComponentState(componentId)?.[keyName] as S | undefined)\n    : undefined;\n\n  // Local state - initialized from interactable state, server state, or initial value\n  const [localState, setLocalState] = useState<S>(\n    () => interactableState ?? serverValue ?? (initialValue as S),\n  );\n\n  // Track pending state and errors\n  const [isPending, setIsPending] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  // Track the last value we sent to avoid overwriting with stale server state\n  const lastSentValueRef = useRef<S | undefined>(undefined);\n\n  // Track whether there's a pending local change that hasn't synced yet\n  const hasPendingLocalChangeRef = useRef(false);\n\n  // Track in-flight sync requests to avoid stale completions clearing pending state\n  const syncSeqRef = useRef(0);\n\n  // Debounced function to sync state to server (only used for v1-rendered components)\n  const syncToServer = useDebouncedCallback(async (newState: S) => {\n    if (isInteractable) return;\n\n    const seq = ++syncSeqRef.current;\n    setIsPending(true);\n    setError(null);\n    lastSentValueRef.current = newState;\n\n    try {\n      await client.threads.state.updateState(componentId, {\n        threadId,\n        state: { [keyName]: newState },\n      });\n      // Clear pending flag after successful sync\n      hasPendingLocalChangeRef.current = false;\n    } catch (err) {\n      // Clear pending flag on error to allow server reconciliation\n      hasPendingLocalChangeRef.current = false;\n      const syncError = err instanceof Error ? err : new Error(String(err));\n      setError(syncError);\n      console.error(\n        `[useTamboV1ComponentState] Failed to sync state for ${componentId}:`,\n        syncError,\n      );\n    } finally {\n      // Only clear isPending if this is the most recent request\n      if (seq === syncSeqRef.current) {\n        setIsPending(false);\n      }\n    }\n  }, debounceTime);\n\n  // setState function that updates local state and syncs appropriately\n  const setState = useCallback(\n    (newState: S | ((prev: S) => S)) => {\n      setLocalState((prev) => {\n        const nextState =\n          typeof newState === \"function\"\n            ? (newState as (prev: S) => S)(prev)\n            : newState;\n\n        if (isInteractable) {\n          // For interactable components, update the interactable provider's state\n          setInteractableState(componentId, keyName, nextState);\n        } else {\n          // For v1-rendered components, trigger debounced sync to server\n          hasPendingLocalChangeRef.current = true;\n          void syncToServer(nextState);\n        }\n\n        return nextState;\n      });\n    },\n    [isInteractable, syncToServer, setInteractableState, componentId, keyName],\n  );\n\n  // Set initial value in interactable state on mount if no existing state\n  const existingInteractableState = isInteractable\n    ? getInteractableComponentState(componentId)?.[keyName]\n    : undefined;\n  const shouldUpdateInteractableInitial =\n    isInteractable &&\n    existingInteractableState === undefined &&\n    initialValue !== undefined;\n\n  useEffect(() => {\n    if (!shouldUpdateInteractableInitial) return;\n    setInteractableState(componentId, keyName, initialValue!);\n  }, [\n    shouldUpdateInteractableInitial,\n    componentId,\n    keyName,\n    initialValue,\n    setInteractableState,\n  ]);\n\n  // Sync from interactable provider when state changes externally (e.g., from AI tool call)\n  useEffect(() => {\n    if (!isInteractable) return;\n    if (interactableState === undefined) return;\n    setLocalState((prev) =>\n      deepEqual(prev, interactableState) ? prev : (interactableState as S),\n    );\n  }, [isInteractable, interactableState]);\n\n  // Sync from server state when it changes (e.g., from streaming events) - v1-rendered only\n  useEffect(() => {\n    if (isInteractable) return;\n    if (serverValue === undefined) return;\n\n    // Don't overwrite local changes that haven't synced yet\n    if (hasPendingLocalChangeRef.current) return;\n\n    // Only sync if the server value is different from what we last sent\n    // This prevents overwriting local state with stale server values\n    if (\n      lastSentValueRef.current !== undefined &&\n      deepEqual(serverValue, lastSentValueRef.current)\n    ) {\n      return;\n    }\n\n    // Use functional update to avoid localState in deps\n    setLocalState((prev) =>\n      deepEqual(serverValue, prev) ? prev : serverValue,\n    );\n  }, [isInteractable, serverValue]);\n\n  // Flush pending updates on unmount (only for v1-rendered components)\n  useEffect(() => {\n    if (isInteractable) return;\n    return () => {\n      void syncToServer.flush();\n    };\n  }, [isInteractable, syncToServer]);\n\n  // Flush function for immediate sync (noop for interactable)\n  const flush = useCallback(() => {\n    if (isInteractable) return;\n    void syncToServer.flush();\n  }, [isInteractable, syncToServer]);\n\n  return [localState, setState, { isPending, error, flush }];\n}\n"]}
+{"version":3,"file":"use-tambo-v1-component-state.js","sourceRoot":"","sources":["../../../src/v1/hooks/use-tambo-v1-component-state.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n/**\n * useTamboComponentState - Component State Hook\n *\n * Provides bidirectional state synchronization between React components\n * and the Tambo backend. State changes are debounced before syncing to\n * the server, and server state updates are reflected in the component.\n *\n * Works in three modes:\n * - **Rendered components**: syncs state bidirectionally with the server\n * - **Interactable components**: syncs state via the interactable provider\n * - **No context yet**: acts as plain useState (no side effects) until a\n *   provider wraps the component (e.g., first render before withTamboInteractable)\n */\n\nimport { useCallback, useEffect, useState, useRef } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { deepEqual } from \"fast-equals\";\nimport { useTamboClient } from \"../../providers/tambo-client-provider\";\nimport { useTamboInteractable } from \"../../providers/tambo-interactable-provider\";\nimport { useComponentContentOptional } from \"../utils/component-renderer\";\nimport { useTamboConfig } from \"../providers/tambo-v1-provider\";\nimport { useStreamState } from \"../providers/tambo-v1-stream-context\";\nimport { findComponentContent } from \"../utils/thread-utils\";\n\n/**\n * Return type for useTamboComponentState hook.\n * Similar to useState but with additional metadata.\n */\nexport type UseTamboComponentStateReturn<S> = [\n  currentState: S,\n  setState: (newState: S | ((prev: S) => S)) => void,\n  meta: {\n    isPending: boolean;\n    error: Error | null;\n    flush: () => void;\n  },\n];\n\n/**\n * Hook for managing component state with bidirectional server sync.\n *\n * This hook acts like useState but automatically syncs state changes\n * to the Tambo backend. Server-side state updates are also reflected\n * in the component.\n *\n * Can be used within rendered components, interactable components, or\n * components awaiting provider context (acts as plain useState until context is available).\n * @param keyName - The unique key to identify this state value within the component's state\n * @param initialValue - Initial value for the state (used if no server state exists)\n * @param debounceTime - Debounce time in milliseconds (default: 500ms)\n * @returns Tuple of [currentState, setState, meta]\n * @example\n * ```tsx\n * function Counter() {\n *   const [count, setCount, { isPending }] = useTamboComponentState('count', 0);\n *\n *   return (\n *     <div>\n *       <span>{count}</span>\n *       <button onClick={() => setCount(c => c + 1)} disabled={isPending}>\n *         Increment\n *       </button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime?: number,\n): UseTamboComponentStateReturn<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  debounceTime?: number,\n): UseTamboComponentStateReturn<S>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime = 500,\n): UseTamboComponentStateReturn<S> {\n  const client = useTamboClient();\n  const { userKey } = useTamboConfig();\n  const componentContent = useComponentContentOptional();\n  const streamState = useStreamState();\n  const { setInteractableState, getInteractableComponentState } =\n    useTamboInteractable();\n\n  // componentContent is null on the first render of interactable components\n  // (before withTamboInteractable sets the interactableId and wraps with provider).\n  // When null, we act as plain useState with no side effects.\n  const isContextAvailable = componentContent !== null;\n  const componentId = componentContent?.componentId ?? \"\";\n  const threadId = componentContent?.threadId ?? \"\";\n\n  // Only treat as interactable when we have real context with threadId=\"\"\n  // (set by withTamboInteractable). When context is missing entirely,\n  // neither interactable nor server-sync paths should run.\n  const isInteractable = isContextAvailable && threadId === \"\";\n\n  // Find the component content to get server state (only for rendered components)\n  const renderedContent = isInteractable\n    ? undefined\n    : findComponentContent(streamState, threadId, componentId);\n  const serverState = renderedContent?.state as\n    | Record<string, unknown>\n    | undefined;\n  const serverValue = serverState?.[keyName] as S | undefined;\n\n  // For interactable components, read state from the interactable provider\n  const interactableState = isInteractable\n    ? (getInteractableComponentState(componentId)?.[keyName] as S | undefined)\n    : undefined;\n\n  // Local state - initialized from interactable state, server state, or initial value\n  const [localState, setLocalState] = useState<S>(\n    () => interactableState ?? serverValue ?? (initialValue as S),\n  );\n\n  // Track pending state and errors\n  const [isPending, setIsPending] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  // Track the last value we sent to avoid overwriting with stale server state\n  const lastSentValueRef = useRef<S | undefined>(undefined);\n\n  // Track whether there's a pending local change that hasn't synced yet\n  const hasPendingLocalChangeRef = useRef(false);\n\n  // Track in-flight sync requests to avoid stale completions clearing pending state\n  const syncSeqRef = useRef(0);\n\n  // Debounced function to sync state to server (only used for rendered components)\n  const syncToServer = useDebouncedCallback(async (newState: S) => {\n    if (!isContextAvailable || isInteractable) return;\n\n    const seq = ++syncSeqRef.current;\n    setIsPending(true);\n    setError(null);\n    lastSentValueRef.current = newState;\n\n    try {\n      await client.threads.state.updateState(componentId, {\n        threadId,\n        state: { [keyName]: newState },\n        userKey,\n      });\n      // Clear pending flag after successful sync\n      hasPendingLocalChangeRef.current = false;\n    } catch (err) {\n      // Clear pending flag on error to allow server reconciliation\n      hasPendingLocalChangeRef.current = false;\n      const syncError = err instanceof Error ? err : new Error(String(err));\n      setError(syncError);\n      console.error(\n        `[useTamboComponentState] Failed to sync state for ${componentId}:`,\n        syncError,\n      );\n    } finally {\n      // Only clear isPending if this is the most recent request\n      if (seq === syncSeqRef.current) {\n        setIsPending(false);\n      }\n    }\n  }, debounceTime);\n\n  // setState function that updates local state and syncs appropriately\n  const setState = useCallback(\n    (newState: S | ((prev: S) => S)) => {\n      setLocalState((prev) => {\n        const nextState =\n          typeof newState === \"function\"\n            ? (newState as (prev: S) => S)(prev)\n            : newState;\n\n        // No side effects when context isn't available yet (local-only update)\n        if (!isContextAvailable) {\n          return nextState;\n        }\n\n        if (isInteractable) {\n          // For interactable components, update the interactable provider's state\n          setInteractableState(componentId, keyName, nextState);\n        } else {\n          // For rendered components, trigger debounced sync to server\n          hasPendingLocalChangeRef.current = true;\n          void syncToServer(nextState);\n        }\n\n        return nextState;\n      });\n    },\n    [\n      isContextAvailable,\n      isInteractable,\n      syncToServer,\n      setInteractableState,\n      componentId,\n      keyName,\n    ],\n  );\n\n  // Set initial value in interactable state on mount if no existing state\n  const existingInteractableState = isInteractable\n    ? getInteractableComponentState(componentId)?.[keyName]\n    : undefined;\n  const shouldUpdateInteractableInitial =\n    isInteractable &&\n    existingInteractableState === undefined &&\n    initialValue !== undefined;\n\n  useEffect(() => {\n    if (!shouldUpdateInteractableInitial) return;\n    setInteractableState(componentId, keyName, initialValue!);\n  }, [\n    shouldUpdateInteractableInitial,\n    componentId,\n    keyName,\n    initialValue,\n    setInteractableState,\n  ]);\n\n  // Sync from interactable provider when state changes externally (e.g., from AI tool call)\n  useEffect(() => {\n    if (!isInteractable) return;\n    if (interactableState === undefined) return;\n    setLocalState((prev) =>\n      deepEqual(prev, interactableState) ? prev : (interactableState as S),\n    );\n  }, [isInteractable, interactableState]);\n\n  // Sync from server state when it changes (e.g., from streaming events) - rendered components only\n  useEffect(() => {\n    if (!isContextAvailable || isInteractable) return;\n    if (serverValue === undefined) return;\n\n    // Don't overwrite local changes that haven't synced yet\n    if (hasPendingLocalChangeRef.current) return;\n\n    // Only sync if the server value is different from what we last sent\n    // This prevents overwriting local state with stale server values\n    if (\n      lastSentValueRef.current !== undefined &&\n      deepEqual(serverValue, lastSentValueRef.current)\n    ) {\n      return;\n    }\n\n    // Use functional update to avoid localState in deps\n    setLocalState((prev) =>\n      deepEqual(serverValue, prev) ? prev : serverValue,\n    );\n  }, [isContextAvailable, isInteractable, serverValue]);\n\n  // Flush pending updates on unmount (only for rendered components)\n  useEffect(() => {\n    if (!isContextAvailable || isInteractable) return;\n    return () => {\n      void syncToServer.flush();\n    };\n  }, [isContextAvailable, isInteractable, syncToServer]);\n\n  // Flush function for immediate sync (noop when context is unavailable or interactable)\n  const flush = useCallback(() => {\n    if (!isContextAvailable || isInteractable) return;\n    void syncToServer.flush();\n  }, [isContextAvailable, isInteractable, syncToServer]);\n\n  return [localState, setState, { isPending, error, flush }];\n}\n"]}

package/dist/v1/hooks/use-tambo-v1-component-state.test.js

@@ -10,10 +10,13 @@ jest.mock("../providers/tambo-v1-stream-context", () => ({
     useStreamState: jest.fn(),
 }));
 jest.mock("../utils/component-renderer", () => ({
-    useV1ComponentContent: jest.fn(),
+    useComponentContentOptional: jest.fn(),
 }));
 const mockSetInteractableState = jest.fn();
 const mockGetInteractableComponentState = jest.fn(() => undefined);
+jest.mock("../providers/tambo-v1-provider", () => ({
+    useTamboConfig: jest.fn(() => ({})),
+}));
 jest.mock("../../providers/tambo-interactable-provider", () => ({
     useTamboInteractable: () => ({
         interactableComponents: [],
@@ -43,10 +46,11 @@ jest.mock("use-debounce", () => ({
 }));
 // Import the mocked modules
 const tambo_client_provider_1 = require("../../providers/tambo-client-provider");
+const tambo_v1_provider_1 = require("../providers/tambo-v1-provider");
 const tambo_v1_stream_context_1 = require("../providers/tambo-v1-stream-context");
 const component_renderer_1 = require("../utils/component-renderer");
 const use_debounce_1 = require("use-debounce");
-describe("useTamboV1ComponentState", () => {
+describe("useTamboComponentState", () => {
     const mockUpdateState = jest.fn();
     const mockComponentId = "comp_test123";
     const mockThreadId = "thread_abc";
@@ -87,6 +91,7 @@ describe("useTamboV1ComponentState", () => {
     });
     beforeEach(() => {
         jest.clearAllMocks();
+        jest.mocked(tambo_v1_provider_1.useTamboConfig).mockReturnValue({});
         // Setup default mocks
         jest.mocked(tambo_client_provider_1.useTamboClient).mockReturnValue({
             threads: {
@@ -95,7 +100,7 @@ describe("useTamboV1ComponentState", () => {
                 },
             },
         });
-        jest.mocked(component_renderer_1.useV1ComponentContent).mockReturnValue({
+        jest.mocked(component_renderer_1.useComponentContentOptional).mockReturnValue({
             componentId: mockComponentId,
             threadId: mockThreadId,
             messageId: mockMessageId,
@@ -118,7 +123,7 @@ describe("useTamboV1ComponentState", () => {
         it("should initialize with initialValue when no server state exists", () => {
             const initialValue = "test-initial";
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(createMockStreamState({}));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", initialValue));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", initialValue));
             expect(result.current[0]).toBe(initialValue);
         });
         it("should use server state over initialValue", () => {
@@ -127,12 +132,12 @@ describe("useTamboV1ComponentState", () => {
             jest
                 .mocked(tambo_v1_stream_context_1.useStreamState)
                 .mockReturnValue(createMockStreamState({ testKey: serverValue }));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", initialValue));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", initialValue));
             expect(result.current[0]).toBe(serverValue);
         });
         it("should handle undefined initialValue gracefully", () => {
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(createMockStreamState({}));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey"));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey"));
             expect(result.current[0]).toBeUndefined();
         });
         it("should handle different data types correctly", () => {
@@ -147,7 +152,7 @@ describe("useTamboV1ComponentState", () => {
                 jest
                     .mocked(tambo_v1_stream_context_1.useStreamState)
                     .mockReturnValue(createMockStreamState({ testKey: value }));
-                const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", value));
+                const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", value));
                 expect(result.current[0]).toEqual(value);
             });
         });
@@ -158,7 +163,7 @@ describe("useTamboV1ComponentState", () => {
             jest
                 .mocked(tambo_v1_stream_context_1.useStreamState)
                 .mockReturnValue(createMockStreamState({ testKey: initialValue }));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", initialValue));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", initialValue));
             const newValue = "updated";
             (0, react_1.act)(() => {
                 result.current[1](newValue);
@@ -170,7 +175,7 @@ describe("useTamboV1ComponentState", () => {
             jest
                 .mocked(tambo_v1_stream_context_1.useStreamState)
                 .mockReturnValue(createMockStreamState({ counter: initialValue }));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("counter", initialValue));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("counter", initialValue));
             (0, react_1.act)(() => {
                 result.current[1]((prev) => (prev ?? 0) + 1);
             });
@@ -181,7 +186,7 @@ describe("useTamboV1ComponentState", () => {
             jest
                 .mocked(tambo_v1_stream_context_1.useStreamState)
                 .mockReturnValue(createMockStreamState({ testKey: initialValue }));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", initialValue));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", initialValue));
             const newValue = "updated";
             (0, react_1.act)(() => {
                 result.current[1](newValue);
@@ -190,6 +195,7 @@ describe("useTamboV1ComponentState", () => {
             expect(mockUpdateState).toHaveBeenCalledWith(mockComponentId, {
                 threadId: mockThreadId,
                 state: { testKey: newValue },
+                userKey: undefined,
             });
         });
         it("should work with complex objects", () => {
@@ -197,7 +203,7 @@ describe("useTamboV1ComponentState", () => {
             jest
                 .mocked(tambo_v1_stream_context_1.useStreamState)
                 .mockReturnValue(createMockStreamState({ data: initialValue }));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("data", initialValue));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("data", initialValue));
             const newValue = { name: "updated", items: [4, 5, 6] };
             (0, react_1.act)(() => {
                 result.current[1](newValue);
@@ -208,7 +214,7 @@ describe("useTamboV1ComponentState", () => {
     describe("Metadata", () => {
         it("should return isPending and error in meta", () => {
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(createMockStreamState({}));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "initial"));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial"));
             expect(result.current[2]).toEqual({
                 isPending: false,
                 error: null,
@@ -221,7 +227,7 @@ describe("useTamboV1ComponentState", () => {
             mockDebouncedFn.flush = mockFlush;
             jest.mocked(use_debounce_1.useDebouncedCallback).mockReturnValue(mockDebouncedFn);
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(createMockStreamState({}));
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "initial"));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial"));
             (0, react_1.act)(() => {
                 result.current[2].flush();
             });
@@ -231,13 +237,13 @@ describe("useTamboV1ComponentState", () => {
     describe("Debouncing Behavior", () => {
         it("should use default debounce time of 500ms", () => {
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(createMockStreamState({}));
-            (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "initial"));
+            (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial"));
             expect(use_debounce_1.useDebouncedCallback).toHaveBeenCalledWith(expect.any(Function), 500);
         });
         it("should use custom debounce time when provided", () => {
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(createMockStreamState({}));
             const customDebounceTime = 1000;
-            (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "initial", customDebounceTime));
+            (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial", customDebounceTime));
             expect(use_debounce_1.useDebouncedCallback).toHaveBeenCalledWith(expect.any(Function), customDebounceTime);
         });
         it("should flush debounced callback on unmount", () => {
@@ -246,7 +252,7 @@ describe("useTamboV1ComponentState", () => {
             mockDebouncedFn.flush = mockFlush;
             jest.mocked(use_debounce_1.useDebouncedCallback).mockReturnValue(mockDebouncedFn);
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(createMockStreamState({}));
-            const { unmount } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "initial"));
+            const { unmount } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial"));
             unmount();
             expect(mockFlush).toHaveBeenCalled();
         });
@@ -255,7 +261,7 @@ describe("useTamboV1ComponentState", () => {
         it("should sync with server state changes from streaming", () => {
             const streamState = createMockStreamState({ testKey: "initial" });
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(streamState);
-            const { result, rerender } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "initial"));
+            const { result, rerender } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial"));
             expect(result.current[0]).toBe("initial");
             // Simulate server state change from streaming
             const updatedStreamState = createMockStreamState({
@@ -271,7 +277,7 @@ describe("useTamboV1ComponentState", () => {
                 threadMap: {},
                 currentThreadId: "placeholder",
             });
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "default"));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "default"));
             expect(result.current[0]).toBe("default");
         });
     });
@@ -290,7 +296,7 @@ describe("useTamboV1ComponentState", () => {
             });
             jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue(createMockStreamState({}));
             const consoleSpy = jest.spyOn(console, "error").mockImplementation();
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "initial"));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial"));
             await (0, react_1.act)(async () => {
                 result.current[1]("new-value");
                 // Wait for async operations
@@ -301,20 +307,39 @@ describe("useTamboV1ComponentState", () => {
         });
     });
     describe("Context Requirements", () => {
-        it("should throw when used outside component content context", () => {
-            jest.mocked(component_renderer_1.useV1ComponentContent).mockImplementation(() => {
-                throw new Error("useV1ComponentContent must be used within a rendered component");
+        it("should act as plain useState when component content context is missing", () => {
+            jest.mocked(component_renderer_1.useComponentContentOptional).mockReturnValue(null);
+            jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue({
+                threadMap: {},
+                currentThreadId: "",
+            });
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial"));
+            expect(result.current[0]).toBe("initial");
+            // No side effects when context is missing
+            expect(mockSetInteractableState).not.toHaveBeenCalled();
+            expect(mockUpdateState).not.toHaveBeenCalled();
+        });
+        it("should not trigger side effects on setState when context is missing", () => {
+            jest.mocked(component_renderer_1.useComponentContentOptional).mockReturnValue(null);
+            jest.mocked(tambo_v1_stream_context_1.useStreamState).mockReturnValue({
+                threadMap: {},
+                currentThreadId: "",
             });
-            expect(() => {
-                (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("testKey", "initial"));
-            }).toThrow("useV1ComponentContent must be used within a rendered component");
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("testKey", "initial"));
+            (0, react_1.act)(() => {
+                result.current[1]("updated");
+            });
+            // Local state updates, but no server sync or interactable writes
+            expect(result.current[0]).toBe("updated");
+            expect(mockSetInteractableState).not.toHaveBeenCalled();
+            expect(mockUpdateState).not.toHaveBeenCalled();
         });
     });
     describe("Interactable Component Support", () => {
         const interactableComponentId = "MyWidget-abc";
         beforeEach(() => {
             // Simulate interactable context: threadId="" signals interactable
-            jest.mocked(component_renderer_1.useV1ComponentContent).mockReturnValue({
+            jest.mocked(component_renderer_1.useComponentContentOptional).mockReturnValue({
                 componentId: interactableComponentId,
                 threadId: "",
                 messageId: "",
@@ -328,17 +353,17 @@ describe("useTamboV1ComponentState", () => {
         });
         it("should initialize with initialValue when no interactable state exists", () => {
             mockGetInteractableComponentState.mockReturnValue(undefined);
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 42));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 42));
             expect(result.current[0]).toBe(42);
         });
         it("should initialize from interactable state when it exists", () => {
             mockGetInteractableComponentState.mockReturnValue({ count: 99 });
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 0));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 0));
             expect(result.current[0]).toBe(99);
         });
         it("should call setInteractableState when setState is called", () => {
             mockGetInteractableComponentState.mockReturnValue(undefined);
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 0));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 0));
             (0, react_1.act)(() => {
                 result.current[1](10);
             });
@@ -346,7 +371,7 @@ describe("useTamboV1ComponentState", () => {
         });
         it("should NOT call client.threads.state.updateState for interactable components", () => {
             mockGetInteractableComponentState.mockReturnValue(undefined);
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 0));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 0));
             (0, react_1.act)(() => {
                 result.current[1](10);
             });
@@ -354,7 +379,7 @@ describe("useTamboV1ComponentState", () => {
         });
         it("should sync from interactable provider when state changes externally", () => {
             mockGetInteractableComponentState.mockReturnValue({ count: 0 });
-            const { result, rerender } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 0));
+            const { result, rerender } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 0));
             expect(result.current[0]).toBe(0);
             // Simulate external state change (e.g., AI tool call)
             mockGetInteractableComponentState.mockReturnValue({ count: 77 });
@@ -363,18 +388,18 @@ describe("useTamboV1ComponentState", () => {
         });
         it("should have isPending as false in interactable context", () => {
             mockGetInteractableComponentState.mockReturnValue(undefined);
-            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 0));
+            const { result } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 0));
             expect(result.current[2].isPending).toBe(false);
             expect(result.current[2].error).toBeNull();
         });
         it("should set initial value in interactable state on mount when no existing state", () => {
             mockGetInteractableComponentState.mockReturnValue(undefined);
-            (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 42));
+            (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 42));
             expect(mockSetInteractableState).toHaveBeenCalledWith(interactableComponentId, "count", 42);
         });
         it("should NOT set initial value in interactable state when state already exists", () => {
             mockGetInteractableComponentState.mockReturnValue({ count: 99 });
-            (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 42));
+            (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 42));
             // Should not be called because state already exists
             expect(mockSetInteractableState).not.toHaveBeenCalled();
         });
@@ -384,7 +409,7 @@ describe("useTamboV1ComponentState", () => {
             mockDebouncedFn.flush = mockFlush;
             jest.mocked(use_debounce_1.useDebouncedCallback).mockReturnValue(mockDebouncedFn);
             mockGetInteractableComponentState.mockReturnValue(undefined);
-            const { unmount } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboV1ComponentState)("count", 0));
+            const { unmount } = (0, react_1.renderHook)(() => (0, use_tambo_v1_component_state_1.useTamboComponentState)("count", 0));
             unmount();
             expect(mockFlush).not.toHaveBeenCalled();
         });