@quiltt/react 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @quiltt/react
 
+## 4.5.0
+
+### Minor Changes
+
+- [#386](https://github.com/quiltt/quiltt-js/pull/386) [`0bf706c`](https://github.com/quiltt/quiltt-js/commit/0bf706ce2ad926304d6eac739ee58971736f913e) Thanks [@zubairaziz](https://github.com/zubairaziz)! - Update platform webview props
+
+### Patch Changes
+
+- [#380](https://github.com/quiltt/quiltt-js/pull/380) [`31cd190`](https://github.com/quiltt/quiltt-js/commit/31cd1902618ebc2314d42dd7aca81b3ab94068ea) Thanks [@sirwolfgang](https://github.com/sirwolfgang)! - Improve useQuilttResolvable error messaging
+
+- Updated dependencies [[`31cd190`](https://github.com/quiltt/quiltt-js/commit/31cd1902618ebc2314d42dd7aca81b3ab94068ea), [`0bf706c`](https://github.com/quiltt/quiltt-js/commit/0bf706ce2ad926304d6eac739ee58971736f913e)]:
+  - @quiltt/core@4.5.0
+
 ## 4.4.0
 
 ### Minor Changes

package/dist/{QuilttAuthProvider-12s-4hQ7iysR.js → QuilttAuthProvider-12s-BCpwSX-3.js}

@@ -5,9 +5,10 @@ import '@apollo/client/react/hooks/useApolloClient.js';
 import './QuilttSettings-12s-BK-0SQME.js';
 import './useSession-12s-7GOn4sUn.js';
 import 'use-debounce';
+import './QuilttProviderRender-12s-DtQtubjL.js';
 import { jsx } from 'react/jsx-runtime';
 import { ApolloProvider } from '@apollo/client/react/context/ApolloProvider.js';
-import { u as useQuilttSession } from './useQuilttSession-12s-BCq3OL9S.js';
+import { u as useQuilttSession } from './useQuilttSession-12s-D10t5Wfh.js';
 
 const useAuthenticateSession = (auth, setSession)=>{
     const authenticateSession = useCallback(async (payload, callbacks)=>{

package/dist/QuilttProviderRender-12s-DtQtubjL.js

@@ -0,0 +1,6 @@
+'use client';
+import { createContext } from 'react';
+
+const QuilttProviderRender = createContext({});
+
+export { QuilttProviderRender as Q };

package/dist/index.d.ts

@@ -117,6 +117,31 @@ declare const useQuilttConnector: (connectorId?: string, options?: ConnectorSDKC
     open: () => void;
 };
 
+type UseQuilttInstitutions = (connectorId: string, onErrorCallback?: (msg: string) => void) => {
+    searchTerm: string;
+    searchResults: InstitutionsData;
+    isSearching: boolean;
+    setSearchTerm: (term: string) => void;
+};
+declare const useQuilttInstitutions: UseQuilttInstitutions;
+
+/**
+ * Internal hook that detects when a Quiltt SDK component may be rendered
+ * in the same component as QuilttProvider, which is an anti-pattern that
+ * can cause memory context issues and unexpected behavior.
+ *
+ * **Limitation**: Due to React context propagation, this will trigger for ALL
+ * descendants of QuilttProvider, not just direct children. This means it may
+ * produce false positives for valid nested component patterns. However, the
+ * primary use case (same-component rendering) is reliably detected.
+ *
+ * When the flag is set, this hook will emit a console error. This primarily
+ * helps catch the anti-pattern but may also flag valid nested structures.
+ *
+ * @param componentName - The name of the component calling this hook (for error messages)
+ */
+declare const useQuilttRenderGuard: (componentName: string) => void;
+
 type UseQuilttResolvable = (connectorId: string, onErrorCallback?: (msg: string) => void) => {
     checkResolvable: (providerId: {
         plaid?: string;
@@ -131,14 +156,6 @@ type UseQuilttResolvable = (connectorId: string, onErrorCallback?: (msg: string)
 };
 declare const useQuilttResolvable: UseQuilttResolvable;
 
-type UseQuilttInstitutions = (connectorId: string, onErrorCallback?: (msg: string) => void) => {
-    searchTerm: string;
-    searchResults: InstitutionsData;
-    isSearching: boolean;
-    setSearchTerm: (term: string) => void;
-};
-declare const useQuilttInstitutions: UseQuilttInstitutions;
-
 type UseQuilttSession = (environmentId?: string) => {
     session: Maybe<QuilttJWT> | undefined;
     importSession: ImportSession;
@@ -196,5 +213,5 @@ declare const QuilttSettingsProvider: FC<QuilttSettingsProviderProps>;
 type QuilttProviderProps = QuilttSettingsProviderProps & QuilttAuthProviderProps;
 declare const QuilttProvider: FC<QuilttProviderProps>;
 
-export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useAuthenticateSession, useEventListener, useIdentifySession, useImportSession, useIsomorphicLayoutEffect, useQuilttClient, useQuilttConnector, useQuilttInstitutions, useQuilttResolvable, useQuilttSession, useQuilttSettings, useRevokeSession, useSession, useStorage };
+export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useAuthenticateSession, useEventListener, useIdentifySession, useImportSession, useIsomorphicLayoutEffect, useQuilttClient, useQuilttConnector, useQuilttInstitutions, useQuilttRenderGuard, useQuilttResolvable, useQuilttSession, useQuilttSettings, useRevokeSession, useSession, useStorage };
 export type { AuthenticateSession, IdentifySession, ImportSession, QuilttAuthProviderProps, QuilttSettingsProviderProps, RevokeSession, SetSession, UseQuilttInstitutions, UseQuilttResolvable, UseQuilttSession };

package/dist/index.js

@@ -1,18 +1,20 @@
 export * from '@quiltt/core';
 import { jsx } from 'react/jsx-runtime';
 import { useRef, useEffect } from 'react';
-import { u as useQuilttConnector } from './useQuilttConnector-12s-BiIbmt7I.js';
-import { i as isDeepEqual, Q as QuilttAuthProvider } from './QuilttAuthProvider-12s-4hQ7iysR.js';
-export { b as useAuthenticateSession, a as useIdentifySession, u as useImportSession, c as useRevokeSession } from './QuilttAuthProvider-12s-4hQ7iysR.js';
+import { u as useQuilttConnector } from './useQuilttConnector-12s-7jon0A8C.js';
+import { u as useQuilttRenderGuard } from './useQuilttRenderGuard-12s-BbUitnF1.js';
+import { i as isDeepEqual, Q as QuilttAuthProvider } from './QuilttAuthProvider-12s-BCpwSX-3.js';
+export { b as useAuthenticateSession, a as useIdentifySession, u as useImportSession, c as useRevokeSession } from './QuilttAuthProvider-12s-BCpwSX-3.js';
 export { u as useEventListener } from './useEventListener-12s-D_-6QIXa.js';
 export { u as useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect-12s-DeTHOKz1.js';
 export { u as useQuilttClient } from './useQuilttClient-12s-CAAUait1.js';
-export { u as useQuilttResolvable } from './useQuilttResolvable-12s-C2mjy5zs.js';
-export { u as useQuilttInstitutions } from './useQuilttInstitutions-12s-0_y37UHg.js';
-export { u as useQuilttSession } from './useQuilttSession-12s-BCq3OL9S.js';
+export { u as useQuilttInstitutions } from './useQuilttInstitutions-12s-Ca5smTKo.js';
+export { u as useQuilttResolvable } from './useQuilttResolvable-12s-CNvWZe0V.js';
+export { u as useQuilttSession } from './useQuilttSession-12s-D10t5Wfh.js';
 export { u as useQuilttSettings } from './useQuilttSettings-12s--rCJoNHD.js';
 export { u as useSession } from './useSession-12s-7GOn4sUn.js';
 export { u as useStorage } from './useStorage-12s-DHcq3Kuh.js';
+import { Q as QuilttProviderRender } from './QuilttProviderRender-12s-DtQtubjL.js';
 import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmOiZ.js';
 
 /**
@@ -22,6 +24,8 @@ import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmO
  * connector instance with the new connection details. If you need to force a
  * complete remount instead, set forceRemountOnConnectionChange to true.
  */ const QuilttButton = ({ as, connectorId, connectionId, institution, forceRemountOnConnectionChange = false, onEvent, onOpen, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, onClick, onHtmlLoad, children, ...props })=>{
+    // Check flag to warn about potential anti-pattern (may produce false positives for valid nested patterns)
+    useQuilttRenderGuard('QuilttButton');
     // Keep track of previous connectionId for change detection
     const prevConnectionIdRef = useRef(connectionId);
     const prevCallbacksRef = useRef({
@@ -104,6 +108,8 @@ import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmO
  * connector instance with the new connection details. If you need to force a
  * complete remount instead, set forceRemountOnConnectionChange to true.
  */ const QuilttContainer = ({ as, connectorId, connectionId, forceRemountOnConnectionChange = false, onEvent, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, children, ...props })=>{
+    // Check flag to warn about potential anti-pattern (may produce false positives for valid nested patterns)
+    useQuilttRenderGuard('QuilttContainer');
     // Keep track of previous connectionId for change detection
     const prevConnectionIdRef = useRef(connectionId);
     const prevCallbacksRef = useRef({
@@ -163,14 +169,24 @@ import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmO
 };
 
 const QuilttProvider = ({ clientId, graphqlClient, token, children })=>{
-    return /*#__PURE__*/ jsx(QuilttSettingsProvider, {
-        clientId: clientId,
-        children: /*#__PURE__*/ jsx(QuilttAuthProvider, {
-            token: token,
-            graphqlClient: graphqlClient,
-            children: children
+    // Set a context flag that SDK components can check to warn about potential anti-patterns.
+    // LIMITATION: This flags ALL descendants due to React context propagation, not just same-component usage.
+    // Will produce false positives for valid patterns like: <QuilttProvider><MyPage /></QuilttProvider>
+    // where MyPage renders SDK components (which is correct usage).
+    // The flag-based approach is simple but imprecise - a proper solution would require render stack tracking.
+    return /*#__PURE__*/ jsx(QuilttProviderRender.Provider, {
+        value: {
+            isRenderingProvider: true
+        },
+        children: /*#__PURE__*/ jsx(QuilttSettingsProvider, {
+            clientId: clientId,
+            children: /*#__PURE__*/ jsx(QuilttAuthProvider, {
+                token: token,
+                graphqlClient: graphqlClient,
+                children: children
+            })
         })
     });
 };
 
-export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useQuilttConnector };
+export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useQuilttConnector, useQuilttRenderGuard };

package/dist/{useQuilttConnector-12s-BiIbmt7I.js → useQuilttConnector-12s-7jon0A8C.js}

@@ -1,11 +1,11 @@
 'use client';
 import { useState, useRef, useEffect, useCallback } from 'react';
 import { cdnBase } from '@quiltt/core';
-import { u as useQuilttSession } from './useQuilttSession-12s-BCq3OL9S.js';
+import { u as useQuilttSession } from './useQuilttSession-12s-D10t5Wfh.js';
 import { u as useScript } from './useScript-12s-JCgaTW9n.js';
-import { i as isDeepEqual } from './QuilttAuthProvider-12s-4hQ7iysR.js';
+import { i as isDeepEqual } from './QuilttAuthProvider-12s-BCpwSX-3.js';
 
-var version = "4.4.0";
+var version = "4.5.0";
 
 const useQuilttConnector = (connectorId, options)=>{
     const status = useScript(`${cdnBase}/v1/connector.js?agent=react-${version}`, {

package/dist/{useQuilttInstitutions-12s-0_y37UHg.js → useQuilttInstitutions-12s-Ca5smTKo.js}

@@ -2,7 +2,7 @@
 import { useMemo, useState, useRef, useEffect, useCallback } from 'react';
 import { ConnectorsAPI } from '@quiltt/core';
 import { useDebounce } from 'use-debounce';
-import { v as version } from './useQuilttConnector-12s-BiIbmt7I.js';
+import { v as version } from './useQuilttConnector-12s-7jon0A8C.js';
 import { u as useSession } from './useSession-12s-7GOn4sUn.js';
 
 const useQuilttInstitutions = (connectorId, onErrorCallback)=>{

package/dist/useQuilttRenderGuard-12s-BbUitnF1.js

@@ -0,0 +1,37 @@
+'use client';
+import { useContext, useRef, useEffect } from 'react';
+import { Q as QuilttProviderRender } from './QuilttProviderRender-12s-DtQtubjL.js';
+
+/**
+ * Internal hook that detects when a Quiltt SDK component may be rendered
+ * in the same component as QuilttProvider, which is an anti-pattern that
+ * can cause memory context issues and unexpected behavior.
+ *
+ * **Limitation**: Due to React context propagation, this will trigger for ALL
+ * descendants of QuilttProvider, not just direct children. This means it may
+ * produce false positives for valid nested component patterns. However, the
+ * primary use case (same-component rendering) is reliably detected.
+ *
+ * When the flag is set, this hook will emit a console error. This primarily
+ * helps catch the anti-pattern but may also flag valid nested structures.
+ *
+ * @param componentName - The name of the component calling this hook (for error messages)
+ */ const useQuilttRenderGuard = (componentName)=>{
+    const { isRenderingProvider } = useContext(QuilttProviderRender);
+    const hasWarnedRef = useRef(false);
+    useEffect(()=>{
+        // Only run in development mode and warn once per component instance
+        // Support both Node.js (process.env) and Vite (import.meta.env) environments
+        const isProduction = process.env.NODE_ENV === 'production' || typeof import.meta !== 'undefined' && import.meta.env?.PROD;
+        if (isProduction) return;
+        if (isRenderingProvider && !hasWarnedRef.current) {
+            hasWarnedRef.current = true;
+            console.error(`[Quiltt] ⚠️  POTENTIAL ANTI-PATTERN: ${componentName} may be rendered in the same component as QuilttProvider.\n\n` + `NOTE: This check uses a simple flag and may produce false positives for valid nested patterns.\n` + `If ${componentName} is in a SEPARATE component from QuilttProvider, you can safely ignore this.\n\n` + `The ANTI-PATTERN we're trying to catch:\n` + `  • Rendering Provider and SDK components in the SAME function component\n` + `  • This causes memory context issues because they run at the same React execution layer\n` + `  • React cannot properly manage the context hierarchy in this case\n\n` + `RECOMMENDED PATTERN:\n` + `  • Move QuilttProvider to a parent component or layout\n` + `  • Render ${componentName} in a child component\n\n` + `Example:\n\n` + `  // ✅ CORRECT: Provider in parent, SDK component in child (separate components)\n` + `  function Providers({ children }) {\n` + `    return (\n` + `      <QuilttProvider token={token}>\n` + `        {children}\n` + `      </QuilttProvider>\n` + `    )\n` + `  }\n\n` + `  function MyFeature() {\n` + `    return <${componentName} connectorId="..." />\n` + `  }\n\n` + `  // ❌ ANTI-PATTERN: Both in SAME component\n` + `  function MyFeature() {\n` + `    return (\n` + `      <QuilttProvider token={token}>\n` + `        <${componentName} connectorId="..." />\n` + `      </QuilttProvider>\n` + `    )\n` + `  }\n\n` + `Learn more:\n` + `  • https://github.com/quiltt/quiltt-js/tree/main/packages/react#provider-usage\n` + `  • https://react.dev/reference/react/useContext#my-component-doesnt-see-the-value-from-my-provider`);
+        }
+    }, [
+        isRenderingProvider,
+        componentName
+    ]);
+};
+
+export { useQuilttRenderGuard as u };

package/dist/{useQuilttResolvable-12s-C2mjy5zs.js → useQuilttResolvable-12s-CNvWZe0V.js}

@@ -1,7 +1,7 @@
 'use client';
-import { useMemo, useState, useCallback } from 'react';
+import { useMemo, useState, useRef, useEffect, useCallback } from 'react';
 import { ConnectorsAPI } from '@quiltt/core';
-import { v as version } from './useQuilttConnector-12s-BiIbmt7I.js';
+import { v as version } from './useQuilttConnector-12s-7jon0A8C.js';
 import { u as useSession } from './useSession-12s-7GOn4sUn.js';
 
 const useQuilttResolvable = (connectorId, onErrorCallback)=>{
@@ -25,17 +25,24 @@ const useQuilttResolvable = (connectorId, onErrorCallback)=>{
     const [isLoading, setIsLoading] = useState(false);
     const [isResolvable, setIsResolvable] = useState(null);
     const [error, setError] = useState(null);
+    // Store callback in ref to maintain stable reference
+    const onErrorCallbackRef = useRef(onErrorCallback);
+    useEffect(()=>{
+        onErrorCallbackRef.current = onErrorCallback;
+    });
     const handleError = useCallback((message)=>{
         const errorMessage = message || 'Unknown error occurred while checking resolvability';
         setError(errorMessage);
         console.error('Quiltt Connector Resolvable Error:', errorMessage);
-        if (onErrorCallback) onErrorCallback(errorMessage);
-    }, [
-        onErrorCallback
-    ]);
+        if (onErrorCallbackRef.current) onErrorCallbackRef.current(errorMessage);
+    }, []);
     const checkResolvable = useCallback(async (providerId)=>{
-        if (!session?.token || !connectorId) {
-            handleError('Missing session token or connector ID');
+        if (!session?.token) {
+            handleError('Missing session token');
+            return null;
+        }
+        if (!connectorId) {
+            handleError('Missing connector ID');
             return null;
         }
         const hasProviderId = Object.values(providerId).some((id)=>!!id);

package/dist/{useQuilttSession-12s-BCq3OL9S.js → useQuilttSession-12s-D10t5Wfh.js}

@@ -1,14 +1,16 @@
 'use client';
-import { useCallback } from 'react';
+import { useMemo, useCallback } from 'react';
 import { AuthAPI } from '@quiltt/core';
-import { u as useImportSession, a as useIdentifySession, b as useAuthenticateSession, c as useRevokeSession } from './QuilttAuthProvider-12s-4hQ7iysR.js';
+import { u as useImportSession, a as useIdentifySession, b as useAuthenticateSession, c as useRevokeSession } from './QuilttAuthProvider-12s-BCpwSX-3.js';
 import { u as useQuilttSettings } from './useQuilttSettings-12s--rCJoNHD.js';
 import { u as useSession } from './useSession-12s-7GOn4sUn.js';
 
 const useQuilttSession = (environmentId)=>{
     const { clientId } = useQuilttSettings();
     const [session, setSession] = useSession();
-    const auth = new AuthAPI(clientId);
+    const auth = useMemo(()=>new AuthAPI(clientId), [
+        clientId
+    ]);
     const importSession = useImportSession(auth, session, setSession, environmentId);
     const identifySession = useIdentifySession(auth, setSession);
     const authenticateSession = useAuthenticateSession(auth, setSession);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/react",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "React Components and Hooks for Quiltt Connector",
   "keywords": [
     "quiltt",
@@ -36,7 +36,7 @@
   "dependencies": {
     "@apollo/client": "^3.14.0",
     "use-debounce": "^10.0.4",
-    "@quiltt/core": "4.4.0"
+    "@quiltt/core": "4.5.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.4",

package/src/components/QuilttButton.tsx

@@ -4,6 +4,7 @@ import { useEffect, useRef } from 'react'
 import type { ConnectorSDKCallbacks } from '@quiltt/core'
 
 import { useQuilttConnector } from '@/hooks/useQuilttConnector'
+import { useQuilttRenderGuard } from '@/hooks/useQuilttRenderGuard'
 import type { PropsOf } from '@/types'
 import { isDeepEqual } from '@/utils/isDeepEqual'
 
@@ -62,6 +63,9 @@ export const QuilttButton = <T extends ElementType = 'button'>({
   children,
   ...props
 }: QuilttButtonProps<T> & PropsOf<T>) => {
+  // Check flag to warn about potential anti-pattern (may produce false positives for valid nested patterns)
+  useQuilttRenderGuard('QuilttButton')
+
   // Keep track of previous connectionId for change detection
   const prevConnectionIdRef = useRef<string | undefined>(connectionId)
   const prevCallbacksRef = useRef({

package/src/components/QuilttContainer.tsx

@@ -4,6 +4,7 @@ import { useEffect, useRef } from 'react'
 import type { ConnectorSDKCallbacks } from '@quiltt/core'
 
 import { useQuilttConnector } from '@/hooks/useQuilttConnector'
+import { useQuilttRenderGuard } from '@/hooks/useQuilttRenderGuard'
 import type { PropsOf } from '@/types'
 import { isDeepEqual } from '@/utils/isDeepEqual'
 
@@ -44,6 +45,9 @@ export const QuilttContainer = <T extends ElementType = 'div'>({
   children,
   ...props
 }: QuilttContainerProps<T> & PropsOf<T>) => {
+  // Check flag to warn about potential anti-pattern (may produce false positives for valid nested patterns)
+  useQuilttRenderGuard('QuilttContainer')
+
   // Keep track of previous connectionId for change detection
   const prevConnectionIdRef = useRef<string | undefined>(connectionId)
   const prevCallbacksRef = useRef({

package/src/contexts/QuilttProviderRender.ts

@@ -0,0 +1,15 @@
+'use client'
+
+import { createContext } from 'react'
+
+type QuilttProviderRenderContext = {
+  /**
+   * Flag indicating that QuilttProvider is in the ancestor tree.
+   * Due to React context propagation, this is true for ALL descendants,
+   * not just those in the same component as the provider.
+   * Used to detect potential anti-patterns in component composition.
+   */
+  isRenderingProvider?: boolean
+}
+
+export const QuilttProviderRender = createContext<QuilttProviderRenderContext>({})

package/src/hooks/index.ts

@@ -2,8 +2,9 @@ export * from './helpers'
 export * from './session'
 export * from './useQuilttClient'
 export * from './useQuilttConnector'
-export * from './useQuilttResolvable'
 export * from './useQuilttInstitutions'
+export * from './useQuilttRenderGuard'
+export * from './useQuilttResolvable'
 export * from './useQuilttSession'
 export * from './useQuilttSettings'
 export * from './useSession'

package/src/hooks/useQuilttRenderGuard.ts

@@ -0,0 +1,76 @@
+'use client'
+
+import { useContext, useEffect, useRef } from 'react'
+
+import { QuilttProviderRender } from '@/contexts/QuilttProviderRender'
+
+/**
+ * Internal hook that detects when a Quiltt SDK component may be rendered
+ * in the same component as QuilttProvider, which is an anti-pattern that
+ * can cause memory context issues and unexpected behavior.
+ *
+ * **Limitation**: Due to React context propagation, this will trigger for ALL
+ * descendants of QuilttProvider, not just direct children. This means it may
+ * produce false positives for valid nested component patterns. However, the
+ * primary use case (same-component rendering) is reliably detected.
+ *
+ * When the flag is set, this hook will emit a console error. This primarily
+ * helps catch the anti-pattern but may also flag valid nested structures.
+ *
+ * @param componentName - The name of the component calling this hook (for error messages)
+ */
+export const useQuilttRenderGuard = (componentName: string) => {
+  const { isRenderingProvider } = useContext(QuilttProviderRender)
+  const hasWarnedRef = useRef(false)
+
+  useEffect(() => {
+    // Only run in development mode and warn once per component instance
+    // Support both Node.js (process.env) and Vite (import.meta.env) environments
+    const isProduction =
+      process.env.NODE_ENV === 'production' ||
+      (typeof import.meta !== 'undefined' && (import.meta as any).env?.PROD)
+
+    if (isProduction) return
+
+    if (isRenderingProvider && !hasWarnedRef.current) {
+      hasWarnedRef.current = true
+      console.error(
+        `[Quiltt] ⚠️  POTENTIAL ANTI-PATTERN: ${componentName} may be rendered in the same component as QuilttProvider.\n\n` +
+          `NOTE: This check uses a simple flag and may produce false positives for valid nested patterns.\n` +
+          `If ${componentName} is in a SEPARATE component from QuilttProvider, you can safely ignore this.\n\n` +
+          `The ANTI-PATTERN we're trying to catch:\n` +
+          `  • Rendering Provider and SDK components in the SAME function component\n` +
+          `  • This causes memory context issues because they run at the same React execution layer\n` +
+          `  • React cannot properly manage the context hierarchy in this case\n\n` +
+          `RECOMMENDED PATTERN:\n` +
+          `  • Move QuilttProvider to a parent component or layout\n` +
+          `  • Render ${componentName} in a child component\n\n` +
+          `Example:\n\n` +
+          `  // ✅ CORRECT: Provider in parent, SDK component in child (separate components)\n` +
+          `  function Providers({ children }) {\n` +
+          `    return (\n` +
+          `      <QuilttProvider token={token}>\n` +
+          `        {children}\n` +
+          `      </QuilttProvider>\n` +
+          `    )\n` +
+          `  }\n\n` +
+          `  function MyFeature() {\n` +
+          `    return <${componentName} connectorId="..." />\n` +
+          `  }\n\n` +
+          `  // ❌ ANTI-PATTERN: Both in SAME component\n` +
+          `  function MyFeature() {\n` +
+          `    return (\n` +
+          `      <QuilttProvider token={token}>\n` +
+          `        <${componentName} connectorId="..." />\n` +
+          `      </QuilttProvider>\n` +
+          `    )\n` +
+          `  }\n\n` +
+          `Learn more:\n` +
+          `  • https://github.com/quiltt/quiltt-js/tree/main/packages/react#provider-usage\n` +
+          `  • https://react.dev/reference/react/useContext#my-component-doesnt-see-the-value-from-my-provider`
+      )
+    }
+  }, [isRenderingProvider, componentName])
+}
+
+export default useQuilttRenderGuard

package/src/hooks/useQuilttResolvable.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useCallback, useMemo, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import type { ErrorData, ResolvableData } from '@quiltt/core'
 import { ConnectorsAPI } from '@quiltt/core'
@@ -10,7 +10,7 @@ import useSession from './useSession'
 
 export type UseQuilttResolvable = (
   connectorId: string,
-  onErrorCallback?: (msg: string) => void,
+  onErrorCallback?: (msg: string) => void
 ) => {
   checkResolvable: (providerId: {
     plaid?: string
@@ -24,10 +24,7 @@ export type UseQuilttResolvable = (
   error: string | null
 }
 
-export const useQuilttResolvable: UseQuilttResolvable = (
-  connectorId,
-  onErrorCallback,
-) => {
+export const useQuilttResolvable: UseQuilttResolvable = (connectorId, onErrorCallback) => {
   const agent = useMemo(() => {
     // Try deprecated navigator.product first (still used in some RN versions)
     if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
@@ -56,16 +53,19 @@ export const useQuilttResolvable: UseQuilttResolvable = (
   const [isResolvable, setIsResolvable] = useState<boolean | null>(null)
   const [error, setError] = useState<string | null>(null)
 
-  const handleError = useCallback(
-    (message: string) => {
-      const errorMessage = message || 'Unknown error occurred while checking resolvability'
+  // Store callback in ref to maintain stable reference
+  const onErrorCallbackRef = useRef(onErrorCallback)
+  useEffect(() => {
+    onErrorCallbackRef.current = onErrorCallback
+  })
 
-      setError(errorMessage)
-      console.error('Quiltt Connector Resolvable Error:', errorMessage)
-      if (onErrorCallback) onErrorCallback(errorMessage)
-    },
-    [onErrorCallback],
-  )
+  const handleError = useCallback((message: string) => {
+    const errorMessage = message || 'Unknown error occurred while checking resolvability'
+
+    setError(errorMessage)
+    console.error('Quiltt Connector Resolvable Error:', errorMessage)
+    if (onErrorCallbackRef.current) onErrorCallbackRef.current(errorMessage)
+  }, [])
 
   const checkResolvable = useCallback(
     async (providerId: {
@@ -75,8 +75,13 @@ export const useQuilttResolvable: UseQuilttResolvable = (
       finicity?: string
       akoya?: string
     }): Promise<boolean | null> => {
-      if (!session?.token || !connectorId) {
-        handleError('Missing session token or connector ID')
+      if (!session?.token) {
+        handleError('Missing session token')
+        return null
+      }
+
+      if (!connectorId) {
+        handleError('Missing connector ID')
         return null
       }
 
@@ -90,11 +95,7 @@ export const useQuilttResolvable: UseQuilttResolvable = (
       setError(null)
 
       try {
-        const response = await connectorsAPI.checkResolvable(
-          session.token,
-          connectorId,
-          providerId,
-        )
+        const response = await connectorsAPI.checkResolvable(session.token, connectorId, providerId)
 
         if (response.status === 200) {
           const result = (response.data as ResolvableData).resolvable
@@ -113,7 +114,7 @@ export const useQuilttResolvable: UseQuilttResolvable = (
         setIsLoading(false)
       }
     },
-    [session?.token, connectorId, connectorsAPI, handleError],
+    [session?.token, connectorId, connectorsAPI, handleError]
   )
 
   return {

package/src/hooks/useQuilttSession.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useCallback } from 'react'
+import { useCallback, useMemo } from 'react'
 
 import type { Maybe, QuilttJWT } from '@quiltt/core'
 import { AuthAPI } from '@quiltt/core'
@@ -28,7 +28,7 @@ export const useQuilttSession: UseQuilttSession = (environmentId) => {
   const { clientId } = useQuilttSettings()
   const [session, setSession] = useSession()
 
-  const auth = new AuthAPI(clientId)
+  const auth = useMemo(() => new AuthAPI(clientId), [clientId])
   const importSession = useImportSession(auth, session, setSession, environmentId)
   const identifySession = useIdentifySession(auth, setSession)
   const authenticateSession = useAuthenticateSession(auth, setSession)

package/src/providers/QuilttProvider.tsx

@@ -1,5 +1,7 @@
 import type { FC } from 'react'
 
+import { QuilttProviderRender } from '@/contexts/QuilttProviderRender'
+
 import type { QuilttAuthProviderProps } from './QuilttAuthProvider'
 import { QuilttAuthProvider } from './QuilttAuthProvider'
 import type { QuilttSettingsProviderProps } from './QuilttSettingsProvider'
@@ -13,12 +15,19 @@ export const QuilttProvider: FC<QuilttProviderProps> = ({
   token,
   children,
 }) => {
+  // Set a context flag that SDK components can check to warn about potential anti-patterns.
+  // LIMITATION: This flags ALL descendants due to React context propagation, not just same-component usage.
+  // Will produce false positives for valid patterns like: <QuilttProvider><MyPage /></QuilttProvider>
+  // where MyPage renders SDK components (which is correct usage).
+  // The flag-based approach is simple but imprecise - a proper solution would require render stack tracking.
   return (
-    <QuilttSettingsProvider clientId={clientId}>
-      <QuilttAuthProvider token={token} graphqlClient={graphqlClient}>
-        {children}
-      </QuilttAuthProvider>
-    </QuilttSettingsProvider>
+    <QuilttProviderRender.Provider value={{ isRenderingProvider: true }}>
+      <QuilttSettingsProvider clientId={clientId}>
+        <QuilttAuthProvider token={token} graphqlClient={graphqlClient}>
+          {children}
+        </QuilttAuthProvider>
+      </QuilttSettingsProvider>
+    </QuilttProviderRender.Provider>
   )
 }