hydrogen-sanity 5.1.3 → 5.3.0

package/dist/_chunks-es/LiveMode.client.js

@@ -1,6 +1,7 @@
 import { createClient } from '@sanity/client';
 import { useLiveMode } from '@sanity/react-loader';
-import { useMemo, useEffect } from 'react';
+import isEqual from 'fast-deep-equal';
+import { useState, useEffect, useMemo } from 'react';
 import { useSanityProviderValue } from './provider.js';
 import { isServer } from './utils.js';
 import { useRefresh } from './refresh.js';
@@ -13,6 +14,12 @@ if (isServer()) {
 function LiveModeClient(props) {
   const { onConnect, onDisconnect, ...stegaProps } = props;
   const sanityProvider = useSanityProviderValue();
+  const [stableStegaProps, setStableStegaProps] = useState(stegaProps);
+  useEffect(() => {
+    if (!isEqual(stableStegaProps, stegaProps)) {
+      setStableStegaProps(stegaProps);
+    }
+  }, [stegaProps]);
   const client = useMemo(() => {
     const baseClient = createClient({
       projectId: sanityProvider.projectId,
@@ -21,11 +28,11 @@ function LiveModeClient(props) {
       apiVersion: sanityProvider.apiVersion,
       useCdn: false
     });
-    if (sanityProvider.stegaEnabled && Object.keys(stegaProps).length > 0) {
+    if (sanityProvider.stegaEnabled && Object.keys(stableStegaProps).length > 0) {
       return baseClient.withConfig({
         stega: {
           enabled: true,
-          ...stegaProps
+          ...stableStegaProps
         }
       });
     }
@@ -36,18 +43,14 @@ function LiveModeClient(props) {
     sanityProvider.perspective,
     sanityProvider.apiVersion,
     sanityProvider.stegaEnabled,
-    // eslint-disable-next-line react-hooks/preserve-manual-memoization
-    stegaProps
+    stableStegaProps
   ]);
   useLiveMode({
     client,
     onConnect,
     onDisconnect
   });
-  const { handleRevalidatorState } = useRefresh();
-  useEffect(() => {
-    handleRevalidatorState();
-  });
+  useRefresh();
   return null;
 }
 

package/dist/_chunks-es/LiveMode.client.js.map

@@ -1 +1 @@
-{"version":3,"file":"LiveMode.client.js","sources":["../../src/visual-editing/LiveMode.client.tsx"],"sourcesContent":["import {createClient, type StegaConfig} from '@sanity/client'\nimport {useLiveMode} from '@sanity/react-loader'\nimport {type ReactNode, useEffect, useMemo} from 'react'\n\nimport {useSanityProviderValue} from '../provider'\nimport {isServer} from '../utils'\nimport {useRefresh} from './hooks/refresh'\n\nexport interface LiveModeProps extends Omit<StegaConfig, 'enabled'> {\n  /**\n   * Fires when a connection is established to the Studio.\n   */\n  onConnect?: () => void\n  /**\n   * Fires when a connection to the Studio is lost.\n   */\n  onDisconnect?: () => void\n}\n\n/**\n * Prevent a consumer from importing into a worker/server bundle.\n */\nif (isServer()) {\n  throw new Error(\n    'LiveMode should only run client-side. Please check that this file is not being imported into a worker or server bundle.',\n  )\n}\n\n/**\n * Enables live data synchronization with Sanity Studio.\n *\n * This component handles:\n * - Real-time data updates via comlink connection to Studio\n * - Perspective changes (draft/published switching)\n * - Connection status with Studio\n *\n * Only use this component when you have client-side loaders (useQuery hooks)\n * that can receive real-time updates. For server-only setups, use only\n * Overlays component.\n *\n * @see https://www.sanity.io/docs/introduction-to-visual-editing\n */\nfunction LiveModeClient(props: LiveModeProps): ReactNode {\n  const {onConnect, onDisconnect, ...stegaProps} = props\n\n  const sanityProvider = useSanityProviderValue()\n\n  // eslint-disable-next-line react-hooks/preserve-manual-memoization\n  const client = useMemo(() => {\n    const baseClient = createClient({\n      projectId: sanityProvider.projectId,\n      dataset: sanityProvider.dataset,\n      perspective: sanityProvider.perspective,\n      apiVersion: sanityProvider.apiVersion,\n      useCdn: false,\n    })\n\n    // Apply stega configuration if provided\n    if (sanityProvider.stegaEnabled && Object.keys(stegaProps).length > 0) {\n      return baseClient.withConfig({\n        stega: {\n          enabled: true,\n          ...stegaProps,\n        },\n      })\n    }\n\n    return baseClient\n  }, [\n    sanityProvider.projectId,\n    sanityProvider.dataset,\n    sanityProvider.perspective,\n    sanityProvider.apiVersion,\n    sanityProvider.stegaEnabled,\n    // eslint-disable-next-line react-hooks/preserve-manual-memoization\n    stegaProps,\n  ])\n\n  // Enable live mode for real-time data updates (client loaders only)\n  useLiveMode({\n    client,\n    onConnect,\n    onDisconnect,\n  })\n\n  // Automatically handle revalidator state changes\n  const {handleRevalidatorState} = useRefresh()\n  useEffect(() => {\n    handleRevalidatorState()\n  })\n\n  return null\n}\n\nexport default LiveModeClient\n"],"names":[],"mappings":";;;;;;;AAsBA,IAAI,UAAS,EAAG;AACd,EAAA,MAAM,IAAI,KAAA;AAAA,IACR;AAAA,GACF;AACF;AAgBA,SAAS,eAAe,KAAA,EAAiC;AACvD,EAAA,MAAM,EAAC,SAAA,EAAW,YAAA,EAAc,GAAG,YAAU,GAAI,KAAA;AAEjD,EAAA,MAAM,iBAAiB,sBAAA,EAAuB;AAG9C,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAM;AAC3B,IAAA,MAAM,aAAa,YAAA,CAAa;AAAA,MAC9B,WAAW,cAAA,CAAe,SAAA;AAAA,MAC1B,SAAS,cAAA,CAAe,OAAA;AAAA,MACxB,aAAa,cAAA,CAAe,WAAA;AAAA,MAC5B,YAAY,cAAA,CAAe,UAAA;AAAA,MAC3B,MAAA,EAAQ;AAAA,KACT,CAAA;AAGD,IAAA,IAAI,eAAe,YAAA,IAAgB,MAAA,CAAO,KAAK,UAAU,CAAA,CAAE,SAAS,CAAA,EAAG;AACrE,MAAA,OAAO,WAAW,UAAA,CAAW;AAAA,QAC3B,KAAA,EAAO;AAAA,UACL,OAAA,EAAS,IAAA;AAAA,UACT,GAAG;AAAA;AACL,OACD,CAAA;AAAA,IACH;AAEA,IAAA,OAAO,UAAA;AAAA,EACT,CAAA,EAAG;AAAA,IACD,cAAA,CAAe,SAAA;AAAA,IACf,cAAA,CAAe,OAAA;AAAA,IACf,cAAA,CAAe,WAAA;AAAA,IACf,cAAA,CAAe,UAAA;AAAA,IACf,cAAA,CAAe,YAAA;AAAA;AAAA,IAEf;AAAA,GACD,CAAA;AAGD,EAAA,WAAA,CAAY;AAAA,IACV,MAAA;AAAA,IACA,SAAA;AAAA,IACA;AAAA,GACD,CAAA;AAGD,EAAA,MAAM,EAAC,sBAAA,EAAsB,GAAI,UAAA,EAAW;AAC5C,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,sBAAA,EAAuB;AAAA,EACzB,CAAC,CAAA;AAED,EAAA,OAAO,IAAA;AACT;;;;"}
+{"version":3,"file":"LiveMode.client.js","sources":["../../src/visual-editing/LiveMode.client.tsx"],"sourcesContent":["import {createClient, type StegaConfig} from '@sanity/client'\nimport {useLiveMode} from '@sanity/react-loader'\nimport isEqual from 'fast-deep-equal'\nimport {type ReactNode, useEffect, useMemo, useState} from 'react'\n\nimport {useSanityProviderValue} from '../provider'\nimport {isServer} from '../utils'\nimport {useRefresh} from './hooks/refresh'\n\nexport interface LiveModeProps extends Omit<StegaConfig, 'enabled'> {\n  /**\n   * Fires when a connection is established to the Studio.\n   */\n  onConnect?: () => void\n  /**\n   * Fires when a connection to the Studio is lost.\n   */\n  onDisconnect?: () => void\n}\n\n/**\n * Prevent a consumer from importing into a worker/server bundle.\n */\nif (isServer()) {\n  throw new Error(\n    'LiveMode should only run client-side. Please check that this file is not being imported into a worker or server bundle.',\n  )\n}\n\n/**\n * Enables live data synchronization with Sanity Studio.\n *\n * This component handles:\n * - Real-time data updates via comlink connection to Studio\n * - Perspective changes (draft/published switching)\n * - Connection status with Studio\n *\n * Only use this component when you have client-side loaders (useQuery hooks)\n * that can receive real-time updates. For server-only setups, use only\n * Overlays component.\n *\n * @see https://www.sanity.io/docs/introduction-to-visual-editing\n */\nfunction LiveModeClient(props: LiveModeProps): ReactNode {\n  const {onConnect, onDisconnect, ...stegaProps} = props\n\n  const sanityProvider = useSanityProviderValue()\n\n  // Maintain reference stability for stegaProps when content is unchanged\n  // This prevents unnecessary client recreation when parent component re-renders\n  const [stableStegaProps, setStableStegaProps] = useState(stegaProps)\n  useEffect(() => {\n    if (!isEqual(stableStegaProps, stegaProps)) {\n      setStableStegaProps(stegaProps)\n    }\n    // Intentionally not including stableStegaProps in deps - we only want to\n    // update when the incoming stegaProps changes, comparing against the stored value\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [stegaProps])\n\n  const client = useMemo(() => {\n    const baseClient = createClient({\n      projectId: sanityProvider.projectId,\n      dataset: sanityProvider.dataset,\n      perspective: sanityProvider.perspective,\n      apiVersion: sanityProvider.apiVersion,\n      useCdn: false,\n    })\n\n    // Apply stega configuration if provided\n    if (sanityProvider.stegaEnabled && Object.keys(stableStegaProps).length > 0) {\n      return baseClient.withConfig({\n        stega: {\n          enabled: true,\n          ...stableStegaProps,\n        },\n      })\n    }\n\n    return baseClient\n  }, [\n    sanityProvider.projectId,\n    sanityProvider.dataset,\n    sanityProvider.perspective,\n    sanityProvider.apiVersion,\n    sanityProvider.stegaEnabled,\n    stableStegaProps,\n  ])\n\n  // Enable live mode for real-time data updates (client loaders only)\n  useLiveMode({\n    client,\n    onConnect,\n    onDisconnect,\n  })\n\n  // Initialize refresh hook to handle revalidator state transitions\n  // The hook internally manages state changes via useEffect\n  useRefresh()\n\n  return null\n}\n\nexport default LiveModeClient\n"],"names":[],"mappings":";;;;;;;;AAuBA,IAAI,UAAS,EAAG;AACd,EAAA,MAAM,IAAI,KAAA;AAAA,IACR;AAAA,GACF;AACF;AAgBA,SAAS,eAAe,KAAA,EAAiC;AACvD,EAAA,MAAM,EAAC,SAAA,EAAW,YAAA,EAAc,GAAG,YAAU,GAAI,KAAA;AAEjD,EAAA,MAAM,iBAAiB,sBAAA,EAAuB;AAI9C,EAAA,MAAM,CAAC,gBAAA,EAAkB,mBAAmB,CAAA,GAAI,SAAS,UAAU,CAAA;AACnE,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,CAAC,OAAA,CAAQ,gBAAA,EAAkB,UAAU,CAAA,EAAG;AAC1C,MAAA,mBAAA,CAAoB,UAAU,CAAA;AAAA,IAChC;AAAA,EAIF,CAAA,EAAG,CAAC,UAAU,CAAC,CAAA;AAEf,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAM;AAC3B,IAAA,MAAM,aAAa,YAAA,CAAa;AAAA,MAC9B,WAAW,cAAA,CAAe,SAAA;AAAA,MAC1B,SAAS,cAAA,CAAe,OAAA;AAAA,MACxB,aAAa,cAAA,CAAe,WAAA;AAAA,MAC5B,YAAY,cAAA,CAAe,UAAA;AAAA,MAC3B,MAAA,EAAQ;AAAA,KACT,CAAA;AAGD,IAAA,IAAI,eAAe,YAAA,IAAgB,MAAA,CAAO,KAAK,gBAAgB,CAAA,CAAE,SAAS,CAAA,EAAG;AAC3E,MAAA,OAAO,WAAW,UAAA,CAAW;AAAA,QAC3B,KAAA,EAAO;AAAA,UACL,OAAA,EAAS,IAAA;AAAA,UACT,GAAG;AAAA;AACL,OACD,CAAA;AAAA,IACH;AAEA,IAAA,OAAO,UAAA;AAAA,EACT,CAAA,EAAG;AAAA,IACD,cAAA,CAAe,SAAA;AAAA,IACf,cAAA,CAAe,OAAA;AAAA,IACf,cAAA,CAAe,WAAA;AAAA,IACf,cAAA,CAAe,UAAA;AAAA,IACf,cAAA,CAAe,YAAA;AAAA,IACf;AAAA,GACD,CAAA;AAGD,EAAA,WAAA,CAAY;AAAA,IACV,MAAA;AAAA,IACA,SAAA;AAAA,IACA;AAAA,GACD,CAAA;AAID,EAAA,UAAA,EAAW;AAEX,EAAA,OAAO,IAAA;AACT;;;;"}

package/dist/_chunks-es/Overlays.client.js

@@ -3,7 +3,7 @@ import { enableVisualEditing } from '@sanity/visual-editing';
 import { useRef, useState, useEffect, useMemo } from 'react';
 import { useNavigate, useLocation, useSubmit, useRevalidator } from 'react-router';
 import { useEffectEvent } from 'use-effect-event';
-import { isServer } from './utils.js';
+import { isServer, sanitizePerspective } from './utils.js';
 import { useRefresh } from './refresh.js';
 import { useHasActiveLoaders } from './registry.js';
 
@@ -12,16 +12,18 @@ function useHistory() {
   const navigateRemixRef = useRef(navigateRemix);
   const [navigate, setNavigate] = useState();
   const location = useLocation();
+  const isProgrammaticNavRef = useRef(false);
   useEffect(() => {
     navigateRemixRef.current = navigateRemix;
   }, [navigateRemix]);
   useEffect(() => {
-    if (navigate) {
+    if (navigate && !isProgrammaticNavRef.current) {
       navigate({
         type: "push",
         url: `${location.pathname}${location.search}${location.hash}`
       });
     }
+    isProgrammaticNavRef.current = false;
   }, [location.hash, location.pathname, location.search, navigate]);
   const historyAdapter = useMemo(
     () => ({
@@ -30,6 +32,7 @@ function useHistory() {
         return () => setNavigate(void 0);
       },
       update(update) {
+        isProgrammaticNavRef.current = true;
         if (update.type === "push" || update.type === "replace") {
           navigateRemixRef.current(update.url, {
             replace: update.type === "replace"
@@ -64,8 +67,12 @@ function OverlaysClient(props) {
     return isMaybePresentation();
   });
   const handlePerspectiveChange = useEffectEvent((perspective) => {
+    const cleanPerspective = sanitizePerspective(perspective);
     const formData = new FormData();
-    formData.set("perspective", Array.isArray(perspective) ? perspective.join(",") : perspective);
+    formData.set(
+      "perspective",
+      Array.isArray(cleanPerspective) ? cleanPerspective.join(",") : cleanPerspective
+    );
     submit(formData, {
       method: "PUT",
       action,

package/dist/_chunks-es/Overlays.client.js.map

@@ -1 +1 @@
-{"version":3,"file":"Overlays.client.js","sources":["../../src/visual-editing/hooks/history.ts","../../src/visual-editing/Overlays.client.tsx"],"sourcesContent":["import type {HistoryAdapter, HistoryAdapterNavigate, HistoryUpdate} from '@sanity/visual-editing'\nimport {useEffect, useMemo, useRef, useState} from 'react'\nimport {useLocation, useNavigate} from 'react-router'\n\n/**\n * Hook that provides history management for visual editing.\n * Integrates with React Router's navigation for Studio-storefront communication.\n */\nexport function useHistory(): HistoryAdapter {\n  const navigateRemix = useNavigate()\n  const navigateRemixRef = useRef(navigateRemix)\n  const [navigate, setNavigate] = useState<HistoryAdapterNavigate | undefined>()\n  const location = useLocation()\n\n  useEffect(() => {\n    navigateRemixRef.current = navigateRemix\n  }, [navigateRemix])\n\n  useEffect(() => {\n    if (navigate) {\n      navigate({\n        type: 'push',\n        url: `${location.pathname}${location.search}${location.hash}`,\n      })\n    }\n  }, [location.hash, location.pathname, location.search, navigate])\n\n  const historyAdapter: HistoryAdapter = useMemo(\n    () => ({\n      subscribe(_navigate: HistoryAdapterNavigate) {\n        setNavigate(() => _navigate)\n        return () => setNavigate(undefined)\n      },\n      update(update: HistoryUpdate) {\n        if (update.type === 'push' || update.type === 'replace') {\n          navigateRemixRef.current(update.url, {\n            replace: update.type === 'replace',\n          })\n        } else if (update.type === 'pop') {\n          navigateRemixRef.current(-1)\n        }\n      },\n    }),\n    [],\n  )\n\n  return historyAdapter\n}\n","import {type ClientPerspective} from '@sanity/client'\nimport {isMaybePresentation} from '@sanity/presentation-comlink'\nimport {\n  enableVisualEditing,\n  type HistoryRefresh,\n  type OverlayComponentResolver,\n} from '@sanity/visual-editing'\nimport {type ReactNode, useEffect, useState} from 'react'\nimport {useRevalidator, useSubmit} from 'react-router'\nimport {useEffectEvent} from 'use-effect-event'\n\nimport {isServer} from '../utils'\nimport {useHistory} from './hooks/history'\nimport {useRefresh} from './hooks/refresh'\nimport {useHasActiveLoaders} from './registry'\nimport type {Revalidator} from './types'\n\nexport interface OverlaysProps {\n  /**\n   * Custom overlay components for visual editing.\n   */\n  components?: OverlayComponentResolver\n  /**\n   * The CSS z-index for visual editing overlays.\n   */\n  zIndex?: string | number\n  /**\n   * Custom refresh logic. Called when content changes.\n   */\n  refresh?: (\n    payload: HistoryRefresh,\n    refreshDefault: () => false | Promise<void>,\n    revalidator: Revalidator,\n  ) => false | Promise<void>\n  /**\n   * The action URL path used to submit perspective changes.\n   */\n  action?: string\n}\n\n/**\n * Prevent a consumer from importing into a worker/server bundle.\n */\nif (isServer()) {\n  throw new Error(\n    'Overlays should only run client-side. Please check that this file is not being imported into a worker or server bundle.',\n  )\n}\n\n/**\n * Enables visual editing overlays and click-to-edit functionality.\n *\n * This component handles:\n * - Visual overlays for click-to-edit\n * - Element highlighting and interactions\n * - Perspective changes from Studio\n * - Server revalidation for content changes\n *\n * For real-time data synchronization with Studio, also use LiveMode component.\n *\n * @see https://www.sanity.io/docs/introduction-to-visual-editing\n */\nfunction OverlaysClient(props: OverlaysProps): ReactNode {\n  const {components, zIndex, refresh, action = '/api/preview'} = props\n\n  const submit = useSubmit()\n  const revalidator = useRevalidator()\n  const {refreshHandler} = useRefresh()\n  const refreshFn = refreshHandler(refresh)\n  const historyAdapter = useHistory()\n  const hasActiveLoaders = useHasActiveLoaders()\n\n  // Detect if we're in a Studio presentation context (lazy initialization for SSR safety)\n  const [inStudioContext] = useState<boolean | null>(() => {\n    // Only run on client-side to avoid SSR mismatch\n    if (isServer()) {\n      return null\n    }\n\n    return isMaybePresentation()\n  })\n\n  // Handle perspective changes from Studio\n  const handlePerspectiveChange = useEffectEvent((perspective: ClientPerspective) => {\n    const formData = new FormData()\n    formData.set('perspective', Array.isArray(perspective) ? perspective.join(',') : perspective)\n    submit(formData, {\n      method: 'PUT',\n      action,\n      navigate: false,\n      preventScrollReset: true,\n    })\n\n    // Always trigger refresh for perspective changes (server revalidation needed)\n    refreshFn({\n      source: 'manual',\n      livePreviewEnabled: false, // Force server revalidation for perspective changes\n    } as const)\n  })\n\n  const handleRefresh = useEffectEvent((payload: HistoryRefresh): false | Promise<void> => {\n    // Prioritize userland refresh function if provided\n    if (refresh) {\n      return refresh(payload, () => refreshFn(payload), revalidator)\n    }\n\n    switch (payload.source) {\n      case 'manual':\n        // Always handle manual refresh events (like perspective changes)\n        return refreshFn(payload)\n\n      default:\n        // For other refresh events, check if active loaders should handle them\n        if (hasActiveLoaders) {\n          return false // Let client loaders handle mutations (live mode active)\n        }\n        return refreshFn(payload) // Server revalidation for server-only setups\n    }\n  })\n\n  // Listen for presentation events from Studio (only perspective changes needed for server revalidation)\n  useEffect(() => {\n    if (isServer() || !inStudioContext) return undefined\n\n    const handleMessage = (event: MessageEvent) => {\n      const {type, data} = event.data || {}\n\n      // Only handle perspective changes - let enableVisualEditing handle refresh events\n      if (type === 'presentation/perspective') {\n        handlePerspectiveChange(data.perspective)\n      }\n    }\n\n    window.addEventListener('message', handleMessage)\n\n    return () => {\n      window.removeEventListener('message', handleMessage)\n    }\n  }, [inStudioContext])\n\n  // Enable visual editing overlays and interactions\n  useEffect(() => {\n    const disable = enableVisualEditing({\n      components,\n      zIndex,\n      refresh: handleRefresh,\n      history: historyAdapter,\n    })\n\n    return () => disable()\n  }, [components, zIndex, historyAdapter])\n\n  return null\n}\n\nexport default OverlaysClient\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"Overlays.client.js","sources":["../../src/visual-editing/hooks/history.ts","../../src/visual-editing/Overlays.client.tsx"],"sourcesContent":["import type {HistoryAdapter, HistoryAdapterNavigate, HistoryUpdate} from '@sanity/visual-editing'\nimport {useEffect, useMemo, useRef, useState} from 'react'\nimport {useLocation, useNavigate} from 'react-router'\n\n/**\n * Hook that provides history management for visual editing.\n * Integrates with React Router's navigation for Studio-storefront communication.\n */\nexport function useHistory(): HistoryAdapter {\n  const navigateRemix = useNavigate()\n  const navigateRemixRef = useRef(navigateRemix)\n  const [navigate, setNavigate] = useState<HistoryAdapterNavigate | undefined>()\n  const location = useLocation()\n  // Track programmatic navigations to avoid duplicate notifications to Studio\n  const isProgrammaticNavRef = useRef(false)\n\n  useEffect(() => {\n    navigateRemixRef.current = navigateRemix\n  }, [navigateRemix])\n\n  useEffect(() => {\n    // Skip notification for programmatic navigations (initiated by Studio)\n    // to avoid duplicate notifications and potential infinite loops\n    if (navigate && !isProgrammaticNavRef.current) {\n      navigate({\n        type: 'push',\n        url: `${location.pathname}${location.search}${location.hash}`,\n      })\n    }\n    isProgrammaticNavRef.current = false\n  }, [location.hash, location.pathname, location.search, navigate])\n\n  const historyAdapter: HistoryAdapter = useMemo(\n    () => ({\n      subscribe(_navigate: HistoryAdapterNavigate) {\n        setNavigate(() => _navigate)\n        return () => setNavigate(undefined)\n      },\n      update(update: HistoryUpdate) {\n        // Mark as programmatic navigation to skip notification in the location effect\n        isProgrammaticNavRef.current = true\n        if (update.type === 'push' || update.type === 'replace') {\n          navigateRemixRef.current(update.url, {\n            replace: update.type === 'replace',\n          })\n        } else if (update.type === 'pop') {\n          navigateRemixRef.current(-1)\n        }\n      },\n    }),\n    [],\n  )\n\n  return historyAdapter\n}\n","import {type ClientPerspective} from '@sanity/client'\nimport {isMaybePresentation} from '@sanity/presentation-comlink'\nimport {\n  enableVisualEditing,\n  type HistoryRefresh,\n  type OverlayComponentResolver,\n} from '@sanity/visual-editing'\nimport {type ReactNode, useEffect, useState} from 'react'\nimport {useRevalidator, useSubmit} from 'react-router'\nimport {useEffectEvent} from 'use-effect-event'\n\nimport {isServer, sanitizePerspective} from '../utils'\nimport {useHistory} from './hooks/history'\nimport {useRefresh} from './hooks/refresh'\nimport {useHasActiveLoaders} from './registry'\nimport type {Revalidator} from './types'\n\nexport interface OverlaysProps {\n  /**\n   * Custom overlay components for visual editing.\n   */\n  components?: OverlayComponentResolver\n  /**\n   * The CSS z-index for visual editing overlays.\n   */\n  zIndex?: string | number\n  /**\n   * Custom refresh logic. Called when content changes.\n   */\n  refresh?: (\n    payload: HistoryRefresh,\n    refreshDefault: () => false | Promise<void>,\n    revalidator: Revalidator,\n  ) => false | Promise<void>\n  /**\n   * The action URL path used to submit perspective changes.\n   */\n  action?: string\n}\n\n/**\n * Prevent a consumer from importing into a worker/server bundle.\n */\nif (isServer()) {\n  throw new Error(\n    'Overlays should only run client-side. Please check that this file is not being imported into a worker or server bundle.',\n  )\n}\n\n/**\n * Enables visual editing overlays and click-to-edit functionality.\n *\n * This component handles:\n * - Visual overlays for click-to-edit\n * - Element highlighting and interactions\n * - Perspective changes from Studio\n * - Server revalidation for content changes\n *\n * For real-time data synchronization with Studio, also use LiveMode component.\n *\n * @see https://www.sanity.io/docs/introduction-to-visual-editing\n */\nfunction OverlaysClient(props: OverlaysProps): ReactNode {\n  const {components, zIndex, refresh, action = '/api/preview'} = props\n\n  const submit = useSubmit()\n  const revalidator = useRevalidator()\n  const {refreshHandler} = useRefresh()\n  const refreshFn = refreshHandler(refresh)\n  const historyAdapter = useHistory()\n  const hasActiveLoaders = useHasActiveLoaders()\n\n  // Detect if we're in a Studio presentation context (lazy initialization for SSR safety)\n  const [inStudioContext] = useState<boolean | null>(() => {\n    // Only run on client-side to avoid SSR mismatch\n    if (isServer()) {\n      return null\n    }\n\n    return isMaybePresentation()\n  })\n\n  // Handle perspective changes from Studio\n  const handlePerspectiveChange = useEffectEvent((perspective: ClientPerspective) => {\n    // Sanitize perspective (filters out undefined/empty values from upstream bug)\n    const cleanPerspective = sanitizePerspective(perspective)\n\n    const formData = new FormData()\n    formData.set(\n      'perspective',\n      Array.isArray(cleanPerspective) ? cleanPerspective.join(',') : cleanPerspective,\n    )\n    submit(formData, {\n      method: 'PUT',\n      action,\n      navigate: false,\n      preventScrollReset: true,\n    })\n\n    // Always trigger refresh for perspective changes (server revalidation needed)\n    refreshFn({\n      source: 'manual',\n      livePreviewEnabled: false, // Force server revalidation for perspective changes\n    } as const)\n  })\n\n  const handleRefresh = useEffectEvent((payload: HistoryRefresh): false | Promise<void> => {\n    // Prioritize userland refresh function if provided\n    if (refresh) {\n      return refresh(payload, () => refreshFn(payload), revalidator)\n    }\n\n    switch (payload.source) {\n      case 'manual':\n        // Always handle manual refresh events (like perspective changes)\n        return refreshFn(payload)\n\n      default:\n        // For other refresh events, check if active loaders should handle them\n        if (hasActiveLoaders) {\n          return false // Let client loaders handle mutations (live mode active)\n        }\n        return refreshFn(payload) // Server revalidation for server-only setups\n    }\n  })\n\n  // Listen for presentation events from Studio (only perspective changes needed for server revalidation)\n  useEffect(() => {\n    if (isServer() || !inStudioContext) return undefined\n\n    const handleMessage = (event: MessageEvent) => {\n      const {type, data} = event.data || {}\n\n      // Only handle perspective changes - let enableVisualEditing handle refresh events\n      if (type === 'presentation/perspective') {\n        handlePerspectiveChange(data.perspective)\n      }\n    }\n\n    window.addEventListener('message', handleMessage)\n\n    return () => {\n      window.removeEventListener('message', handleMessage)\n    }\n  }, [inStudioContext])\n\n  // Enable visual editing overlays and interactions\n  useEffect(() => {\n    const disable = enableVisualEditing({\n      components,\n      zIndex,\n      refresh: handleRefresh,\n      history: historyAdapter,\n    })\n\n    return () => disable()\n  }, [components, zIndex, historyAdapter])\n\n  return null\n}\n\nexport default OverlaysClient\n"],"names":[],"mappings":"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"}

package/dist/_chunks-es/refresh.js

@@ -1,19 +1,25 @@
-import { useState, useCallback } from 'react';
+import { useState, startTransition, useEffect, useCallback } from 'react';
 import { useRevalidator } from 'react-router';
+import { useEffectEvent } from 'use-effect-event';
 
 function useRefresh() {
   const revalidator = useRevalidator();
   const [revalidatorPromise, setRevalidatorPromise] = useState(null);
   const [revalidatorLoading, setRevalidatorLoading] = useState(false);
-  const handleRevalidatorState = useCallback(() => {
+  const handleRevalidatorState = useEffectEvent(() => {
     if (revalidatorPromise && revalidator.state === "loading") {
-      setRevalidatorLoading(true);
+      startTransition(() => setRevalidatorLoading(true));
     } else if (revalidatorPromise && revalidatorLoading && revalidator.state === "idle") {
       revalidatorPromise();
-      setRevalidatorPromise(null);
-      setRevalidatorLoading(false);
+      startTransition(() => {
+        setRevalidatorPromise(null);
+        setRevalidatorLoading(false);
+      });
     }
-  }, [revalidatorLoading, revalidator.state, revalidatorPromise]);
+  });
+  useEffect(() => {
+    handleRevalidatorState();
+  }, [revalidator.state]);
   const createRefreshHandler = useCallback(
     (customRefresh) => {
       return (payload) => {
@@ -32,9 +38,7 @@ function useRefresh() {
     [revalidator]
   );
   return {
-    refreshHandler: createRefreshHandler,
-    handleRevalidatorState,
-    revalidatorState: revalidator.state
+    refreshHandler: createRefreshHandler
   };
 }
 

package/dist/_chunks-es/refresh.js.map

@@ -1 +1 @@
-{"version":3,"file":"refresh.js","sources":["../../src/visual-editing/hooks/refresh.ts"],"sourcesContent":["import type {HistoryRefresh} from '@sanity/visual-editing'\nimport {useCallback, useState} from 'react'\nimport {useRevalidator} from 'react-router'\n\nimport type {Revalidator} from '../types'\n\n/**\n * Hook that provides refresh logic for visual editing.\n * Integrates with React Router's revalidator for optimal data refetching.\n */\nexport function useRefresh(): {\n  refreshHandler: (\n    customRefresh?: (\n      payload: HistoryRefresh,\n      refreshDefault: () => false | Promise<void>,\n      revalidator: Revalidator,\n    ) => false | Promise<void>,\n  ) => (payload: HistoryRefresh) => false | Promise<void>\n  handleRevalidatorState: () => void\n  revalidatorState: Revalidator['state']\n} {\n  const revalidator = useRevalidator()\n  const [revalidatorPromise, setRevalidatorPromise] = useState<(() => void) | null>(null)\n  const [revalidatorLoading, setRevalidatorLoading] = useState(false)\n\n  const handleRevalidatorState = useCallback(() => {\n    if (revalidatorPromise && revalidator.state === 'loading') {\n      setRevalidatorLoading(true)\n    } else if (revalidatorPromise && revalidatorLoading && revalidator.state === 'idle') {\n      revalidatorPromise()\n      setRevalidatorPromise(null)\n      setRevalidatorLoading(false)\n    }\n  }, [revalidatorLoading, revalidator.state, revalidatorPromise])\n\n  const createRefreshHandler = useCallback(\n    (\n      customRefresh?: (\n        payload: HistoryRefresh,\n        refreshDefault: () => false | Promise<void>,\n        revalidator: Revalidator,\n      ) => false | Promise<void>,\n    ) => {\n      return (payload: HistoryRefresh) => {\n        function refreshDefault() {\n          // Only skip revalidation for mutations when client loaders are active\n          if (payload.source === 'mutation' && payload.livePreviewEnabled) {\n            // Client loaders (useQuery) will handle the update via comlink\n            return false\n          }\n\n          // All other cases: revalidate\n          // - Manual refreshes (user explicitly requested refresh)\n          // - Mutations without client loaders (server-only setup needs revalidation)\n          // - Unknown source types (fallback to revalidate for safety)\n          return new Promise<void>((resolve) => {\n            revalidator.revalidate()\n            setRevalidatorPromise(() => resolve)\n          })\n        }\n\n        return customRefresh\n          ? customRefresh(payload, refreshDefault, revalidator)\n          : refreshDefault()\n      }\n    },\n    [revalidator],\n  )\n\n  return {\n    refreshHandler: createRefreshHandler,\n    handleRevalidatorState,\n    revalidatorState: revalidator.state,\n  }\n}\n"],"names":[],"mappings":";;;AAUO,SAAS,UAAA,GAUd;AACA,EAAA,MAAM,cAAc,cAAA,EAAe;AACnC,EAAA,MAAM,CAAC,kBAAA,EAAoB,qBAAqB,CAAA,GAAI,SAA8B,IAAI,CAAA;AACtF,EAAA,MAAM,CAAC,kBAAA,EAAoB,qBAAqB,CAAA,GAAI,SAAS,KAAK,CAAA;AAElE,EAAA,MAAM,sBAAA,GAAyB,YAAY,MAAM;AAC/C,IAAA,IAAI,kBAAA,IAAsB,WAAA,CAAY,KAAA,KAAU,SAAA,EAAW;AACzD,MAAA,qBAAA,CAAsB,IAAI,CAAA;AAAA,IAC5B,CAAA,MAAA,IAAW,kBAAA,IAAsB,kBAAA,IAAsB,WAAA,CAAY,UAAU,MAAA,EAAQ;AACnF,MAAA,kBAAA,EAAmB;AACnB,MAAA,qBAAA,CAAsB,IAAI,CAAA;AAC1B,MAAA,qBAAA,CAAsB,KAAK,CAAA;AAAA,IAC7B;AAAA,EACF,GAAG,CAAC,kBAAA,EAAoB,WAAA,CAAY,KAAA,EAAO,kBAAkB,CAAC,CAAA;AAE9D,EAAA,MAAM,oBAAA,GAAuB,WAAA;AAAA,IAC3B,CACE,aAAA,KAKG;AACH,MAAA,OAAO,CAAC,OAAA,KAA4B;AAClC,QAAA,SAAS,cAAA,GAAiB;AAExB,UAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,UAAA,IAAc,OAAA,CAAQ,kBAAA,EAAoB;AAE/D,YAAA,OAAO,KAAA;AAAA,UACT;AAMA,UAAA,OAAO,IAAI,OAAA,CAAc,CAAC,OAAA,KAAY;AACpC,YAAA,WAAA,CAAY,UAAA,EAAW;AACvB,YAAA,qBAAA,CAAsB,MAAM,OAAO,CAAA;AAAA,UACrC,CAAC,CAAA;AAAA,QACH;AAEA,QAAA,OAAO,gBACH,aAAA,CAAc,OAAA,EAAS,cAAA,EAAgB,WAAW,IAClD,cAAA,EAAe;AAAA,MACrB,CAAA;AAAA,IACF,CAAA;AAAA,IACA,CAAC,WAAW;AAAA,GACd;AAEA,EAAA,OAAO;AAAA,IACL,cAAA,EAAgB,oBAAA;AAAA,IAChB,sBAAA;AAAA,IACA,kBAAkB,WAAA,CAAY;AAAA,GAChC;AACF;;;;"}
+{"version":3,"file":"refresh.js","sources":["../../src/visual-editing/hooks/refresh.ts"],"sourcesContent":["import type {HistoryRefresh} from '@sanity/visual-editing'\nimport {startTransition, useCallback, useEffect, useState} from 'react'\nimport {useRevalidator} from 'react-router'\nimport {useEffectEvent} from 'use-effect-event'\n\nimport type {Revalidator} from '../types'\n\n/**\n * Hook that provides refresh logic for visual editing.\n * Integrates with React Router's revalidator for optimal data refetching.\n */\nexport function useRefresh(): {\n  refreshHandler: (\n    customRefresh?: (\n      payload: HistoryRefresh,\n      refreshDefault: () => false | Promise<void>,\n      revalidator: Revalidator,\n    ) => false | Promise<void>,\n  ) => (payload: HistoryRefresh) => false | Promise<void>\n} {\n  const revalidator = useRevalidator()\n  const [revalidatorPromise, setRevalidatorPromise] = useState<(() => void) | null>(null)\n  const [revalidatorLoading, setRevalidatorLoading] = useState(false)\n\n  // Handle revalidator state transitions internally\n  const handleRevalidatorState = useEffectEvent(() => {\n    if (revalidatorPromise && revalidator.state === 'loading') {\n      startTransition(() => setRevalidatorLoading(true))\n    } else if (revalidatorPromise && revalidatorLoading && revalidator.state === 'idle') {\n      revalidatorPromise()\n      startTransition(() => {\n        setRevalidatorPromise(null)\n        setRevalidatorLoading(false)\n      })\n    }\n  })\n\n  // Automatically handle revalidator state changes\n  useEffect(() => {\n    handleRevalidatorState()\n  }, [revalidator.state])\n\n  const createRefreshHandler = useCallback(\n    (\n      customRefresh?: (\n        payload: HistoryRefresh,\n        refreshDefault: () => false | Promise<void>,\n        revalidator: Revalidator,\n      ) => false | Promise<void>,\n    ) => {\n      return (payload: HistoryRefresh) => {\n        function refreshDefault() {\n          // Only skip revalidation for mutations when client loaders are active\n          if (payload.source === 'mutation' && payload.livePreviewEnabled) {\n            // Client loaders (useQuery) will handle the update via comlink\n            return false\n          }\n\n          // All other cases: revalidate\n          // - Manual refreshes (user explicitly requested refresh)\n          // - Mutations without client loaders (server-only setup needs revalidation)\n          // - Unknown source types (fallback to revalidate for safety)\n          return new Promise<void>((resolve) => {\n            revalidator.revalidate()\n            setRevalidatorPromise(() => resolve)\n          })\n        }\n\n        return customRefresh\n          ? customRefresh(payload, refreshDefault, revalidator)\n          : refreshDefault()\n      }\n    },\n    [revalidator],\n  )\n\n  return {\n    refreshHandler: createRefreshHandler,\n  }\n}\n"],"names":[],"mappings":";;;;AAWO,SAAS,UAAA,GAQd;AACA,EAAA,MAAM,cAAc,cAAA,EAAe;AACnC,EAAA,MAAM,CAAC,kBAAA,EAAoB,qBAAqB,CAAA,GAAI,SAA8B,IAAI,CAAA;AACtF,EAAA,MAAM,CAAC,kBAAA,EAAoB,qBAAqB,CAAA,GAAI,SAAS,KAAK,CAAA;AAGlE,EAAA,MAAM,sBAAA,GAAyB,eAAe,MAAM;AAClD,IAAA,IAAI,kBAAA,IAAsB,WAAA,CAAY,KAAA,KAAU,SAAA,EAAW;AACzD,MAAA,eAAA,CAAgB,MAAM,qBAAA,CAAsB,IAAI,CAAC,CAAA;AAAA,IACnD,CAAA,MAAA,IAAW,kBAAA,IAAsB,kBAAA,IAAsB,WAAA,CAAY,UAAU,MAAA,EAAQ;AACnF,MAAA,kBAAA,EAAmB;AACnB,MAAA,eAAA,CAAgB,MAAM;AACpB,QAAA,qBAAA,CAAsB,IAAI,CAAA;AAC1B,QAAA,qBAAA,CAAsB,KAAK,CAAA;AAAA,MAC7B,CAAC,CAAA;AAAA,IACH;AAAA,EACF,CAAC,CAAA;AAGD,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,sBAAA,EAAuB;AAAA,EACzB,CAAA,EAAG,CAAC,WAAA,CAAY,KAAK,CAAC,CAAA;AAEtB,EAAA,MAAM,oBAAA,GAAuB,WAAA;AAAA,IAC3B,CACE,aAAA,KAKG;AACH,MAAA,OAAO,CAAC,OAAA,KAA4B;AAClC,QAAA,SAAS,cAAA,GAAiB;AAExB,UAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,UAAA,IAAc,OAAA,CAAQ,kBAAA,EAAoB;AAE/D,YAAA,OAAO,KAAA;AAAA,UACT;AAMA,UAAA,OAAO,IAAI,OAAA,CAAc,CAAC,OAAA,KAAY;AACpC,YAAA,WAAA,CAAY,UAAA,EAAW;AACvB,YAAA,qBAAA,CAAsB,MAAM,OAAO,CAAA;AAAA,UACrC,CAAC,CAAA;AAAA,QACH;AAEA,QAAA,OAAO,gBACH,aAAA,CAAc,OAAA,EAAS,cAAA,EAAgB,WAAW,IAClD,cAAA,EAAe;AAAA,MACrB,CAAA;AAAA,IACF,CAAA;AAAA,IACA,CAAC,WAAW;AAAA,GACd;AAEA,EAAA,OAAO;AAAA,IACL,cAAA,EAAgB;AAAA,GAClB;AACF;;;;"}

package/dist/_chunks-es/utils.js

@@ -1,4 +1,5 @@
 import { validateApiPerspective } from '@sanity/client';
+import { urlSearchParamPreviewPerspective } from '@sanity/preview-url-secret/constants';
 
 async function sha256(message) {
   const messageBuffer = await new TextEncoder().encode(message);
@@ -13,7 +14,12 @@ function hashQuery(query, params) {
   return sha256(hash);
 }
 function sanitizePerspective(perspective) {
-  const sanitizedPerspective = typeof perspective === "string" && perspective.includes(",") ? perspective.split(",") : perspective;
+  let sanitizedPerspective = typeof perspective === "string" && perspective.includes(",") ? perspective.split(",") : perspective;
+  if (Array.isArray(sanitizedPerspective)) {
+    sanitizedPerspective = sanitizedPerspective.filter(
+      (p) => typeof p === "string" && p.length > 0
+    );
+  }
   validateApiPerspective(sanitizedPerspective);
   return sanitizedPerspective === "raw" ? "drafts" : sanitizedPerspective;
 }
@@ -27,10 +33,20 @@ function supportsPerspectiveStack(apiVersion) {
   return versionDate >= cutoffDate;
 }
 function getPerspective(session) {
-  const perspective = session.get("perspective")?.split(",");
+  const perspective = session.get("perspective")?.split(",").filter((p) => p.length > 0);
   validateApiPerspective(perspective);
   return perspective;
 }
+function getPerspectiveFromUrl(url) {
+  try {
+    const parsed = typeof url === "string" ? new URL(url) : url;
+    const param = parsed.searchParams.get(urlSearchParamPreviewPerspective);
+    if (!param) return void 0;
+    return sanitizePerspective(param);
+  } catch {
+    return void 0;
+  }
+}
 function isSanityPreviewSession(session) {
   return isHydrogenSession(session) && "has" in session && typeof session.has === "function" && "destroy" in session && typeof session.destroy === "function";
 }
@@ -41,5 +57,5 @@ function isServer() {
   return typeof document === "undefined";
 }
 
-export { getPerspective, hashQuery, isHydrogenSession, isSanityPreviewSession, isServer, sanitizePerspective, supportsPerspectiveStack };
+export { getPerspective, getPerspectiveFromUrl, hashQuery, isHydrogenSession, isSanityPreviewSession, isServer, sanitizePerspective, supportsPerspectiveStack };
 //# sourceMappingURL=utils.js.map

package/dist/_chunks-es/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["import {\n  type ClientPerspective,\n  type QueryParams,\n  type QueryWithoutParams,\n  validateApiPerspective,\n} from '@sanity/client'\nimport type {HydrogenSession} from '@shopify/hydrogen'\n\nimport type {SanityPreviewSession} from './preview/session'\n\n/**\n * Create an SHA-256 hash as a hex string\n * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest#converting_a_digest_to_a_hex_string\n */\nexport async function sha256(message: string): Promise<string> {\n  // encode as UTF-8\n  const messageBuffer = await new TextEncoder().encode(message)\n  // hash the message\n  const hashBuffer = await crypto.subtle.digest('SHA-256', messageBuffer)\n  // convert bytes to hex string\n  return Array.from(new Uint8Array(hashBuffer))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n/**\n * Hash query and its parameters for use as cache key.\n * NOTE: Oxygen deployment will break if the cache key is long or contains `\\n`\n */\nexport function hashQuery(\n  query: string,\n  params: QueryParams | QueryWithoutParams,\n): Promise<string> {\n  let hash = query\n\n  if (params) {\n    hash += JSON.stringify(params)\n  }\n\n  return sha256(hash)\n}\n\n/**\n * Sanitizes and validates a perspective value.\n * Handles both string (comma-separated) and array formats.\n */\nexport function sanitizePerspective(perspective: unknown): Exclude<ClientPerspective, 'raw'> {\n  const sanitizedPerspective =\n    typeof perspective === 'string' && perspective.includes(',')\n      ? perspective.split(',')\n      : perspective\n\n  validateApiPerspective(sanitizedPerspective)\n\n  return sanitizedPerspective === 'raw' ? 'drafts' : sanitizedPerspective\n}\n\n/**\n * Check if API version supports perspective stack (v2025-02-19 or later)\n * Special versions: '1' doesn't support perspectives, 'X' does support perspectives\n */\nexport function supportsPerspectiveStack(apiVersion: string): boolean {\n  // Special cases\n  if (apiVersion === '1') return false\n  if (apiVersion === 'X') return true\n\n  // Normalize version by removing 'v' prefix if present\n  const normalizedVersion = `${apiVersion}`.replace(/^v/, '')\n\n  // Parse date format: 2025-02-19\n  if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(normalizedVersion)) return false\n\n  const versionDate = new Date(normalizedVersion)\n  const cutoffDate = new Date('2025-02-19')\n\n  return versionDate >= cutoffDate\n}\n\n/**\n * Extracts and validates the perspective from a session.\n */\nexport function getPerspective(session: SanityPreviewSession | HydrogenSession): ClientPerspective {\n  const perspective = session.get('perspective')?.split(',')\n  validateApiPerspective(perspective)\n  return perspective\n}\n\n/**\n * Type guard that checks if a session object is a SanityPreviewSession.\n * Validates presence of required methods: has, destroy (in addition to Hydrogen session methods).\n */\nexport function isSanityPreviewSession(session: unknown): session is SanityPreviewSession {\n  return (\n    isHydrogenSession(session) &&\n    'has' in session &&\n    typeof session.has === 'function' &&\n    'destroy' in session &&\n    typeof session.destroy === 'function'\n  )\n}\n\n/**\n * Type guard that checks if a session object is a valid Hydrogen session.\n * Validates presence of required methods: get, set, unset, commit.\n */\nexport function isHydrogenSession(session: unknown): session is HydrogenSession {\n  return (\n    !!session &&\n    typeof session === 'object' &&\n    'get' in session &&\n    typeof session.get === 'function' &&\n    'set' in session &&\n    typeof session.set === 'function' &&\n    'unset' in session &&\n    typeof session.unset === 'function' &&\n    'commit' in session &&\n    typeof session.commit === 'function'\n  )\n}\n\n/**\n * Utility function that detects if code is running on the server.\n * Used for SSR safety and preventing client-only code from running on server.\n */\nexport function isServer(): boolean {\n  return typeof document === 'undefined'\n}\n"],"names":[],"mappings":";;AAcA,eAAsB,OAAO,OAAA,EAAkC;AAE7D,EAAA,MAAM,gBAAgB,MAAM,IAAI,WAAA,EAAY,CAAE,OAAO,OAAO,CAAA;AAE5D,EAAA,MAAM,aAAa,MAAM,MAAA,CAAO,MAAA,CAAO,MAAA,CAAO,WAAW,aAAa,CAAA;AAEtE,EAAA,OAAO,KAAA,CAAM,KAAK,IAAI,UAAA,CAAW,UAAU,CAAC,CAAA,CACzC,IAAI,CAAC,CAAA,KAAM,EAAE,QAAA,CAAS,EAAE,EAAE,QAAA,CAAS,CAAA,EAAG,GAAG,CAAC,CAAA,CAC1C,KAAK,EAAE,CAAA;AACZ;AAMO,SAAS,SAAA,CACd,OACA,MAAA,EACiB;AACjB,EAAA,IAAI,IAAA,GAAO,KAAA;AAEX,EAAA,IAAI,MAAA,EAAQ;AACV,IAAA,IAAA,IAAQ,IAAA,CAAK,UAAU,MAAM,CAAA;AAAA,EAC/B;AAEA,EAAA,OAAO,OAAO,IAAI,CAAA;AACpB;AAMO,SAAS,oBAAoB,WAAA,EAAyD;AAC3F,EAAA,MAAM,oBAAA,GACJ,OAAO,WAAA,KAAgB,QAAA,IAAY,WAAA,CAAY,QAAA,CAAS,GAAG,CAAA,GACvD,WAAA,CAAY,KAAA,CAAM,GAAG,CAAA,GACrB,WAAA;AAEN,EAAA,sBAAA,CAAuB,oBAAoB,CAAA;AAE3C,EAAA,OAAO,oBAAA,KAAyB,QAAQ,QAAA,GAAW,oBAAA;AACrD;AAMO,SAAS,yBAAyB,UAAA,EAA6B;AAEpE,EAAA,IAAI,UAAA,KAAe,KAAK,OAAO,KAAA;AAC/B,EAAA,IAAI,UAAA,KAAe,KAAK,OAAO,IAAA;AAG/B,EAAA,MAAM,oBAAoB,CAAA,EAAG,UAAU,CAAA,CAAA,CAAG,OAAA,CAAQ,MAAM,EAAE,CAAA;AAG1D,EAAA,IAAI,CAAC,qBAAA,CAAsB,IAAA,CAAK,iBAAiB,GAAG,OAAO,KAAA;AAE3D,EAAA,MAAM,WAAA,GAAc,IAAI,IAAA,CAAK,iBAAiB,CAAA;AAC9C,EAAA,MAAM,UAAA,mBAAa,IAAI,IAAA,CAAK,YAAY,CAAA;AAExC,EAAA,OAAO,WAAA,IAAe,UAAA;AACxB;AAKO,SAAS,eAAe,OAAA,EAAoE;AACjG,EAAA,MAAM,cAAc,OAAA,CAAQ,GAAA,CAAI,aAAa,CAAA,EAAG,MAAM,GAAG,CAAA;AACzD,EAAA,sBAAA,CAAuB,WAAW,CAAA;AAClC,EAAA,OAAO,WAAA;AACT;AAMO,SAAS,uBAAuB,OAAA,EAAmD;AACxF,EAAA,OACE,iBAAA,CAAkB,OAAO,CAAA,IACzB,KAAA,IAAS,OAAA,IACT,OAAO,OAAA,CAAQ,GAAA,KAAQ,UAAA,IACvB,SAAA,IAAa,OAAA,IACb,OAAO,QAAQ,OAAA,KAAY,UAAA;AAE/B;AAMO,SAAS,kBAAkB,OAAA,EAA8C;AAC9E,EAAA,OACE,CAAC,CAAC,OAAA,IACF,OAAO,OAAA,KAAY,QAAA,IACnB,KAAA,IAAS,OAAA,IACT,OAAO,OAAA,CAAQ,GAAA,KAAQ,UAAA,IACvB,KAAA,IAAS,OAAA,IACT,OAAO,OAAA,CAAQ,GAAA,KAAQ,UAAA,IACvB,OAAA,IAAW,OAAA,IACX,OAAO,OAAA,CAAQ,KAAA,KAAU,UAAA,IACzB,QAAA,IAAY,OAAA,IACZ,OAAO,OAAA,CAAQ,MAAA,KAAW,UAAA;AAE9B;AAMO,SAAS,QAAA,GAAoB;AAClC,EAAA,OAAO,OAAO,QAAA,KAAa,WAAA;AAC7B;;;;"}
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["import {\n  type ClientPerspective,\n  type QueryParams,\n  type QueryWithoutParams,\n  validateApiPerspective,\n} from '@sanity/client'\nimport {urlSearchParamPreviewPerspective} from '@sanity/preview-url-secret/constants'\nimport type {HydrogenSession} from '@shopify/hydrogen'\n\nimport type {SanityPreviewSession} from './preview/session'\n\n/**\n * Create an SHA-256 hash as a hex string\n * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest#converting_a_digest_to_a_hex_string\n */\nexport async function sha256(message: string): Promise<string> {\n  // encode as UTF-8\n  const messageBuffer = await new TextEncoder().encode(message)\n  // hash the message\n  const hashBuffer = await crypto.subtle.digest('SHA-256', messageBuffer)\n  // convert bytes to hex string\n  return Array.from(new Uint8Array(hashBuffer))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n/**\n * Hash query and its parameters for use as cache key.\n * NOTE: Oxygen deployment will break if the cache key is long or contains `\\n`\n */\nexport function hashQuery(\n  query: string,\n  params: QueryParams | QueryWithoutParams,\n): Promise<string> {\n  let hash = query\n\n  if (params) {\n    hash += JSON.stringify(params)\n  }\n\n  return sha256(hash)\n}\n\n/**\n * Sanitizes and validates a perspective value.\n * Handles both string (comma-separated) and array formats.\n */\nexport function sanitizePerspective(perspective: unknown): Exclude<ClientPerspective, 'raw'> {\n  let sanitizedPerspective =\n    typeof perspective === 'string' && perspective.includes(',')\n      ? perspective.split(',')\n      : perspective\n\n  // Filter out empty strings and undefined values from perspective array\n  if (Array.isArray(sanitizedPerspective)) {\n    sanitizedPerspective = sanitizedPerspective.filter(\n      (p): p is string => typeof p === 'string' && p.length > 0,\n    )\n  }\n\n  validateApiPerspective(sanitizedPerspective)\n\n  return sanitizedPerspective === 'raw' ? 'drafts' : sanitizedPerspective\n}\n\n/**\n * Check if API version supports perspective stack (v2025-02-19 or later)\n * Special versions: '1' doesn't support perspectives, 'X' does support perspectives\n */\nexport function supportsPerspectiveStack(apiVersion: string): boolean {\n  // Special cases\n  if (apiVersion === '1') return false\n  if (apiVersion === 'X') return true\n\n  // Normalize version by removing 'v' prefix if present\n  const normalizedVersion = `${apiVersion}`.replace(/^v/, '')\n\n  // Parse date format: 2025-02-19\n  if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(normalizedVersion)) return false\n\n  const versionDate = new Date(normalizedVersion)\n  const cutoffDate = new Date('2025-02-19')\n\n  return versionDate >= cutoffDate\n}\n\n/**\n * Extracts and validates the perspective from a session.\n */\nexport function getPerspective(session: SanityPreviewSession | HydrogenSession): ClientPerspective {\n  const perspective = session\n    .get('perspective')\n    ?.split(',')\n    .filter((p: string) => p.length > 0)\n  validateApiPerspective(perspective)\n  return perspective\n}\n\n/**\n * Reads the `sanity-preview-perspective` URL search param and validates it.\n * Returns `undefined` if absent or invalid, so callers can fall back to the session.\n */\nexport function getPerspectiveFromUrl(url: URL | string): ClientPerspective | undefined {\n  try {\n    const parsed = typeof url === 'string' ? new URL(url) : url\n    const param = parsed.searchParams.get(urlSearchParamPreviewPerspective)\n    if (!param) return undefined\n    return sanitizePerspective(param)\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Type guard that checks if a session object is a SanityPreviewSession.\n * Validates presence of required methods: has, destroy (in addition to Hydrogen session methods).\n */\nexport function isSanityPreviewSession(session: unknown): session is SanityPreviewSession {\n  return (\n    isHydrogenSession(session) &&\n    'has' in session &&\n    typeof session.has === 'function' &&\n    'destroy' in session &&\n    typeof session.destroy === 'function'\n  )\n}\n\n/**\n * Type guard that checks if a session object is a valid Hydrogen session.\n * Validates presence of required methods: get, set, unset, commit.\n */\nexport function isHydrogenSession(session: unknown): session is HydrogenSession {\n  return (\n    !!session &&\n    typeof session === 'object' &&\n    'get' in session &&\n    typeof session.get === 'function' &&\n    'set' in session &&\n    typeof session.set === 'function' &&\n    'unset' in session &&\n    typeof session.unset === 'function' &&\n    'commit' in session &&\n    typeof session.commit === 'function'\n  )\n}\n\n/**\n * Utility function that detects if code is running on the server.\n * Used for SSR safety and preventing client-only code from running on server.\n */\nexport function isServer(): boolean {\n  return typeof document === 'undefined'\n}\n"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import {Any} from '@sanity/client'
 import {CachingStrategy} from '@shopify/hydrogen'
 import {ClientConfig} from '@sanity/client'
+import {ClientPerspective} from '@sanity/client'
 import {ClientReturn} from '@sanity/client'
 import {createDataAttribute} from '@sanity/react-loader'
 import {EncodeDataAttributeFunction} from '@sanity/core-loader/encode-data-attribute'
@@ -86,6 +87,12 @@ declare type FetchOptions<T> = HydrogenResponseQueryOptions & {
   }
 }
 
+/**
+ * Reads the `sanity-preview-perspective` URL search param and validates it.
+ * Returns `undefined` if absent or invalid, so callers can fall back to the session.
+ */
+export declare function getPerspectiveFromUrl(url: URL | string): ClientPerspective | undefined
+
 declare type HydrogenResponseQueryOptions = Omit<ResponseQueryOptions, 'next' | 'cache'> & {
   hydrogen?: 'hydrogen' extends keyof RequestInit_2 ? RequestInit_2['hydrogen'] : never
 }

package/dist/index.js

@@ -4,7 +4,7 @@ import { createElement, useMemo, lazy, Suspense, useSyncExternalStore, useId, us
 import { isPreviewEnabled, usePreviewMode } from './preview/index.js';
 import { SanityProvider, useSanityProviderValue } from './_chunks-es/provider.js';
 export { Sanity } from './_chunks-es/provider.js';
-import { supportsPerspectiveStack, getPerspective, hashQuery, isServer } from './_chunks-es/utils.js';
+import { getPerspectiveFromUrl, supportsPerspectiveStack, getPerspective, hashQuery, isServer } from './_chunks-es/utils.js';
 import { createImageUrlBuilder } from '@sanity/image-url';
 import { jsx } from 'react/jsx-runtime';
 import { useQuery as useQuery$1 } from '@sanity/react-loader';
@@ -17,7 +17,6 @@ const DEFAULT_CACHE_STRATEGY = CacheLong();
 let didWarnAboutNoApiVersion = false;
 let didWarnAboutNoPerspectiveSupport = false;
 let didWarnAboutLoadQuery = false;
-let didInitializeLoader = false;
 async function createSanityContext(options) {
   const { cache, waitUntil = () => Promise.resolve(), request, preview, defaultStrategy } = options;
   const withCache = cache ? createWithCache({ cache, waitUntil, request }) : null;
@@ -43,7 +42,10 @@ You can find the latest version in the Sanity changelog: https://www.sanity.io/c
     if (previewEnabled) {
       const apiVersion2 = client.config().apiVersion;
       let perspective;
-      if (supportsPerspectiveStack(apiVersion2)) {
+      const urlPerspective = getPerspectiveFromUrl(request.url);
+      if (urlPerspective !== void 0 && !(Array.isArray(urlPerspective) && !supportsPerspectiveStack(apiVersion2))) {
+        perspective = urlPerspective;
+      } else if (supportsPerspectiveStack(apiVersion2)) {
         perspective = getPerspective(preview.session);
       } else {
         if (process.env.NODE_ENV === "development" && !didWarnAboutNoPerspectiveSupport) {
@@ -77,11 +79,8 @@ You can find the latest version in the Sanity changelog: https://www.sanity.io/c
      * Bypasses Hydrogen cache in preview mode.
      */
     async loadQuery(query, params, loaderOptions) {
-      if (!didInitializeLoader) {
-        const { setServerClient } = await import('@sanity/react-loader');
-        setServerClient(client);
-        didInitializeLoader = true;
-      }
+      const { setServerClient } = await import('@sanity/react-loader');
+      setServerClient(client);
       if (!previewEnabled && process.env.NODE_ENV === "development" && !didWarnAboutLoadQuery) {
         console.warn(
           `\`loadQuery\` is being called outside of preview mode. Consider using \`query\` instead, which automatically handles both preview and production modes efficiently, or use \`fetch\`. \`loadQuery\` is intended to be called conditionally in preview and visual editing contexts.`
@@ -90,7 +89,8 @@ You can find the latest version in the Sanity changelog: https://www.sanity.io/c
       }
       if (!withCache || previewEnabled) {
         const { loadQuery } = await import('@sanity/react-loader');
-        return await loadQuery(query, params, loaderOptions);
+        const resolvedOptions = previewEnabled && !loaderOptions?.perspective ? { ...loaderOptions, perspective: client.config().perspective } : loaderOptions;
+        return await loadQuery(query, params, resolvedOptions);
       }
       const cacheStrategy = loaderOptions?.hydrogen?.cache || defaultStrategy || DEFAULT_CACHE_STRATEGY;
       const queryHash = await hashQuery(query, params);
@@ -226,5 +226,5 @@ function useQuery(query, params, options) {
   return useQuery$1(query, params, options);
 }
 
-export { DEFAULT_API_VERSION, DEFAULT_CACHE_STRATEGY, Query, createSanityContext, useImageUrl, useImageUrlBuilder, useQuery, useSanityProviderValue };
+export { DEFAULT_API_VERSION, DEFAULT_CACHE_STRATEGY, Query, createSanityContext, getPerspectiveFromUrl, useImageUrl, useImageUrlBuilder, useQuery, useSanityProviderValue };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/constants.ts","../src/context.ts","../src/image.ts","../src/Query.tsx","../src/visual-editing/useQuery.tsx"],"sourcesContent":["import {CacheLong, type CachingStrategy} from '@shopify/hydrogen'\n\n/** Default Sanity API version with perspective stack support */\nexport const DEFAULT_API_VERSION = 'v2025-02-19'\n\n/** Default Hydrogen caching strategy for Sanity queries */\nexport const DEFAULT_CACHE_STRATEGY: CachingStrategy = CacheLong()\n","import {\n  type Any,\n  type ClientConfig,\n  type ClientPerspective,\n  type ClientReturn,\n  createClient,\n  type QueryParams,\n  type QueryWithoutParams,\n  type ResponseQueryOptions,\n  SanityClient,\n} from '@sanity/client'\nimport type {QueryResponseInitial} from '@sanity/react-loader'\nimport {type CachingStrategy, createWithCache, type HydrogenSession} from '@shopify/hydrogen'\nimport {createElement, type PropsWithChildren, type ReactNode} from 'react'\n\nimport {DEFAULT_API_VERSION, DEFAULT_CACHE_STRATEGY} from './constants'\nimport type {SanityPreviewSession} from './preview/session'\nimport {isPreviewEnabled} from './preview/utils'\nimport {SanityProvider, type SanityProviderValue} from './provider'\nimport type {CacheActionFunctionParam, WaitUntil} from './types'\nimport {getPerspective} from './utils'\nimport {hashQuery, supportsPerspectiveStack} from './utils'\n\nlet didWarnAboutNoApiVersion = false\nlet didWarnAboutNoPerspectiveSupport = false\nlet didWarnAboutLoadQuery = false\nlet didInitializeLoader = false\n\nexport type CreateSanityContextOptions = {\n  request: Request\n\n  cache?: Cache | undefined\n  waitUntil?: WaitUntil | undefined\n\n  /**\n   * Sanity client or configuration to use.\n   */\n  client: SanityClient | ClientConfig\n\n  /**\n   * The default caching strategy to use for `loadQuery` subrequests.\n   * @see https://shopify.dev/docs/custom-storefronts/hydrogen/caching#caching-strategies\n   *\n   * Defaults to `CacheLong`\n   */\n  defaultStrategy?: CachingStrategy | null\n\n  /**\n   * Configuration for enabling preview mode.\n   */\n  preview?: {\n    token: string\n    session: SanityPreviewSession | HydrogenSession\n  }\n}\n\ninterface RequestInit {\n  hydrogen?: {\n    /**\n     * The caching strategy to use for the subrequest.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/caching#caching-strategies\n     */\n    cache?: CachingStrategy\n\n    /**\n     * Optional debugging information to be displayed in the subrequest profiler.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/debugging/subrequest-profiler#how-to-provide-more-debug-information-for-a-request\n     */\n    debug?: {\n      displayName: string\n    }\n  }\n}\n\ntype HydrogenResponseQueryOptions = Omit<ResponseQueryOptions, 'next' | 'cache'> & {\n  hydrogen?: 'hydrogen' extends keyof RequestInit ? RequestInit['hydrogen'] : never\n}\n\nexport type LoadQueryOptions<T> = Pick<\n  HydrogenResponseQueryOptions,\n  'perspective' | 'hydrogen' | 'useCdn' | 'stega' | 'headers' | 'tag'\n> & {\n  hydrogen?: {\n    /**\n     * The caching strategy to use for the subrequest.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/caching#caching-strategies\n     */\n    cache?: CachingStrategy\n\n    /**\n     * Optional debugging information to be displayed in the subrequest profiler.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/debugging/subrequest-profiler#how-to-provide-more-debug-information-for-a-request\n     */\n    debug?: {\n      displayName: string\n    }\n\n    /**\n     * Whether to cache the result of the query or not.\n     * @defaultValue () => true\n     */\n    shouldCacheResult?: (value: QueryResponseInitial<T>) => boolean\n  }\n}\n\nexport type FetchOptions<T> = HydrogenResponseQueryOptions & {\n  hydrogen?: {\n    /**\n     * The caching strategy to use for the subrequest.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/caching#caching-strategies\n     */\n    cache?: CachingStrategy\n\n    /**\n     * Optional debugging information to be displayed in the subrequest profiler.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/debugging/subrequest-profiler#how-to-provide-more-debug-information-for-a-request\n     */\n    debug?: {\n      displayName: string\n    }\n\n    /**\n     * Whether to cache the result of the query or not.\n     * @defaultValue () => true\n     */\n    shouldCacheResult?: (value: QueryResponseInitial<T>) => boolean\n  }\n}\n\nexport interface SanityContext {\n  /**\n   * Query Sanity using the loader.\n   * @see https://www.sanity.io/docs/loaders\n   */\n  loadQuery<Result = Any, Query extends string = string>(\n    query: Query,\n    params?: QueryParams | QueryWithoutParams,\n    options?: LoadQueryOptions<ClientReturn<Query, Result>>,\n  ): Promise<QueryResponseInitial<ClientReturn<Query, Result>>>\n\n  /**\n   * Query Sanity using direct client fetch with Hydrogen caching.\n   * Use this when you need direct client results without react-loader integration.\n   * Automatically disables caching in preview mode for real-time updates.\n   */\n  fetch<Result = Any, Query extends string = string>(\n    query: Query,\n    params?: QueryParams | QueryWithoutParams,\n    options?: FetchOptions<Result>,\n  ): Promise<ClientReturn<Query, Result>>\n\n  /**\n   * Conditionally query Sanity using either loadQuery (for preview mode) or fetch (for static mode).\n   * This optimizes bundle size by only loading @sanity/react-loader dependencies when in preview mode.\n   */\n  query<Result = Any, Query extends string = string>(\n    query: Query,\n    params?: QueryParams | QueryWithoutParams,\n    options?: LoadQueryOptions<ClientReturn<Query, Result>> & FetchOptions<Result>,\n  ): Promise<QueryResponseInitial<ClientReturn<Query, Result>> | ClientReturn<Query, Result>>\n\n  /**\n   * The Sanity client, automatically configured for preview mode when enabled.\n   * Uses preview token, perspective, and CDN settings based on session state.\n   */\n  client: SanityClient\n\n  preview?: CreateSanityContextOptions['preview'] & {\n    /**\n     * Whether preview mode is currently enabled based on session detection\n     */\n    enabled: boolean\n  }\n\n  SanityProvider: (props: PropsWithChildren<object>) => ReactNode\n}\n\n/**\n * @public\n */\nexport async function createSanityContext(\n  options: CreateSanityContextOptions,\n): Promise<SanityContext> {\n  const {cache, waitUntil = () => Promise.resolve(), request, preview, defaultStrategy} = options\n  const withCache = cache ? createWithCache({cache, waitUntil, request}) : null\n  let client =\n    options.client instanceof SanityClient ? options.client : createClient(options.client)\n\n  if (client.config().apiVersion === '1') {\n    if (process.env.NODE_ENV === 'development' && !didWarnAboutNoApiVersion) {\n      console.warn(\n        `\nNo API version specified, defaulting to \\`${DEFAULT_API_VERSION}\\` which supports perspectives and Content Releases.\nYou can find the latest version in the Sanity changelog: https://www.sanity.io/changelog.\n    `.trim(),\n      )\n\n      didWarnAboutNoApiVersion = true\n    }\n\n    client = client.withConfig({apiVersion: DEFAULT_API_VERSION})\n  }\n\n  // Determine if preview is enabled and configure the client accordingly\n  let previewEnabled = false\n  if (preview) {\n    if (!preview.token) {\n      throw new Error('Enabling preview mode requires a token.')\n    }\n\n    previewEnabled = isPreviewEnabled(client.config().projectId!, preview.session)\n\n    if (previewEnabled) {\n      const apiVersion = client.config().apiVersion\n      let perspective: ClientPerspective\n      if (supportsPerspectiveStack(apiVersion)) {\n        perspective = getPerspective(preview.session)\n      } else {\n        if (process.env.NODE_ENV === 'development' && !didWarnAboutNoPerspectiveSupport) {\n          console.warn(\n            `API version \\`${apiVersion}\\` does not support perspective stacks. Using \\`previewDrafts\\` perspective. Consider upgrading to \\`v2025-02-19\\` or later for full perspective support.`,\n          )\n\n          didWarnAboutNoPerspectiveSupport = true\n        }\n        perspective = 'previewDrafts'\n      }\n\n      client = client.withConfig({\n        useCdn: false,\n        token: preview.token,\n        perspective,\n      })\n    }\n  }\n\n  // Server client will be initialized lazily on first loadQuery call\n  const {apiHost, projectId, dataset, apiVersion} = client.config()\n  const providerValue: SanityProviderValue = {\n    projectId: projectId!,\n    dataset: dataset!,\n    apiHost,\n    apiVersion: apiVersion!,\n    previewEnabled,\n    perspective: client.config().perspective || 'published',\n    stegaEnabled: client.config().stega?.enabled ?? false,\n  }\n\n  return {\n    /**\n     * Loads a Sanity query with client-side loader support and Hydrogen cache integration.\n     * Bypasses Hydrogen cache in preview mode.\n     */\n    async loadQuery<Result = Any, Query extends string = string>(\n      query: Query,\n      params: QueryParams | QueryWithoutParams,\n      loaderOptions?: LoadQueryOptions<ClientReturn<Query, Result>>,\n    ): Promise<QueryResponseInitial<ClientReturn<Query, Result>>> {\n      // Lazy initialize the loader on first call with the configured client\n      if (!didInitializeLoader) {\n        const {setServerClient} = await import('@sanity/react-loader')\n        setServerClient(client)\n        didInitializeLoader = true\n      }\n\n      // Warn users to migrate to `query` method when using loadQuery outside preview mode\n      if (!previewEnabled && process.env.NODE_ENV === 'development' && !didWarnAboutLoadQuery) {\n        console.warn(\n          `\\`loadQuery\\` is being called outside of preview mode. Consider using \\`query\\` instead, which automatically handles both preview and production modes efficiently, or use \\`fetch\\`. \\`loadQuery\\` is intended to be called conditionally in preview and visual editing contexts.`,\n        )\n        didWarnAboutLoadQuery = true\n      }\n\n      if (!withCache || previewEnabled) {\n        const {loadQuery} = await import('@sanity/react-loader')\n        return await loadQuery<ClientReturn<Query, Result>>(query, params, loaderOptions)\n      }\n\n      const cacheStrategy =\n        loaderOptions?.hydrogen?.cache || defaultStrategy || DEFAULT_CACHE_STRATEGY\n      const queryHash = await hashQuery(query, params)\n      const shouldCacheResult = loaderOptions?.hydrogen?.shouldCacheResult ?? (() => true)\n\n      return await withCache.run(\n        {cacheKey: queryHash, cacheStrategy, shouldCacheResult},\n        async ({\n          addDebugData,\n        }: CacheActionFunctionParam): Promise<\n          QueryResponseInitial<ClientReturn<Query, Result>>\n        > => {\n          // Name displayed in the subrequest profiler\n          const displayName = loaderOptions?.hydrogen?.debug?.displayName || 'query Sanity'\n\n          addDebugData({\n            displayName,\n          })\n\n          const {loadQuery} = await import('@sanity/react-loader')\n          return await loadQuery<ClientReturn<Query, Result>>(query, params, loaderOptions)\n        },\n      )\n    },\n\n    /**\n     * Executes a Sanity query with Hydrogen cache integration.\n     * Direct client fetch without loader integration. Bypasses cache in preview mode.\n     */\n    async fetch<Result = Any, Query extends string = string>(\n      query: Query,\n      params: QueryParams | QueryWithoutParams = {},\n      fetchOptions?: Pick<\n        LoadQueryOptions<Result>,\n        'perspective' | 'hydrogen' | 'useCdn' | 'headers' | 'tag'\n      >,\n    ): Promise<ClientReturn<Query, Result>> {\n      if (!withCache || previewEnabled) {\n        return await client.fetch<ClientReturn<Query, Result>>(query, params, fetchOptions)\n      }\n\n      const cacheStrategy =\n        fetchOptions?.hydrogen?.cache || defaultStrategy || DEFAULT_CACHE_STRATEGY\n      const queryHash = await hashQuery(query, params)\n\n      return await withCache.run(\n        {cacheKey: queryHash, cacheStrategy, shouldCacheResult: () => true},\n        async ({addDebugData}: CacheActionFunctionParam): Promise<ClientReturn<Query, Result>> => {\n          // Name displayed in the subrequest profiler\n          const displayName = fetchOptions?.hydrogen?.debug?.displayName || 'fetch Sanity'\n\n          addDebugData({\n            displayName,\n          })\n\n          return await client.fetch<ClientReturn<Query, Result>>(query, params, fetchOptions)\n        },\n      )\n    },\n\n    /**\n     * Automatic query method that automatically adapts based on preview mode state.\n     * Uses `loadQuery` (with client-side loader integration) when preview is enabled, `fetch` otherwise.\n     * Bypasses cache in preview mode.\n     */\n    async query<Result = Any, Query extends string = string>(\n      query: Query,\n      params?: QueryParams | QueryWithoutParams,\n      queryOptions?: LoadQueryOptions<ClientReturn<Query, Result>> & FetchOptions<Result>,\n    ): Promise<QueryResponseInitial<ClientReturn<Query, Result>> | ClientReturn<Query, Result>> {\n      return await (previewEnabled ? this.loadQuery : this.fetch)(query, params, queryOptions)\n    },\n\n    /** The configured Sanity client instance */\n    client,\n\n    /** Preview configuration with session-based state, undefined when preview is not configured */\n    preview: preview ? {...preview, enabled: previewEnabled} : undefined,\n\n    /**\n     * React Provider component that serializes Sanity configuration across server-client boundary.\n     */\n    SanityProvider({children}: PropsWithChildren<object>) {\n      return createElement(\n        SanityProvider,\n        {\n          value: Object.freeze(providerValue),\n        },\n        children,\n      )\n    },\n  } satisfies SanityContext\n}\n","import type {ImageUrlBuilder, SanityImageSource, SanityModernClientLike} from '@sanity/image-url'\nimport {createImageUrlBuilder} from '@sanity/image-url'\nimport {useMemo} from 'react'\n\nimport {useSanityProviderValue} from './provider'\n\n/**\n * Hook that returns a Sanity image URL builder configured with current provider settings.\n * Use this to create custom image transformations beyond `useImageUrl`.\n */\nexport function useImageUrlBuilder(): ImageUrlBuilder {\n  const {projectId, dataset, apiHost} = useSanityProviderValue()\n  return useMemo(() => {\n    return createImageUrlBuilder({\n      config: () => ({projectId, dataset, apiHost}),\n    } as SanityModernClientLike)\n  }, [apiHost, dataset, projectId])\n}\n\n/**\n * Hook that generates image URLs from Sanity image assets.\n * Returns a configured image URL builder for the given source.\n */\nexport function useImageUrl(source: SanityImageSource): ImageUrlBuilder {\n  const builder = useImageUrlBuilder()\n  return builder.image(source)\n}\n\nexport type * from '@sanity/image-url'\n","import type {Any, ClientReturn, QueryParams, QueryWithoutParams} from '@sanity/client'\nimport type {EncodeDataAttributeFunction} from '@sanity/core-loader/encode-data-attribute'\nimport type {QueryResponseInitial} from '@sanity/react-loader'\nimport {lazy, type ReactNode, Suspense, type SuspenseProps, useSyncExternalStore} from 'react'\n\nimport type {LoadQueryOptions} from './context'\nimport {usePreviewMode} from './preview/hooks'\nimport type {QueryClientProps} from './Query.client'\nimport {isServer} from './utils'\n\n/**\n * Fallback component that renders nothing, preventing hydration mismatches.\n */\nfunction SanityQueryFallback(): ReactNode {\n  return null\n}\n\n/**\n * Simple hydration store to avoid hydration mismatches.\n * Returns false on server, true on client after hydration.\n */\nfunction useIsHydrated(): boolean {\n  return useSyncExternalStore(\n    // eslint-disable-next-line no-empty-function\n    () => () => {},\n    () => true,\n    () => false,\n  )\n}\n\nconst QueryClient = isServer()\n  ? SanityQueryFallback\n  : (lazy(\n      () =>\n        /**\n         * `lazy` expects the component as the default export\n         * @see https://react.dev/reference/react/lazy\n         */\n        import('./Query.client'),\n    ) as <Result = Any, Query extends string = string>(\n      props: QueryClientProps<Result, Query>,\n    ) => ReactNode)\n\nconst noopEncodeDataAttribute: EncodeDataAttributeFunction = Object.assign(() => undefined, {\n  scope: () => noopEncodeDataAttribute,\n})\n\nexport interface QueryProps<Result = Any, Query extends string = string> extends Omit<\n  QueryClientProps<Result, Query>,\n  'options'\n> {\n  query: Query\n  params?: QueryParams | QueryWithoutParams\n  options: {\n    initial: ClientReturn<Query, Result> | QueryResponseInitial<ClientReturn<Query, Result>>\n  } & LoadQueryOptions<ClientReturn<Query, Result>>\n  children: (\n    data: ClientReturn<Query, Result>,\n    encodeDataAttribute: EncodeDataAttributeFunction,\n  ) => ReactNode\n}\n\n/**\n * Query component that provides live updates in preview mode and static data otherwise.\n *\n * @public\n */\nexport function Query<Result = Any, Query extends string = string>({\n  query,\n  params,\n  options,\n  children,\n  ...suspenseProps\n}: QueryProps<Result, Query> & Omit<SuspenseProps, 'children'>): ReactNode {\n  const isPreviewMode = usePreviewMode()\n  const isHydrated = useIsHydrated()\n\n  // If in preview mode and hydrated, render the client component\n  if (isPreviewMode && isHydrated) {\n    return (\n      <Suspense {...suspenseProps} fallback={suspenseProps.fallback ?? <SanityQueryFallback />}>\n        <QueryClient<Result, Query>\n          query={query}\n          params={params}\n          options={options as QueryClientProps<Result, Query>['options']}\n        >\n          {children}\n        </QueryClient>\n      </Suspense>\n    )\n  }\n\n  // Render static data in non-preview mode or during hydration\n  return children(options.initial as ClientReturn<Query, Result>, noopEncodeDataAttribute)\n}\n","import {useQuery as _useQuery, type UseQueryOptionsDefinedInitial} from '@sanity/react-loader'\nimport {useEffect, useId} from 'react'\n\nimport {registerQuery} from './registry'\n\n/**\n * Automatically registers with the query detection system.\n * This enables automatic live mode detection in `VisualEditing` components.\n */\nexport function useQuery<QueryResponseResult = unknown>(\n  query: string,\n  params?: Record<string, unknown>,\n  options?: UseQueryOptionsDefinedInitial<QueryResponseResult>,\n): ReturnType<typeof _useQuery<QueryResponseResult>> {\n  // Generate stable ID for this `useQuery` instance\n  const id = useId()\n\n  // Register this `useQuery` instance with the detection system\n  useEffect(() => {\n    const unregister = registerQuery(id)\n    return unregister\n  }, [id])\n\n  // Call the original `useQuery` with all the same arguments\n  return _useQuery<QueryResponseResult>(query, params, options)\n}\n"],"names":["apiVersion","_useQuery"],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../src/constants.ts","../src/context.ts","../src/image.ts","../src/Query.tsx","../src/visual-editing/useQuery.tsx"],"sourcesContent":["import {CacheLong, type CachingStrategy} from '@shopify/hydrogen'\n\n/** Default Sanity API version with perspective stack support */\nexport const DEFAULT_API_VERSION = 'v2025-02-19'\n\n/** Default Hydrogen caching strategy for Sanity queries */\nexport const DEFAULT_CACHE_STRATEGY: CachingStrategy = CacheLong()\n","import {\n  type Any,\n  type ClientConfig,\n  type ClientPerspective,\n  type ClientReturn,\n  createClient,\n  type QueryParams,\n  type QueryWithoutParams,\n  type ResponseQueryOptions,\n  SanityClient,\n} from '@sanity/client'\nimport type {QueryResponseInitial} from '@sanity/react-loader'\nimport {type CachingStrategy, createWithCache, type HydrogenSession} from '@shopify/hydrogen'\nimport {createElement, type PropsWithChildren, type ReactNode} from 'react'\n\nimport {DEFAULT_API_VERSION, DEFAULT_CACHE_STRATEGY} from './constants'\nimport type {SanityPreviewSession} from './preview/session'\nimport {isPreviewEnabled} from './preview/utils'\nimport {SanityProvider, type SanityProviderValue} from './provider'\nimport type {CacheActionFunctionParam, WaitUntil} from './types'\nimport {getPerspective, getPerspectiveFromUrl} from './utils'\nimport {hashQuery, supportsPerspectiveStack} from './utils'\n\nlet didWarnAboutNoApiVersion = false\nlet didWarnAboutNoPerspectiveSupport = false\nlet didWarnAboutLoadQuery = false\n\nexport type CreateSanityContextOptions = {\n  request: Request\n\n  cache?: Cache | undefined\n  waitUntil?: WaitUntil | undefined\n\n  /**\n   * Sanity client or configuration to use.\n   */\n  client: SanityClient | ClientConfig\n\n  /**\n   * The default caching strategy to use for `loadQuery` subrequests.\n   * @see https://shopify.dev/docs/custom-storefronts/hydrogen/caching#caching-strategies\n   *\n   * Defaults to `CacheLong`\n   */\n  defaultStrategy?: CachingStrategy | null\n\n  /**\n   * Configuration for enabling preview mode.\n   */\n  preview?: {\n    token: string\n    session: SanityPreviewSession | HydrogenSession\n  }\n}\n\ninterface RequestInit {\n  hydrogen?: {\n    /**\n     * The caching strategy to use for the subrequest.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/caching#caching-strategies\n     */\n    cache?: CachingStrategy\n\n    /**\n     * Optional debugging information to be displayed in the subrequest profiler.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/debugging/subrequest-profiler#how-to-provide-more-debug-information-for-a-request\n     */\n    debug?: {\n      displayName: string\n    }\n  }\n}\n\ntype HydrogenResponseQueryOptions = Omit<ResponseQueryOptions, 'next' | 'cache'> & {\n  hydrogen?: 'hydrogen' extends keyof RequestInit ? RequestInit['hydrogen'] : never\n}\n\nexport type LoadQueryOptions<T> = Pick<\n  HydrogenResponseQueryOptions,\n  'perspective' | 'hydrogen' | 'useCdn' | 'stega' | 'headers' | 'tag'\n> & {\n  hydrogen?: {\n    /**\n     * The caching strategy to use for the subrequest.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/caching#caching-strategies\n     */\n    cache?: CachingStrategy\n\n    /**\n     * Optional debugging information to be displayed in the subrequest profiler.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/debugging/subrequest-profiler#how-to-provide-more-debug-information-for-a-request\n     */\n    debug?: {\n      displayName: string\n    }\n\n    /**\n     * Whether to cache the result of the query or not.\n     * @defaultValue () => true\n     */\n    shouldCacheResult?: (value: QueryResponseInitial<T>) => boolean\n  }\n}\n\nexport type FetchOptions<T> = HydrogenResponseQueryOptions & {\n  hydrogen?: {\n    /**\n     * The caching strategy to use for the subrequest.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/caching#caching-strategies\n     */\n    cache?: CachingStrategy\n\n    /**\n     * Optional debugging information to be displayed in the subrequest profiler.\n     * @see https://shopify.dev/docs/custom-storefronts/hydrogen/debugging/subrequest-profiler#how-to-provide-more-debug-information-for-a-request\n     */\n    debug?: {\n      displayName: string\n    }\n\n    /**\n     * Whether to cache the result of the query or not.\n     * @defaultValue () => true\n     */\n    shouldCacheResult?: (value: QueryResponseInitial<T>) => boolean\n  }\n}\n\nexport interface SanityContext {\n  /**\n   * Query Sanity using the loader.\n   * @see https://www.sanity.io/docs/loaders\n   */\n  loadQuery<Result = Any, Query extends string = string>(\n    query: Query,\n    params?: QueryParams | QueryWithoutParams,\n    options?: LoadQueryOptions<ClientReturn<Query, Result>>,\n  ): Promise<QueryResponseInitial<ClientReturn<Query, Result>>>\n\n  /**\n   * Query Sanity using direct client fetch with Hydrogen caching.\n   * Use this when you need direct client results without react-loader integration.\n   * Automatically disables caching in preview mode for real-time updates.\n   */\n  fetch<Result = Any, Query extends string = string>(\n    query: Query,\n    params?: QueryParams | QueryWithoutParams,\n    options?: FetchOptions<Result>,\n  ): Promise<ClientReturn<Query, Result>>\n\n  /**\n   * Conditionally query Sanity using either loadQuery (for preview mode) or fetch (for static mode).\n   * This optimizes bundle size by only loading @sanity/react-loader dependencies when in preview mode.\n   */\n  query<Result = Any, Query extends string = string>(\n    query: Query,\n    params?: QueryParams | QueryWithoutParams,\n    options?: LoadQueryOptions<ClientReturn<Query, Result>> & FetchOptions<Result>,\n  ): Promise<QueryResponseInitial<ClientReturn<Query, Result>> | ClientReturn<Query, Result>>\n\n  /**\n   * The Sanity client, automatically configured for preview mode when enabled.\n   * Uses preview token, perspective, and CDN settings based on session state.\n   */\n  client: SanityClient\n\n  preview?: CreateSanityContextOptions['preview'] & {\n    /**\n     * Whether preview mode is currently enabled based on session detection\n     */\n    enabled: boolean\n  }\n\n  SanityProvider: (props: PropsWithChildren<object>) => ReactNode\n}\n\n/**\n * @public\n */\nexport async function createSanityContext(\n  options: CreateSanityContextOptions,\n): Promise<SanityContext> {\n  const {cache, waitUntil = () => Promise.resolve(), request, preview, defaultStrategy} = options\n  const withCache = cache ? createWithCache({cache, waitUntil, request}) : null\n  let client =\n    options.client instanceof SanityClient ? options.client : createClient(options.client)\n\n  if (client.config().apiVersion === '1') {\n    if (process.env.NODE_ENV === 'development' && !didWarnAboutNoApiVersion) {\n      console.warn(\n        `\nNo API version specified, defaulting to \\`${DEFAULT_API_VERSION}\\` which supports perspectives and Content Releases.\nYou can find the latest version in the Sanity changelog: https://www.sanity.io/changelog.\n    `.trim(),\n      )\n\n      didWarnAboutNoApiVersion = true\n    }\n\n    client = client.withConfig({apiVersion: DEFAULT_API_VERSION})\n  }\n\n  // Determine if preview is enabled and configure the client accordingly\n  let previewEnabled = false\n  if (preview) {\n    if (!preview.token) {\n      throw new Error('Enabling preview mode requires a token.')\n    }\n\n    previewEnabled = isPreviewEnabled(client.config().projectId!, preview.session)\n\n    if (previewEnabled) {\n      const apiVersion = client.config().apiVersion\n      let perspective: ClientPerspective\n\n      // Prefer URL param over session — the cookie may lag behind the iframe reload.\n      const urlPerspective = getPerspectiveFromUrl(request.url)\n\n      if (\n        urlPerspective !== undefined &&\n        !(Array.isArray(urlPerspective) && !supportsPerspectiveStack(apiVersion))\n      ) {\n        perspective = urlPerspective\n      } else if (supportsPerspectiveStack(apiVersion)) {\n        perspective = getPerspective(preview.session)\n      } else {\n        if (process.env.NODE_ENV === 'development' && !didWarnAboutNoPerspectiveSupport) {\n          console.warn(\n            `API version \\`${apiVersion}\\` does not support perspective stacks. Using \\`previewDrafts\\` perspective. Consider upgrading to \\`v2025-02-19\\` or later for full perspective support.`,\n          )\n\n          didWarnAboutNoPerspectiveSupport = true\n        }\n        perspective = 'previewDrafts'\n      }\n\n      client = client.withConfig({\n        useCdn: false,\n        token: preview.token,\n        perspective,\n      })\n    }\n  }\n\n  // Server client will be initialized lazily on first loadQuery call\n  const {apiHost, projectId, dataset, apiVersion} = client.config()\n  const providerValue: SanityProviderValue = {\n    projectId: projectId!,\n    dataset: dataset!,\n    apiHost,\n    apiVersion: apiVersion!,\n    previewEnabled,\n    perspective: client.config().perspective || 'published',\n    stegaEnabled: client.config().stega?.enabled ?? false,\n  }\n\n  return {\n    /**\n     * Loads a Sanity query with client-side loader support and Hydrogen cache integration.\n     * Bypasses Hydrogen cache in preview mode.\n     */\n    async loadQuery<Result = Any, Query extends string = string>(\n      query: Query,\n      params: QueryParams | QueryWithoutParams,\n      loaderOptions?: LoadQueryOptions<ClientReturn<Query, Result>>,\n    ): Promise<QueryResponseInitial<ClientReturn<Query, Result>>> {\n      const {setServerClient} = await import('@sanity/react-loader')\n      setServerClient(client)\n\n      // Warn users to migrate to `query` method when using loadQuery outside preview mode\n      if (!previewEnabled && process.env.NODE_ENV === 'development' && !didWarnAboutLoadQuery) {\n        console.warn(\n          `\\`loadQuery\\` is being called outside of preview mode. Consider using \\`query\\` instead, which automatically handles both preview and production modes efficiently, or use \\`fetch\\`. \\`loadQuery\\` is intended to be called conditionally in preview and visual editing contexts.`,\n        )\n        didWarnAboutLoadQuery = true\n      }\n\n      if (!withCache || previewEnabled) {\n        const {loadQuery} = await import('@sanity/react-loader')\n        // Override the singleton's possibly-stale perspective with the per-request value.\n        const resolvedOptions =\n          previewEnabled && !loaderOptions?.perspective\n            ? {...loaderOptions, perspective: client.config().perspective as ClientPerspective}\n            : loaderOptions\n        return await loadQuery<ClientReturn<Query, Result>>(query, params, resolvedOptions)\n      }\n\n      const cacheStrategy =\n        loaderOptions?.hydrogen?.cache || defaultStrategy || DEFAULT_CACHE_STRATEGY\n      const queryHash = await hashQuery(query, params)\n      const shouldCacheResult = loaderOptions?.hydrogen?.shouldCacheResult ?? (() => true)\n\n      return await withCache.run(\n        {cacheKey: queryHash, cacheStrategy, shouldCacheResult},\n        async ({\n          addDebugData,\n        }: CacheActionFunctionParam): Promise<\n          QueryResponseInitial<ClientReturn<Query, Result>>\n        > => {\n          // Name displayed in the subrequest profiler\n          const displayName = loaderOptions?.hydrogen?.debug?.displayName || 'query Sanity'\n\n          addDebugData({\n            displayName,\n          })\n\n          const {loadQuery} = await import('@sanity/react-loader')\n          return await loadQuery<ClientReturn<Query, Result>>(query, params, loaderOptions)\n        },\n      )\n    },\n\n    /**\n     * Executes a Sanity query with Hydrogen cache integration.\n     * Direct client fetch without loader integration. Bypasses cache in preview mode.\n     */\n    async fetch<Result = Any, Query extends string = string>(\n      query: Query,\n      params: QueryParams | QueryWithoutParams = {},\n      fetchOptions?: Pick<\n        LoadQueryOptions<Result>,\n        'perspective' | 'hydrogen' | 'useCdn' | 'headers' | 'tag'\n      >,\n    ): Promise<ClientReturn<Query, Result>> {\n      if (!withCache || previewEnabled) {\n        return await client.fetch<ClientReturn<Query, Result>>(query, params, fetchOptions)\n      }\n\n      const cacheStrategy =\n        fetchOptions?.hydrogen?.cache || defaultStrategy || DEFAULT_CACHE_STRATEGY\n      const queryHash = await hashQuery(query, params)\n\n      return await withCache.run(\n        {cacheKey: queryHash, cacheStrategy, shouldCacheResult: () => true},\n        async ({addDebugData}: CacheActionFunctionParam): Promise<ClientReturn<Query, Result>> => {\n          // Name displayed in the subrequest profiler\n          const displayName = fetchOptions?.hydrogen?.debug?.displayName || 'fetch Sanity'\n\n          addDebugData({\n            displayName,\n          })\n\n          return await client.fetch<ClientReturn<Query, Result>>(query, params, fetchOptions)\n        },\n      )\n    },\n\n    /**\n     * Automatic query method that automatically adapts based on preview mode state.\n     * Uses `loadQuery` (with client-side loader integration) when preview is enabled, `fetch` otherwise.\n     * Bypasses cache in preview mode.\n     */\n    async query<Result = Any, Query extends string = string>(\n      query: Query,\n      params?: QueryParams | QueryWithoutParams,\n      queryOptions?: LoadQueryOptions<ClientReturn<Query, Result>> & FetchOptions<Result>,\n    ): Promise<QueryResponseInitial<ClientReturn<Query, Result>> | ClientReturn<Query, Result>> {\n      return await (previewEnabled ? this.loadQuery : this.fetch)(query, params, queryOptions)\n    },\n\n    /** The configured Sanity client instance */\n    client,\n\n    /** Preview configuration with session-based state, undefined when preview is not configured */\n    preview: preview ? {...preview, enabled: previewEnabled} : undefined,\n\n    /**\n     * React Provider component that serializes Sanity configuration across server-client boundary.\n     */\n    SanityProvider({children}: PropsWithChildren<object>) {\n      return createElement(\n        SanityProvider,\n        {\n          value: Object.freeze(providerValue),\n        },\n        children,\n      )\n    },\n  } satisfies SanityContext\n}\n","import type {ImageUrlBuilder, SanityImageSource, SanityModernClientLike} from '@sanity/image-url'\nimport {createImageUrlBuilder} from '@sanity/image-url'\nimport {useMemo} from 'react'\n\nimport {useSanityProviderValue} from './provider'\n\n/**\n * Hook that returns a Sanity image URL builder configured with current provider settings.\n * Use this to create custom image transformations beyond `useImageUrl`.\n */\nexport function useImageUrlBuilder(): ImageUrlBuilder {\n  const {projectId, dataset, apiHost} = useSanityProviderValue()\n  return useMemo(() => {\n    return createImageUrlBuilder({\n      config: () => ({projectId, dataset, apiHost}),\n    } as SanityModernClientLike)\n  }, [apiHost, dataset, projectId])\n}\n\n/**\n * Hook that generates image URLs from Sanity image assets.\n * Returns a configured image URL builder for the given source.\n */\nexport function useImageUrl(source: SanityImageSource): ImageUrlBuilder {\n  const builder = useImageUrlBuilder()\n  return builder.image(source)\n}\n\nexport type * from '@sanity/image-url'\n","import type {Any, ClientReturn, QueryParams, QueryWithoutParams} from '@sanity/client'\nimport type {EncodeDataAttributeFunction} from '@sanity/core-loader/encode-data-attribute'\nimport type {QueryResponseInitial} from '@sanity/react-loader'\nimport {lazy, type ReactNode, Suspense, type SuspenseProps, useSyncExternalStore} from 'react'\n\nimport type {LoadQueryOptions} from './context'\nimport {usePreviewMode} from './preview/hooks'\nimport type {QueryClientProps} from './Query.client'\nimport {isServer} from './utils'\n\n/**\n * Fallback component that renders nothing, preventing hydration mismatches.\n */\nfunction SanityQueryFallback(): ReactNode {\n  return null\n}\n\n/**\n * Simple hydration store to avoid hydration mismatches.\n * Returns false on server, true on client after hydration.\n */\nfunction useIsHydrated(): boolean {\n  return useSyncExternalStore(\n    // eslint-disable-next-line no-empty-function\n    () => () => {},\n    () => true,\n    () => false,\n  )\n}\n\nconst QueryClient = isServer()\n  ? SanityQueryFallback\n  : (lazy(\n      () =>\n        /**\n         * `lazy` expects the component as the default export\n         * @see https://react.dev/reference/react/lazy\n         */\n        import('./Query.client'),\n    ) as <Result = Any, Query extends string = string>(\n      props: QueryClientProps<Result, Query>,\n    ) => ReactNode)\n\nconst noopEncodeDataAttribute: EncodeDataAttributeFunction = Object.assign(() => undefined, {\n  scope: () => noopEncodeDataAttribute,\n})\n\nexport interface QueryProps<Result = Any, Query extends string = string> extends Omit<\n  QueryClientProps<Result, Query>,\n  'options'\n> {\n  query: Query\n  params?: QueryParams | QueryWithoutParams\n  options: {\n    initial: ClientReturn<Query, Result> | QueryResponseInitial<ClientReturn<Query, Result>>\n  } & LoadQueryOptions<ClientReturn<Query, Result>>\n  children: (\n    data: ClientReturn<Query, Result>,\n    encodeDataAttribute: EncodeDataAttributeFunction,\n  ) => ReactNode\n}\n\n/**\n * Query component that provides live updates in preview mode and static data otherwise.\n *\n * @public\n */\nexport function Query<Result = Any, Query extends string = string>({\n  query,\n  params,\n  options,\n  children,\n  ...suspenseProps\n}: QueryProps<Result, Query> & Omit<SuspenseProps, 'children'>): ReactNode {\n  const isPreviewMode = usePreviewMode()\n  const isHydrated = useIsHydrated()\n\n  // If in preview mode and hydrated, render the client component\n  if (isPreviewMode && isHydrated) {\n    return (\n      <Suspense {...suspenseProps} fallback={suspenseProps.fallback ?? <SanityQueryFallback />}>\n        <QueryClient<Result, Query>\n          query={query}\n          params={params}\n          options={options as QueryClientProps<Result, Query>['options']}\n        >\n          {children}\n        </QueryClient>\n      </Suspense>\n    )\n  }\n\n  // Render static data in non-preview mode or during hydration\n  return children(options.initial as ClientReturn<Query, Result>, noopEncodeDataAttribute)\n}\n","import {useQuery as _useQuery, type UseQueryOptionsDefinedInitial} from '@sanity/react-loader'\nimport {useEffect, useId} from 'react'\n\nimport {registerQuery} from './registry'\n\n/**\n * Automatically registers with the query detection system.\n * This enables automatic live mode detection in `VisualEditing` components.\n */\nexport function useQuery<QueryResponseResult = unknown>(\n  query: string,\n  params?: Record<string, unknown>,\n  options?: UseQueryOptionsDefinedInitial<QueryResponseResult>,\n): ReturnType<typeof _useQuery<QueryResponseResult>> {\n  // Generate stable ID for this `useQuery` instance\n  const id = useId()\n\n  // Register this `useQuery` instance with the detection system\n  useEffect(() => {\n    const unregister = registerQuery(id)\n    return unregister\n  }, [id])\n\n  // Call the original `useQuery` with all the same arguments\n  return _useQuery<QueryResponseResult>(query, params, options)\n}\n"],"names":["apiVersion","_useQuery"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hydrogen-sanity",
-  "version": "5.1.3",
+  "version": "5.3.0",
   "description": "Sanity.io toolkit for Hydrogen",
   "keywords": [
     "sanity",
@@ -26,8 +26,36 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "provenance": true
+    "provenance": true,
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./preview": {
+        "import": "./dist/preview/index.js",
+        "default": "./dist/preview/index.js"
+      },
+      "./preview/route": {
+        "import": "./dist/preview/route.js",
+        "default": "./dist/preview/route.js"
+      },
+      "./preview/session": {
+        "import": "./dist/preview/session.js",
+        "default": "./dist/preview/session.js"
+      },
+      "./visual-editing": {
+        "import": "./dist/visual-editing/index.js",
+        "default": "./dist/visual-editing/index.js"
+      },
+      "./vite": {
+        "import": "./dist/vite/index.js",
+        "default": "./dist/vite/index.js"
+      },
+      "./package.json": "./package.json"
+    }
   },
+  "browserslist": "extends @sanity/browserslist-config",
   "type": "module",
   "exports": {
     ".": {
@@ -106,6 +134,7 @@
     "@sanity/preview-url-secret": "^2.1.14",
     "@sanity/react-loader": "^1.11.18",
     "@sanity/visual-editing": "^3.0.3",
+    "fast-deep-equal": "^3.1.3",
     "use-effect-event": "^2.0.3"
   },
   "devDependencies": {
@@ -139,7 +168,7 @@
   "peerDependencies": {
     "@sanity/client": "^7",
     "@shopify/hydrogen": "~2025.5.0 || ~2025.7.0",
-    "react": "^18.2.0",
+    "react": "^18.2.0 || ^19.0.0",
     "react-router": "^7.6.0",
     "vite": "^5.1.0 || ^6.2.1"
   },

package/src/context.test.ts

@@ -439,6 +439,131 @@ describe('stegaEnabled serialization', () => {
   })
 })
 
+describe('perspective resolution priority', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should use URL param perspective over session value', async () => {
+    const previewSession = new PreviewSession()
+    previewSession.set('projectId', projectId)
+    previewSession.set('perspective', 'drafts')
+
+    const request = new Request('https://example.com/?sanity-preview-perspective=releaseId,drafts')
+
+    const context = await createSanityContext({
+      request,
+      cache,
+      client,
+      preview: {
+        token: 'my-token',
+        session: previewSession,
+      },
+    })
+
+    expect(context.client.config().perspective).toEqual(['releaseId', 'drafts'])
+  })
+
+  it('should fall back to session perspective when URL param is absent', async () => {
+    const previewSession = new PreviewSession()
+    previewSession.set('projectId', projectId)
+    previewSession.set('perspective', 'drafts')
+
+    const request = new Request('https://example.com/')
+
+    const context = await createSanityContext({
+      request,
+      cache,
+      client,
+      preview: {
+        token: 'my-token',
+        session: previewSession,
+      },
+    })
+
+    expect(context.client.config().perspective).toEqual(['drafts'])
+  })
+
+  it('should pass perspective explicitly to loadQuery in preview mode', async () => {
+    const previewSession = new PreviewSession()
+    previewSession.set('projectId', projectId)
+    previewSession.set('perspective', 'drafts')
+
+    const request = new Request('https://example.com/?sanity-preview-perspective=releaseId,drafts')
+
+    const context = await createSanityContext({
+      request,
+      cache,
+      client,
+      preview: {
+        token: 'my-token',
+        session: previewSession,
+      },
+    })
+
+    await context.loadQuery<boolean>(query, params)
+
+    expect(loadQuery).toHaveBeenCalledWith(
+      query,
+      params,
+      expect.objectContaining({
+        perspective: ['releaseId', 'drafts'],
+      }),
+    )
+  })
+
+  it('should ignore URL param perspective stack when API version is too old', async () => {
+    const previewSession = new PreviewSession()
+    previewSession.set('projectId', projectId)
+
+    const oldClient = createClient({
+      projectId,
+      dataset: 'my-dataset',
+      apiVersion: '2024-01-01',
+    })
+
+    const request = new Request('https://example.com/?sanity-preview-perspective=releaseId,drafts')
+
+    const context = await createSanityContext({
+      request,
+      cache,
+      client: oldClient,
+      preview: {
+        token: 'my-token',
+        session: previewSession,
+      },
+    })
+
+    // Should fall back to previewDrafts since API version doesn't support stacks
+    expect(context.client.config().perspective).toBe('previewDrafts')
+  })
+
+  it('should accept single URL param perspective even with old API version', async () => {
+    const previewSession = new PreviewSession()
+    previewSession.set('projectId', projectId)
+
+    const oldClient = createClient({
+      projectId,
+      dataset: 'my-dataset',
+      apiVersion: '2024-01-01',
+    })
+
+    const request = new Request('https://example.com/?sanity-preview-perspective=drafts')
+
+    const context = await createSanityContext({
+      request,
+      cache,
+      client: oldClient,
+      preview: {
+        token: 'my-token',
+        session: previewSession,
+      },
+    })
+
+    expect(context.client.config().perspective).toBe('drafts')
+  })
+})
+
 describe('lazy-initialize loaders', () => {
   const request = new Request('https://example.com')
 
@@ -456,22 +581,21 @@ describe('lazy-initialize loaders', () => {
     expect(setServerClient).not.toHaveBeenCalled()
   })
 
-  it('should allow `loadQuery` to be called not in preview mode', async () => {
+  it('should call `setServerClient` on every `loadQuery` invocation', async () => {
     const context = await createSanityContext({
       request,
       cache,
       client,
     })
 
-    // loadQuery should work in non-preview mode (backwards compatibility)
-    // The actual loadQuery function will be called from the mocked module
     await context.loadQuery<boolean>(query, params)
+    expect(setServerClient).toHaveBeenCalledTimes(1)
 
-    // Verify the mock was called (actual behavior testing is done in other tests)
-    expect(loadQuery).toHaveBeenCalled()
+    await context.loadQuery<boolean>(query, params)
+    expect(setServerClient).toHaveBeenCalledTimes(2)
   })
 
-  it('should call `setServerClient` on first `loadQuery` invocation in preview mode', async () => {
+  it('should call `setServerClient` with the preview-configured client', async () => {
     const previewSession = new PreviewSession()
     previewSession.set('projectId', projectId)
 
@@ -485,17 +609,11 @@ describe('lazy-initialize loaders', () => {
       },
     })
 
-    // First call to `loadQuery`
     await context.loadQuery<boolean>(query, params)
 
-    // Should be called with the preview-configured client
-    // Check the most recent call
-    const latestCall = setServerClient.mock.calls[setServerClient.mock.calls.length - 1]
-    if (latestCall) {
-      const calledWithClient = latestCall[0]
-      expect(calledWithClient.config().useCdn).toBe(false)
-      expect(calledWithClient.config().token).toBe('my-token')
-    }
+    const calledWithClient = setServerClient.mock.calls[0][0]
+    expect(calledWithClient.config().useCdn).toBe(false)
+    expect(calledWithClient.config().token).toBe('my-token')
   })
 
   it('should display warning when `loadQuery` called outside preview mode in development', async () => {

package/src/context.ts

@@ -18,13 +18,12 @@ import type {SanityPreviewSession} from './preview/session'
 import {isPreviewEnabled} from './preview/utils'
 import {SanityProvider, type SanityProviderValue} from './provider'
 import type {CacheActionFunctionParam, WaitUntil} from './types'
-import {getPerspective} from './utils'
+import {getPerspective, getPerspectiveFromUrl} from './utils'
 import {hashQuery, supportsPerspectiveStack} from './utils'
 
 let didWarnAboutNoApiVersion = false
 let didWarnAboutNoPerspectiveSupport = false
 let didWarnAboutLoadQuery = false
-let didInitializeLoader = false
 
 export type CreateSanityContextOptions = {
   request: Request
@@ -213,7 +212,16 @@ You can find the latest version in the Sanity changelog: https://www.sanity.io/c
     if (previewEnabled) {
       const apiVersion = client.config().apiVersion
       let perspective: ClientPerspective
-      if (supportsPerspectiveStack(apiVersion)) {
+
+      // Prefer URL param over session — the cookie may lag behind the iframe reload.
+      const urlPerspective = getPerspectiveFromUrl(request.url)
+
+      if (
+        urlPerspective !== undefined &&
+        !(Array.isArray(urlPerspective) && !supportsPerspectiveStack(apiVersion))
+      ) {
+        perspective = urlPerspective
+      } else if (supportsPerspectiveStack(apiVersion)) {
         perspective = getPerspective(preview.session)
       } else {
         if (process.env.NODE_ENV === 'development' && !didWarnAboutNoPerspectiveSupport) {
@@ -256,12 +264,8 @@ You can find the latest version in the Sanity changelog: https://www.sanity.io/c
       params: QueryParams | QueryWithoutParams,
       loaderOptions?: LoadQueryOptions<ClientReturn<Query, Result>>,
     ): Promise<QueryResponseInitial<ClientReturn<Query, Result>>> {
-      // Lazy initialize the loader on first call with the configured client
-      if (!didInitializeLoader) {
-        const {setServerClient} = await import('@sanity/react-loader')
-        setServerClient(client)
-        didInitializeLoader = true
-      }
+      const {setServerClient} = await import('@sanity/react-loader')
+      setServerClient(client)
 
       // Warn users to migrate to `query` method when using loadQuery outside preview mode
       if (!previewEnabled && process.env.NODE_ENV === 'development' && !didWarnAboutLoadQuery) {
@@ -273,7 +277,12 @@ You can find the latest version in the Sanity changelog: https://www.sanity.io/c
 
       if (!withCache || previewEnabled) {
         const {loadQuery} = await import('@sanity/react-loader')
-        return await loadQuery<ClientReturn<Query, Result>>(query, params, loaderOptions)
+        // Override the singleton's possibly-stale perspective with the per-request value.
+        const resolvedOptions =
+          previewEnabled && !loaderOptions?.perspective
+            ? {...loaderOptions, perspective: client.config().perspective as ClientPerspective}
+            : loaderOptions
+        return await loadQuery<ClientReturn<Query, Result>>(query, params, resolvedOptions)
       }
 
       const cacheStrategy =

package/src/index.ts

@@ -3,6 +3,7 @@ export {createSanityContext, type SanityContext} from './context'
 export {useImageUrl, useImageUrlBuilder} from './image'
 export {Sanity, useSanityProviderValue} from './provider'
 export {Query, type QueryProps} from './Query'
+export {getPerspectiveFromUrl} from './utils'
 export {useQuery} from './visual-editing/useQuery'
 export type {EncodeDataAttributeFunction} from '@sanity/core-loader/encode-data-attribute'
 export type * from '@sanity/react-loader'

package/src/utils.test.ts

@@ -2,7 +2,7 @@ import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {PreviewSession} from './fixtures'
 import {isPreviewEnabled} from './preview/utils'
-import {getPerspective} from './utils'
+import {getPerspective, getPerspectiveFromUrl} from './utils'
 import {sanitizePerspective, supportsPerspectiveStack} from './utils'
 
 describe('sanitizePerspective', () => {
@@ -17,6 +17,20 @@ describe('sanitizePerspective', () => {
 
     expect(result).toBe('drafts')
   })
+
+  it('should filter out empty strings from perspective array', () => {
+    // This happens when upstream sends [undefined, "releaseId", "drafts"]
+    // which gets serialized as ",releaseId,drafts" and split back
+    const result = sanitizePerspective(',releaseId,drafts')
+
+    expect(result).toEqual(['releaseId', 'drafts'])
+  })
+
+  it('should filter out multiple empty strings', () => {
+    const result = sanitizePerspective('drafts,,published,')
+
+    expect(result).toEqual(['drafts', 'published'])
+  })
 })
 
 describe('supportsPerspectiveStack', () => {
@@ -79,6 +93,57 @@ describe('getPerspective', () => {
     expect(result).toEqual(['drafts', 'published'])
     expect(mockSession.get).toHaveBeenCalledWith('perspective')
   })
+
+  it('should filter out empty strings from perspective array', () => {
+    // This happens when upstream sends [undefined, "releaseId", "drafts"]
+    // which gets serialized as ",releaseId,drafts"
+    mockSession.get.mockReturnValue(',releaseId,drafts')
+
+    const result = getPerspective(mockSession)
+
+    expect(result).toEqual(['releaseId', 'drafts'])
+  })
+})
+
+describe('getPerspectiveFromUrl', () => {
+  it('should return parsed perspective when URL param is present and valid', () => {
+    expect(getPerspectiveFromUrl('https://example.com/?sanity-preview-perspective=drafts')).toBe(
+      'drafts',
+    )
+  })
+
+  it('should return undefined when param is absent', () => {
+    expect(getPerspectiveFromUrl('https://example.com/')).toBeUndefined()
+  })
+
+  it('should return undefined when param is empty', () => {
+    expect(
+      getPerspectiveFromUrl('https://example.com/?sanity-preview-perspective='),
+    ).toBeUndefined()
+  })
+
+  it('should handle comma-separated perspective stacks', () => {
+    expect(
+      getPerspectiveFromUrl('https://example.com/?sanity-preview-perspective=releaseId,drafts'),
+    ).toEqual(['releaseId', 'drafts'])
+  })
+
+  it('should filter empty segments from perspective stacks', () => {
+    expect(
+      getPerspectiveFromUrl('https://example.com/?sanity-preview-perspective=,releaseId,drafts'),
+    ).toEqual(['releaseId', 'drafts'])
+  })
+
+  it('should convert raw to drafts', () => {
+    expect(getPerspectiveFromUrl('https://example.com/?sanity-preview-perspective=raw')).toBe(
+      'drafts',
+    )
+  })
+
+  it('should accept a URL object', () => {
+    const url = new URL('https://example.com/?sanity-preview-perspective=drafts')
+    expect(getPerspectiveFromUrl(url)).toBe('drafts')
+  })
 })
 
 describe('isPreviewEnabled', () => {

package/src/utils.ts

@@ -4,6 +4,7 @@ import {
   type QueryWithoutParams,
   validateApiPerspective,
 } from '@sanity/client'
+import {urlSearchParamPreviewPerspective} from '@sanity/preview-url-secret/constants'
 import type {HydrogenSession} from '@shopify/hydrogen'
 
 import type {SanityPreviewSession} from './preview/session'
@@ -45,11 +46,18 @@ export function hashQuery(
  * Handles both string (comma-separated) and array formats.
  */
 export function sanitizePerspective(perspective: unknown): Exclude<ClientPerspective, 'raw'> {
-  const sanitizedPerspective =
+  let sanitizedPerspective =
     typeof perspective === 'string' && perspective.includes(',')
       ? perspective.split(',')
       : perspective
 
+  // Filter out empty strings and undefined values from perspective array
+  if (Array.isArray(sanitizedPerspective)) {
+    sanitizedPerspective = sanitizedPerspective.filter(
+      (p): p is string => typeof p === 'string' && p.length > 0,
+    )
+  }
+
   validateApiPerspective(sanitizedPerspective)
 
   return sanitizedPerspective === 'raw' ? 'drafts' : sanitizedPerspective
@@ -80,11 +88,29 @@ export function supportsPerspectiveStack(apiVersion: string): boolean {
  * Extracts and validates the perspective from a session.
  */
 export function getPerspective(session: SanityPreviewSession | HydrogenSession): ClientPerspective {
-  const perspective = session.get('perspective')?.split(',')
+  const perspective = session
+    .get('perspective')
+    ?.split(',')
+    .filter((p: string) => p.length > 0)
   validateApiPerspective(perspective)
   return perspective
 }
 
+/**
+ * Reads the `sanity-preview-perspective` URL search param and validates it.
+ * Returns `undefined` if absent or invalid, so callers can fall back to the session.
+ */
+export function getPerspectiveFromUrl(url: URL | string): ClientPerspective | undefined {
+  try {
+    const parsed = typeof url === 'string' ? new URL(url) : url
+    const param = parsed.searchParams.get(urlSearchParamPreviewPerspective)
+    if (!param) return undefined
+    return sanitizePerspective(param)
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Type guard that checks if a session object is a SanityPreviewSession.
  * Validates presence of required methods: has, destroy (in addition to Hydrogen session methods).

package/src/visual-editing/LiveMode.client.tsx

@@ -1,6 +1,7 @@
 import {createClient, type StegaConfig} from '@sanity/client'
 import {useLiveMode} from '@sanity/react-loader'
-import {type ReactNode, useEffect, useMemo} from 'react'
+import isEqual from 'fast-deep-equal'
+import {type ReactNode, useEffect, useMemo, useState} from 'react'
 
 import {useSanityProviderValue} from '../provider'
 import {isServer} from '../utils'
@@ -45,7 +46,18 @@ function LiveModeClient(props: LiveModeProps): ReactNode {
 
   const sanityProvider = useSanityProviderValue()
 
-  // eslint-disable-next-line react-hooks/preserve-manual-memoization
+  // Maintain reference stability for stegaProps when content is unchanged
+  // This prevents unnecessary client recreation when parent component re-renders
+  const [stableStegaProps, setStableStegaProps] = useState(stegaProps)
+  useEffect(() => {
+    if (!isEqual(stableStegaProps, stegaProps)) {
+      setStableStegaProps(stegaProps)
+    }
+    // Intentionally not including stableStegaProps in deps - we only want to
+    // update when the incoming stegaProps changes, comparing against the stored value
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [stegaProps])
+
   const client = useMemo(() => {
     const baseClient = createClient({
       projectId: sanityProvider.projectId,
@@ -56,11 +68,11 @@ function LiveModeClient(props: LiveModeProps): ReactNode {
     })
 
     // Apply stega configuration if provided
-    if (sanityProvider.stegaEnabled && Object.keys(stegaProps).length > 0) {
+    if (sanityProvider.stegaEnabled && Object.keys(stableStegaProps).length > 0) {
       return baseClient.withConfig({
         stega: {
           enabled: true,
-          ...stegaProps,
+          ...stableStegaProps,
         },
       })
     }
@@ -72,8 +84,7 @@ function LiveModeClient(props: LiveModeProps): ReactNode {
     sanityProvider.perspective,
     sanityProvider.apiVersion,
     sanityProvider.stegaEnabled,
-    // eslint-disable-next-line react-hooks/preserve-manual-memoization
-    stegaProps,
+    stableStegaProps,
   ])
 
   // Enable live mode for real-time data updates (client loaders only)
@@ -83,11 +94,9 @@ function LiveModeClient(props: LiveModeProps): ReactNode {
     onDisconnect,
   })
 
-  // Automatically handle revalidator state changes
-  const {handleRevalidatorState} = useRefresh()
-  useEffect(() => {
-    handleRevalidatorState()
-  })
+  // Initialize refresh hook to handle revalidator state transitions
+  // The hook internally manages state changes via useEffect
+  useRefresh()
 
   return null
 }

package/src/visual-editing/Overlays.client.tsx

@@ -9,7 +9,7 @@ import {type ReactNode, useEffect, useState} from 'react'
 import {useRevalidator, useSubmit} from 'react-router'
 import {useEffectEvent} from 'use-effect-event'
 
-import {isServer} from '../utils'
+import {isServer, sanitizePerspective} from '../utils'
 import {useHistory} from './hooks/history'
 import {useRefresh} from './hooks/refresh'
 import {useHasActiveLoaders} from './registry'
@@ -82,8 +82,14 @@ function OverlaysClient(props: OverlaysProps): ReactNode {
 
   // Handle perspective changes from Studio
   const handlePerspectiveChange = useEffectEvent((perspective: ClientPerspective) => {
+    // Sanitize perspective (filters out undefined/empty values from upstream bug)
+    const cleanPerspective = sanitizePerspective(perspective)
+
     const formData = new FormData()
-    formData.set('perspective', Array.isArray(perspective) ? perspective.join(',') : perspective)
+    formData.set(
+      'perspective',
+      Array.isArray(cleanPerspective) ? cleanPerspective.join(',') : cleanPerspective,
+    )
     submit(formData, {
       method: 'PUT',
       action,

package/src/visual-editing/hooks/history.ts

@@ -11,18 +11,23 @@ export function useHistory(): HistoryAdapter {
   const navigateRemixRef = useRef(navigateRemix)
   const [navigate, setNavigate] = useState<HistoryAdapterNavigate | undefined>()
   const location = useLocation()
+  // Track programmatic navigations to avoid duplicate notifications to Studio
+  const isProgrammaticNavRef = useRef(false)
 
   useEffect(() => {
     navigateRemixRef.current = navigateRemix
   }, [navigateRemix])
 
   useEffect(() => {
-    if (navigate) {
+    // Skip notification for programmatic navigations (initiated by Studio)
+    // to avoid duplicate notifications and potential infinite loops
+    if (navigate && !isProgrammaticNavRef.current) {
       navigate({
         type: 'push',
         url: `${location.pathname}${location.search}${location.hash}`,
       })
     }
+    isProgrammaticNavRef.current = false
   }, [location.hash, location.pathname, location.search, navigate])
 
   const historyAdapter: HistoryAdapter = useMemo(
@@ -32,6 +37,8 @@ export function useHistory(): HistoryAdapter {
         return () => setNavigate(undefined)
       },
       update(update: HistoryUpdate) {
+        // Mark as programmatic navigation to skip notification in the location effect
+        isProgrammaticNavRef.current = true
         if (update.type === 'push' || update.type === 'replace') {
           navigateRemixRef.current(update.url, {
             replace: update.type === 'replace',

package/src/visual-editing/hooks/refresh.ts

@@ -1,6 +1,7 @@
 import type {HistoryRefresh} from '@sanity/visual-editing'
-import {useCallback, useState} from 'react'
+import {startTransition, useCallback, useEffect, useState} from 'react'
 import {useRevalidator} from 'react-router'
+import {useEffectEvent} from 'use-effect-event'
 
 import type {Revalidator} from '../types'
 
@@ -16,22 +17,28 @@ export function useRefresh(): {
       revalidator: Revalidator,
     ) => false | Promise<void>,
   ) => (payload: HistoryRefresh) => false | Promise<void>
-  handleRevalidatorState: () => void
-  revalidatorState: Revalidator['state']
 } {
   const revalidator = useRevalidator()
   const [revalidatorPromise, setRevalidatorPromise] = useState<(() => void) | null>(null)
   const [revalidatorLoading, setRevalidatorLoading] = useState(false)
 
-  const handleRevalidatorState = useCallback(() => {
+  // Handle revalidator state transitions internally
+  const handleRevalidatorState = useEffectEvent(() => {
     if (revalidatorPromise && revalidator.state === 'loading') {
-      setRevalidatorLoading(true)
+      startTransition(() => setRevalidatorLoading(true))
     } else if (revalidatorPromise && revalidatorLoading && revalidator.state === 'idle') {
       revalidatorPromise()
-      setRevalidatorPromise(null)
-      setRevalidatorLoading(false)
+      startTransition(() => {
+        setRevalidatorPromise(null)
+        setRevalidatorLoading(false)
+      })
     }
-  }, [revalidatorLoading, revalidator.state, revalidatorPromise])
+  })
+
+  // Automatically handle revalidator state changes
+  useEffect(() => {
+    handleRevalidatorState()
+  }, [revalidator.state])
 
   const createRefreshHandler = useCallback(
     (
@@ -69,7 +76,5 @@ export function useRefresh(): {
 
   return {
     refreshHandler: createRefreshHandler,
-    handleRevalidatorState,
-    revalidatorState: revalidator.state,
   }
 }