@sanity/sdk-react 3.0.0-rc.0 → 3.0.0-rc.2

package/src/components/errors/ChunkLoadError.tsx

@@ -0,0 +1,56 @@
+import {useEffect} from 'react'
+import {type FallbackProps} from 'react-error-boundary'
+
+import {clearChunkReloadFlag, readChunkReloadFlag, setChunkReloadFlag} from './chunkReloadStorage'
+import {Error} from './Error'
+
+function reload(): void {
+  try {
+    window.location.reload()
+  } catch {
+    // No-op: nothing useful we can do if reload itself throws.
+  }
+}
+
+/**
+ * Default fallback rendered when a dynamic-import or chunk-load error
+ * bubbles up to the SDK's top-level error boundary.
+ *
+ * On the first occurrence in a session we set a flag and trigger
+ * window.location.reload(), since chunk-load errors almost always indicate a
+ * stale tab that simply needs a fresh index.html. If the flag is already set
+ * we render a manual reload UI instead, which prevents an infinite reload
+ * loop in the rare case the error is genuinely unrecoverable (network
+ * outage, CSP, etc.).
+ *
+ * @internal
+ */
+export function ChunkLoadError(_props: FallbackProps): React.ReactNode {
+  const alreadyAttempted = readChunkReloadFlag()
+
+  useEffect(() => {
+    if (alreadyAttempted) return
+    setChunkReloadFlag()
+    reload()
+  }, [alreadyAttempted])
+
+  if (!alreadyAttempted) {
+    // Render nothing during the brief window before the page reloads so the
+    // user does not see a flash of error UI.
+    return null
+  }
+
+  return (
+    <Error
+      heading="A new version is available"
+      description="The page tried to load an asset that no longer exists. Reload to continue with the latest version."
+      cta={{
+        text: 'Reload page',
+        onClick: () => {
+          clearChunkReloadFlag()
+          reload()
+        },
+      }}
+    />
+  )
+}

package/src/components/errors/CorsErrorComponent.tsx

@@ -1,5 +1,5 @@
 import {useMemo} from 'react'
-import {type FallbackProps} from 'react-error-boundary'
+import {type FallbackProps, getErrorMessage} from 'react-error-boundary'
 
 import {Error} from './Error'
 
@@ -30,7 +30,7 @@ export function CorsErrorComponent({projectId, error}: CorsErrorComponentProps):
             },
           }
         : {
-            description: error?.message,
+            description: getErrorMessage(error),
           })}
     />
   )

package/src/components/errors/chunkReloadStorage.ts

@@ -0,0 +1,57 @@
+/**
+ * Session-storage key tracking whether the SDK has already attempted an
+ * automatic reload in response to a chunk-load error during this session.
+ *
+ * @internal
+ */
+export const CHUNK_RELOAD_STORAGE_KEY = '__sanity_sdk_chunk_reload_attempted'
+
+/**
+ * Returns true when this session has already triggered an automatic reload.
+ * Returns false if session storage is unreadable.
+ *
+ * @internal
+ */
+export function readChunkReloadFlag(): boolean {
+  try {
+    if (typeof window === 'undefined' || typeof window.sessionStorage === 'undefined') {
+      return false
+    }
+    return window.sessionStorage.getItem(CHUNK_RELOAD_STORAGE_KEY) !== null
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Marks the session as having attempted an automatic reload, so the next
+ * chunk-load error renders the manual reload UI instead of looping.
+ *
+ * @internal
+ */
+export function setChunkReloadFlag(): void {
+  try {
+    if (typeof window === 'undefined' || typeof window.sessionStorage === 'undefined') return
+    window.sessionStorage.setItem(CHUNK_RELOAD_STORAGE_KEY, '1')
+  } catch {
+    // Storage may be unavailable (private mode quotas, disabled cookies).
+    // Falling through means the user sees the manual-reload UI instead of an
+    // automatic reload, which is the correct degradation.
+  }
+}
+
+/**
+ * Clears the chunk-reload flag. Called from SDKProvider once the SDK
+ * mounts successfully past the error boundary so a future incident in the
+ * same session can trigger another automatic reload.
+ *
+ * @internal
+ */
+export function clearChunkReloadFlag(): void {
+  try {
+    if (typeof window === 'undefined' || typeof window.sessionStorage === 'undefined') return
+    window.sessionStorage.removeItem(CHUNK_RELOAD_STORAGE_KEY)
+  } catch {
+    // No-op: see setChunkReloadFlag.
+  }
+}

package/src/config/handles.ts

@@ -1,53 +1,55 @@
-import {type DocumentResource, type PerspectiveHandle} from '@sanity/sdk'
-
-// React-layer types — shadow core equivalents when imported from @sanity/sdk-react.
-// resource is optional here and resolved from context by normalization,
-// whereas core's DocumentHandle/ResourceHandle require resource explicitly.
+import {
+  type DatasetHandle,
+  type DocumentHandle as CoreDocumentHandle,
+  type DocumentTypeHandle as CoreDocumentTypeHandle,
+} from '@sanity/sdk'
 
 /**
- * SDK React ResourceHandle with optional explicit resource field.
- * Resource is resolved from context when not provided.
- * When a `resourceName` is provided, the resource will be resolved from the context using the `ResourcesContext`,
- * if there is a matching resource by that name.
+ * React SDK resource handle — extends the core DatasetHandle with `resourceName`
+ * for context-based resource resolution.
+ *
+ * Use this (or its subtypes) as the options type for custom hooks that need to
+ * accept a resource. It accepts a `resource` object, a `resourceName` registered
+ * via the `resources` prop on `<SanityApp>`, or a bare `projectId`/`dataset` pair
+ * for backward compatibility.
+ *
  * @public
  */
 export interface ResourceHandle<
-  TProjectId extends string = string,
   TDataset extends string = string,
-> {
-  resource?: DocumentResource<TProjectId, TDataset>
+  TProjectId extends string = string,
+> extends DatasetHandle<TDataset, TProjectId> {
+  /**
+   * Name of a resource registered via the `resources` prop on `<SanityApp>`.
+   * Resolved to a `DocumentResource` at the React layer.
+   */
   resourceName?: string
-  perspective?: PerspectiveHandle['perspective']
 }
 
 /**
- * SDK React DocumentTypeHandle with optional explicit resource field.
- * Resource is resolved from context when not provided.
- * When a `resourceName` is provided, the resource will be resolved from the context using the `ResourcesContext`,
- * if there is a matching resource by that name.
+ * React SDK document-type handle. Adds `resourceName` to the core `DocumentTypeHandle`.
  * @public
  */
 export interface DocumentTypeHandle<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends ResourceHandle<TProjectId, TDataset> {
-  documentType: TDocumentType
-  documentId?: string
-  liveEdit?: boolean
+> extends CoreDocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
+  resourceName?: string
 }
 
 /**
- * SDK React DocumentHandle with optional explicit resource field.
- * Resource is resolved from context when not provided.
- * When a `resourceName` is provided, the resource will be resolved from the context using the `ResourcesContext`,
- * if there is a matching resource by that name.
+ * React SDK document handle. Adds `resourceName` to the core `DocumentHandle`.
+ *
+ * Import from `@sanity/sdk-react` (not `@sanity/sdk`) when writing option types
+ * for hooks — this version understands `resourceName` resolution.
+ *
  * @public
  */
 export interface DocumentHandle<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
-  documentId: string
+> extends CoreDocumentHandle<TDocumentType, TDataset, TProjectId> {
+  resourceName?: string
 }

package/src/constants.ts

@@ -0,0 +1,5 @@
+/**
+ * The name of the resource automatically registered from a single-config `<SanityApp>`.
+ * Hooks that receive no resource information fall back to this named resource.
+ */
+export const DEFAULT_RESOURCE_NAME = 'default'

package/src/context/ComlinkTokenRefresh.test.tsx

@@ -56,10 +56,7 @@ describe('ComlinkTokenRefresh', () => {
       it('should not request new token on 401 if not in dashboard', async () => {
         mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
         const {rerender} = render(
-          <ResourceProvider
-            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-            fallback={null}
-          >
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>
@@ -72,10 +69,7 @@ describe('ComlinkTokenRefresh', () => {
         })
         act(() => {
           rerender(
-            <ResourceProvider
-              resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-              fallback={null}
-            >
+            <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
               <ComlinkTokenRefreshProvider>
                 <div>Test</div>
               </ComlinkTokenRefreshProvider>
@@ -98,10 +92,7 @@ describe('ComlinkTokenRefresh', () => {
       it('should initialize useWindowConnection with correct parameters when not in studio mode', () => {
         // Simulate studio mode disabled by default
         render(
-          <ResourceProvider
-            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-            fallback={null}
-          >
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>
@@ -133,10 +124,7 @@ describe('ComlinkTokenRefresh', () => {
         document.body.appendChild(errorContainer)
 
         render(
-          <ResourceProvider
-            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-            fallback={null}
-          >
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>
@@ -150,10 +138,11 @@ describe('ComlinkTokenRefresh', () => {
         expect(mockSetAuthToken).toHaveBeenCalledWith(expect.any(Object), 'new-token')
         expect(mockFetch).toHaveBeenCalledTimes(1)
         expect(mockFetch).toHaveBeenCalledWith('dashboard/v1/auth/tokens/create')
-        // Assert setAuthToken was called with a SanityInstance
+        // Assert setAuthToken was called with instance matching provider config
         const instanceArg = mockSetAuthToken.mock.calls[0][0]
-        expect(instanceArg).toHaveProperty('instanceId')
-        expect(instanceArg).toHaveProperty('config')
+        expect(instanceArg.config).toEqual(
+          expect.objectContaining({projectId: 'test-project', dataset: 'test-dataset'}),
+        )
         // Unauthorized error container should be removed
         expect(document.getElementById('__sanityError')).toBeNull()
       })
@@ -166,10 +155,7 @@ describe('ComlinkTokenRefresh', () => {
         mockFetch.mockResolvedValueOnce({token: null})
 
         render(
-          <ResourceProvider
-            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-            fallback={null}
-          >
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>
@@ -191,10 +177,7 @@ describe('ComlinkTokenRefresh', () => {
         mockFetch.mockRejectedValueOnce(new Error('Fetch failed'))
 
         render(
-          <ResourceProvider
-            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-            fallback={null}
-          >
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>

package/src/context/ComlinkTokenRefresh.tsx

@@ -1,15 +1,13 @@
 import {type ClientError} from '@sanity/client'
 import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {AuthStateType, getIsInDashboardState, setAuthToken} from '@sanity/sdk'
+import {isStudioConfig} from '@sanity/sdk/_internal'
 import {
-  AuthStateType,
   type FrameMessage,
-  getIsInDashboardState,
-  isStudioConfig,
   type NewTokenResponseMessage,
   type RequestNewTokenMessage,
-  setAuthToken,
   type WindowMessage,
-} from '@sanity/sdk'
+} from '@sanity/sdk/comlink'
 import React, {type PropsWithChildren, useCallback, useEffect, useMemo, useRef} from 'react'
 
 import {useAuthState} from '../hooks/auth/useAuthState'

package/src/context/DefaultResourceContext.ts

@@ -2,9 +2,9 @@ import {type DocumentResource} from '@sanity/sdk'
 import {createContext} from 'react'
 
 /**
- * Provides the active resource for a subtree.
- * Set by `ResourceProvider` so hooks resolve the correct project/dataset
- * without requiring an explicit `resource` option.
+ * Provides the active DocumentResource for a subtree.
+ * Set by ResourceProvider; read by useNormalizedResourceOptions as a fallback
+ * when hooks receive no explicit resource or resourceName.
  * @internal
  */
 export const ResourceContext = createContext<DocumentResource | undefined>(undefined)

package/src/context/OrganizationResourcesProvider.test.tsx

@@ -0,0 +1,189 @@
+import {createSanityInstance, type DocumentResource} from '@sanity/sdk'
+import {act, render} from '@testing-library/react'
+import {type ReactNode, Suspense, useContext, useEffect} from 'react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useDashboardOrganizationId} from '../hooks/auth/useDashboardOrganizationId'
+import {resolveOrgResources} from '../utils/resolveOrgResources'
+import {OrganizationResourcesProvider} from './OrganizationResourcesProvider'
+import {ResourcesContext} from './ResourcesContext'
+
+function promiseWithResolvers<T>(): {
+  promise: Promise<T>
+  resolve: (value: T) => void
+} {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((res) => {
+    resolve = res
+  })
+  return {promise, resolve}
+}
+
+// Reset to a fresh instance per test so the module-level WeakMap cache (keyed by
+// instance) starts empty. `useSanityInstance` returns the same object across
+// renders within a test, which is what the cache relies on.
+let instance = createSanityInstance()
+
+vi.mock('../hooks/context/useSanityInstance', () => {
+  return {useSanityInstance: () => instance}
+})
+
+vi.mock('../hooks/auth/useDashboardOrganizationId', () => ({
+  useDashboardOrganizationId: vi.fn(),
+}))
+
+vi.mock('../utils/resolveOrgResources', () => ({
+  resolveOrgResources: vi.fn(),
+}))
+
+const mockResolveOrgResources = vi.mocked(resolveOrgResources)
+const mockUseDashboardOrganizationId = vi.mocked(useDashboardOrganizationId)
+
+describe('OrganizationResourcesProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    instance = createSanityInstance()
+    mockResolveOrgResources.mockResolvedValue({})
+    mockUseDashboardOrganizationId.mockReturnValue(undefined)
+  })
+
+  // Captures ResourcesContext via useEffect (side-effect territory, not render)
+  // to satisfy the react-compiler purity rule.
+  function makeCapture() {
+    const deferred = promiseWithResolvers<Record<string, DocumentResource>>()
+
+    const CaptureContexts = () => {
+      const resources = useContext(ResourcesContext)
+      useEffect(() => {
+        deferred.resolve(resources)
+      }, [resources])
+      return null
+    }
+
+    return {CaptureContexts, capturedResources: deferred.promise}
+  }
+
+  function renderProvider(
+    children: ReactNode,
+    options?: {
+      resources?: Record<string, DocumentResource>
+      inferMediaLibraryAndCanvas?: boolean
+    },
+  ) {
+    return render(
+      <Suspense fallback={<div>loading</div>}>
+        <OrganizationResourcesProvider
+          resources={options?.resources}
+          inferMediaLibraryAndCanvas={options?.inferMediaLibraryAndCanvas}
+        >
+          {children}
+        </OrganizationResourcesProvider>
+      </Suspense>,
+    )
+  }
+
+  it('does not suspend when inferMediaLibraryAndCanvas is not set', async () => {
+    const {CaptureContexts, capturedResources} = makeCapture()
+    renderProvider(<CaptureContexts />)
+    const resources = await capturedResources
+    expect(Object.keys(resources)).toHaveLength(0)
+    expect(mockResolveOrgResources).not.toHaveBeenCalled()
+  })
+
+  it('suspends children while org resources are being fetched, then renders with resolved resources', async () => {
+    mockUseDashboardOrganizationId.mockReturnValue('org-suspend-test')
+    const {promise, resolve} = promiseWithResolvers<void>()
+    mockResolveOrgResources.mockReturnValue(
+      promise.then(() => ({
+        mediaLibrary: {mediaLibraryId: 'ml-id'},
+        canvas: {canvasId: 'canvas-id'},
+      })) as ReturnType<typeof mockResolveOrgResources>,
+    )
+
+    const {CaptureContexts, capturedResources} = makeCapture()
+    await act(async () => {
+      renderProvider(<CaptureContexts />, {inferMediaLibraryAndCanvas: true})
+    })
+
+    await act(async () => {
+      resolve()
+    })
+
+    const resources = await capturedResources
+    expect(resources['media-library']).toEqual({mediaLibraryId: 'ml-id'})
+    expect(resources['canvas']).toEqual({canvasId: 'canvas-id'})
+  })
+
+  it('renders without inferred entries and logs a warning when resolveOrgResources rejects', async () => {
+    mockUseDashboardOrganizationId.mockReturnValue('org-warn-test')
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    mockResolveOrgResources.mockRejectedValue(new Error('fetch failed'))
+
+    const {CaptureContexts, capturedResources} = makeCapture()
+    await act(async () => {
+      renderProvider(<CaptureContexts />, {inferMediaLibraryAndCanvas: true})
+    })
+
+    const resources = await capturedResources
+    expect(resources['media-library']).toBeUndefined()
+    expect(resources['canvas']).toBeUndefined()
+    expect(consoleSpy).toHaveBeenCalledWith(
+      '[sanity/sdk] Failed to infer org resources:',
+      expect.any(Error),
+    )
+    consoleSpy.mockRestore()
+  })
+
+  it('caches Promise references across providers for the same instance', () => {
+    mockUseDashboardOrganizationId.mockReturnValue('org-cache-test')
+    render(
+      <Suspense fallback={null}>
+        <OrganizationResourcesProvider inferMediaLibraryAndCanvas>
+          {null}
+        </OrganizationResourcesProvider>
+      </Suspense>,
+    )
+    render(
+      <Suspense fallback={null}>
+        <OrganizationResourcesProvider inferMediaLibraryAndCanvas>
+          {null}
+        </OrganizationResourcesProvider>
+      </Suspense>,
+    )
+
+    // resolveOrgResources should only have been called once across both providers.
+    expect(mockResolveOrgResources).toHaveBeenCalledTimes(1)
+  })
+
+  it('explicit resources are passed through to ResourcesContext', async () => {
+    const explicitResources = {
+      default: {projectId: 'p1', dataset: 'prod'},
+      secondary: {projectId: 'p2', dataset: 'staging'},
+    }
+
+    const {CaptureContexts, capturedResources} = makeCapture()
+    renderProvider(<CaptureContexts />, {resources: explicitResources})
+
+    expect(await capturedResources).toEqual(explicitResources)
+  })
+
+  it('explicit resources take precedence over inferred ones', async () => {
+    mockUseDashboardOrganizationId.mockReturnValue('org-override-test')
+    mockResolveOrgResources.mockResolvedValue({
+      mediaLibrary: {mediaLibraryId: 'inferred-ml'},
+      canvas: {canvasId: 'inferred-canvas'},
+    })
+
+    const explicitResources = {'media-library': {mediaLibraryId: 'explicit-ml'}}
+    const {CaptureContexts, capturedResources} = makeCapture()
+    await act(async () => {
+      renderProvider(<CaptureContexts />, {
+        resources: explicitResources,
+        inferMediaLibraryAndCanvas: true,
+      })
+    })
+
+    const resources = await capturedResources
+    expect(resources['media-library']).toEqual({mediaLibraryId: 'explicit-ml'})
+  })
+})

package/src/context/OrganizationResourcesProvider.tsx

@@ -0,0 +1,111 @@
+import {type DocumentResource, type SanityInstance} from '@sanity/sdk'
+import {type ReactElement, type ReactNode, use, useMemo} from 'react'
+
+import {useDashboardOrganizationId} from '../hooks/auth/useDashboardOrganizationId'
+import {useSanityInstance} from '../hooks/context/useSanityInstance'
+import {resolveOrgResources} from '../utils/resolveOrgResources'
+import {ResourcesContext} from './ResourcesContext'
+
+const DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME = 'media-library'
+const DEFAULT_CANVAS_RESOURCE_NAME = 'canvas'
+
+type OrgResource = typeof DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME | typeof DEFAULT_CANVAS_RESOURCE_NAME
+type OrgResourcePromises = Map<OrgResource, PromiseLike<DocumentResource | undefined>>
+
+// Module-level cache keyed by SanityInstance so Promise references are stable
+// across Suspense unmount/remount cycles. React's use() tracks promises by
+// identity, so stable references prevent unnecessary re-suspensions.
+// WeakMap entries are GC'd when the instance is disposed.
+// There is only ever one org at a time, so the instance alone is a sufficient
+// key — organizationId only scopes the fetch, it doesn't need to key the cache.
+const inferredResourceCache = new WeakMap<SanityInstance, OrgResourcePromises>()
+
+function getOrgResourcePromises(
+  instance: SanityInstance,
+  organizationId: string,
+): OrgResourcePromises {
+  let promises = inferredResourceCache.get(instance)
+  if (!promises) {
+    const basePromise = resolveOrgResources(instance, organizationId).then(
+      (result) => result,
+      (error) => {
+        // eslint-disable-next-line no-console
+        console.warn('[sanity/sdk] Failed to infer org resources:', error)
+        return {mediaLibrary: undefined, canvas: undefined}
+      },
+    )
+    promises = new Map([
+      [DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME, basePromise.then((r) => r.mediaLibrary)],
+      [DEFAULT_CANVAS_RESOURCE_NAME, basePromise.then((r) => r.canvas)],
+    ])
+    inferredResourceCache.set(instance, promises)
+  }
+
+  return promises
+}
+
+/**
+ * Inner component that suspends via use() until both inference promises settle.
+ * Requires a Suspense boundary from the caller (usually a top ResourceProvider).
+ */
+function InferredResourcesProvider({
+  instance,
+  orgId,
+  explicitResources,
+  children,
+}: {
+  instance: SanityInstance
+  orgId: string
+  explicitResources: Record<string, DocumentResource>
+  children: ReactNode
+}): ReactElement {
+  const promises = getOrgResourcePromises(instance, orgId)
+  const ml = use(promises.get(DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME)!)
+  const canvas = use(promises.get(DEFAULT_CANVAS_RESOURCE_NAME)!)
+
+  const resources = useMemo(() => {
+    const inferred: Record<string, DocumentResource> = {}
+    if (ml !== undefined) inferred[DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME] = ml
+    if (canvas !== undefined) inferred[DEFAULT_CANVAS_RESOURCE_NAME] = canvas
+    return {...inferred, ...explicitResources}
+  }, [ml, canvas, explicitResources])
+
+  return <ResourcesContext.Provider value={resources}>{children}</ResourcesContext.Provider>
+}
+
+/**
+ * When `inferMediaLibraryAndCanvas` is set, this component suspends until
+ * inference resolves. The nearest Suspense boundary (e.g. from ResourceProvider)
+ * shows its fallback during that window.
+
+ * If a user explicitly names a 'media-library' or 'canvas' resource,
+ * this component will use that resource instead of inferring it.
+ */
+export function OrganizationResourcesProvider({
+  resources: explicitResources = {},
+  inferMediaLibraryAndCanvas,
+  children,
+}: {
+  resources?: Record<string, DocumentResource>
+  inferMediaLibraryAndCanvas?: boolean
+  children: ReactNode
+}): ReactElement {
+  const instance = useSanityInstance()
+  const orgId = useDashboardOrganizationId()
+
+  if (!inferMediaLibraryAndCanvas || !orgId) {
+    return (
+      <ResourcesContext.Provider value={explicitResources}>{children}</ResourcesContext.Provider>
+    )
+  }
+
+  return (
+    <InferredResourcesProvider
+      instance={instance}
+      orgId={orgId}
+      explicitResources={explicitResources}
+    >
+      {children}
+    </InferredResourcesProvider>
+  )
+}

package/src/context/PerspectiveContext.ts

@@ -2,9 +2,9 @@ import {type PerspectiveHandle} from '@sanity/sdk'
 import {createContext} from 'react'
 
 /**
- * Provides a perspective override for nested subtrees.
- * Set by `ResourceProvider` so hooks resolve the correct perspective
- * without requiring an explicit `perspective` option.
+ * Provides the active perspective for a subtree.
+ * Set by ResourceProvider; injected by useNormalizedResourceOptions when
+ * the hook's options don't include an explicit perspective.
  * @internal
  */
 export const PerspectiveContext = createContext<PerspectiveHandle['perspective'] | undefined>(

package/src/context/ProjectContext.ts

@@ -0,0 +1,15 @@
+import {createContext} from 'react'
+
+/**
+ * Carries a `projectId` for a subtree even when a complete
+ * `DatasetResource` can't be formed — e.g. a `<ResourceProvider projectId="…">`
+ * with no `dataset` and no parent resource to inherit one from.
+ *
+ * Project-scoped hooks (`useProject`, `useDatasets`, `useUsers`) read this as a
+ * fallback so they can still resolve a project in that case (the only hooks that would work with a config like this.)
+ *
+ * @remarks Temporary bridge for the dataset-less project scope.
+ * Remove in the next major version; those hooks should just always use a projectId or default to a resource available.
+ * @internal
+ */
+export const ProjectContext = createContext<string | undefined>(undefined)