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

package/dist/index.d.ts

@@ -4,28 +4,24 @@ import {AgentPatchOptions} from '@sanity/sdk'
 import {AgentPatchResult} from '@sanity/sdk'
 import {AgentPromptOptions} from '@sanity/sdk'
 import {AgentPromptResult} from '@sanity/sdk'
+import {AgentResourceOptions} from '@sanity/sdk'
 import {AgentTransformOptions} from '@sanity/sdk'
 import {AgentTranslateOptions} from '@sanity/sdk'
-import {ApplyDocumentActionsOptions} from '@sanity/sdk'
 import {AuthState} from '@sanity/sdk'
 import {CanvasResource} from '@sanity/message-protocol'
 import {ClientOptions} from '@sanity/sdk'
 import {Context} from 'react'
 import {CurrentUser} from '@sanity/sdk'
-import {DatasetHandle} from '@sanity/sdk'
 import {DatasetsResponse} from '@sanity/client'
 import {DocumentAction} from '@sanity/sdk'
 import {DocumentEvent} from '@sanity/sdk'
-import {DocumentHandle} from '@sanity/sdk'
-import {DocumentOptions} from '@sanity/sdk'
 import {DocumentPermissionsResult} from '@sanity/sdk'
-import {DocumentSource} from '@sanity/sdk'
+import {DocumentResource} from '@sanity/sdk'
 import {FallbackProps} from 'react-error-boundary'
 import {FavoriteStatusResponse} from '@sanity/sdk'
 import {FrameMessage} from '@sanity/sdk'
 import {GetUserOptions} from '@sanity/sdk'
 import {GetUsersOptions} from '@sanity/sdk'
-import {JsonMatch} from '@sanity/sdk'
 import {MediaResource} from '@sanity/message-protocol'
 import {PathChangeMessage} from '@sanity/message-protocol'
 import {PerspectiveHandle} from '@sanity/sdk'
@@ -40,15 +36,15 @@ import {ReleaseDocument} from '@sanity/sdk'
 import {SanityClient} from '@sanity/client'
 import {SanityConfig} from '@sanity/sdk'
 import {SanityDocument} from '@sanity/types'
-import {SanityDocument as SanityDocument_2} from 'groq'
 import {SanityInstance} from '@sanity/sdk'
 import {SanityProject} from '@sanity/sdk'
 import {SanityProject as SanityProject_2} from '@sanity/client'
-import {SanityProjectionResult} from 'groq'
 import {SanityProjectMember} from '@sanity/client'
-import {SanityQueryResult} from 'groq'
 import {SanityUser} from '@sanity/sdk'
 import {SortOrderingItem} from '@sanity/types'
+import {DocumentHandle as StrictDocumentHandle} from '@sanity/sdk'
+import {DocumentTypeHandle as StrictDocumentTypeHandle} from '@sanity/sdk'
+import {ResourceHandle as StrictResourceHandle} from '@sanity/sdk'
 import {StudioResource} from '@sanity/message-protocol'
 import {TokenSource} from '@sanity/sdk'
 import {UserPresence} from '@sanity/sdk'
@@ -178,6 +174,21 @@ declare interface DispatchIntent {
   dispatchIntent: () => void
 }
 
+/**
+ * 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.
+ * @public
+ */
+export declare interface DocumentHandle<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends DocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
+  documentId: string
+}
+
 declare interface DocumentInteractionHistory {
   recordEvent: (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => void
 }
@@ -193,7 +204,9 @@ export declare interface DocumentsOptions<
   TDataset extends string = string,
   TProjectId extends string = string,
 >
-  extends DatasetHandle<TDataset, TProjectId>, Pick<QueryOptions, 'perspective' | 'params'> {
+  extends
+    ResourceHandle<TProjectId, TDataset>,
+    Pick<QueryOptions<TDocumentType, TDataset, TProjectId>, 'params'> {
   /**
    * Filter documents by their `_type`. Can be a single type or an array of types.
    */
@@ -250,6 +263,28 @@ export declare interface DocumentsResponse<
   loadMore: () => void
 }
 
+/**
+ * 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.
+ * @public
+ */
+export declare interface DocumentTypeHandle<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends ResourceHandle<TProjectId, TDataset> {
+  documentType: TDocumentType
+  documentId?: string
+  liveEdit?: boolean
+}
+
+/** React-layer edit document options: DocumentHandle with optional path */
+declare type EditDocumentOptions<TPath extends string | undefined = undefined> = DocumentHandle & {
+  path?: TPath
+}
+
 /**
  * @internal
  */
@@ -298,11 +333,8 @@ export declare type MessageHandler<TWindowMessage extends WindowMessage> = (
   event: TWindowMessage['data'],
 ) => TWindowMessage['response'] | Promise<TWindowMessage['response']>
 
-/** In-flight CLI PR is using named sources since it's aspirational.
- *  We can transform the shape in this function until it's finalized.
- */
-declare interface NamedSources {
-  [key: string]: SanityConfig
+declare interface NamedResources {
+  [key: string]: DocumentResource
 }
 
 /**
@@ -329,7 +361,10 @@ export declare interface PaginatedDocumentsOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends Omit<QueryOptions<TDocumentType, TDataset, TProjectId>, 'query'> {
+>
+  extends
+    ResourceHandle<TProjectId, TDataset>,
+    Pick<QueryOptions<TDocumentType, TDataset, TProjectId>, 'params'> {
   documentType?: TDocumentType | TDocumentType[]
   /**
    * GROQ filter expression to apply to the query
@@ -445,10 +480,13 @@ export declare type ProjectWithoutMembers = Omit<SanityProject_2, 'members'>
  */
 export declare const REACT_SDK_VERSION: {}
 
+/** Options for useQuery: QueryOptions with resource made optional (resolved from context) */
+declare type ReactQueryOptions = Omit<QueryOptions, 'resource' | 'resourceName'> & ResourceHandle
+
 /** @internal */
 export declare function renderSanityApp(
   rootElement: HTMLElement | null,
-  namedSources: NamedSources,
+  namedResources: NamedResources,
   options: RenderSanitySDKAppOptions,
   children: React.ReactNode,
 ): () => void
@@ -458,64 +496,79 @@ declare interface RenderSanitySDKAppOptions {
 }
 
 /**
- * Provides a Sanity instance to child components through React Context
+ * 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.
+ * @public
+ */
+export declare interface ResourceHandle<
+  TProjectId extends string = string,
+  TDataset extends string = string,
+> {
+  resource?: DocumentResource<TProjectId, TDataset>
+  resourceName?: string
+  perspective?: PerspectiveHandle['perspective']
+}
+
+/**
+ * Provides Sanity configuration to child components through React Context.
  *
  * @internal
  *
  * @remarks
- * The ResourceProvider creates a hierarchical structure of Sanity instances:
- * - When used as a root provider, it creates a new Sanity instance with the given config
- * - When nested inside another ResourceProvider, it creates a child instance that
- *   inherits and extends the parent's configuration
- *
- * Features:
- * - Automatically manages the lifecycle of Sanity instances
- * - Disposes instances when the component unmounts
- * - Includes a Suspense boundary for data loading
- * - Enables hierarchical configuration inheritance
- *
- * Use this component to:
- * - Set up project/dataset configuration for an application
- * - Override specific configuration values in a section of your app
- * - Create isolated instance hierarchies for different features
+ * - **Root usage** (no parent instance): creates a `SanityInstance` with the
+ *   given config and provides it via `SanityInstanceContext`.
+ * - **Nested usage** (inside an existing provider): sets
+ *   `ResourceContext` and `PerspectiveContext` so hooks in the subtree
+ *   resolve the correct resource/perspective without creating a new instance.
  *
- * @example Creating a root provider
+ * @example Root provider
  * ```tsx
  * <ResourceProvider
- *   projectId="your-project-id"
- *   dataset="production"
+ *   resource={{ projectId: 'your-project-id', dataset: 'production' }}
  *   fallback={<LoadingSpinner />}
  * >
  *   <YourApp />
  * </ResourceProvider>
  * ```
  *
- * @example Creating nested providers with configuration inheritance
+ * @example Nested override
  * ```tsx
- * // Root provider with production config with nested provider for preview features with custom dataset
- * <ResourceProvider projectId="abc123" dataset="production" fallback={<Loading />}>
- *   <div>...Main app content</div>
- *   <Dashboard />
- *   <ResourceProvider dataset="preview" fallback={<Loading />}>
- *     <PreviewFeatures />
- *   </ResourceProvider>
+ * <ResourceProvider
+ *   resource={{ projectId: 'other-project', dataset: 'staging' }}
+ *   fallback={<LoadingSpinner />}
+ * >
+ *   <SubSection />
  * </ResourceProvider>
  * ```
  */
 export declare function ResourceProvider({
   children,
   fallback,
-  ...config
+  resource,
+  ...rest
 }: ResourceProviderProps): React.ReactNode
 
 /**
- * Props for the ResourceProvider component
+ * Props for the ResourceProvider component.
+ *
+ * Extends `SanityConfig` (minus `defaultResource`) so new config fields are
+ * automatically forwarded. The `resource` prop replaces `defaultResource`
+ * with a name that better describes its role at the React layer.
+ *
  * @internal
  */
-export declare interface ResourceProviderProps extends SanityConfig {
+export declare interface ResourceProviderProps extends Omit<SanityConfig, 'defaultResource'> {
   /**
-   * React node to show while content is loading
-   * Used as the fallback for the internal Suspense boundary
+   * The document resource (project/dataset, media library, or canvas)
+   * for this subtree. Hooks that don't specify an explicit resource will
+   * use this value.
+   */
+  resource?: DocumentResource
+  /**
+   * React node to show while content is loading.
+   * Used as the fallback for the internal Suspense boundary.
    */
   fallback: React.ReactNode
   children: React.ReactNode
@@ -528,57 +581,49 @@ export declare interface ResourceProviderProps extends SanityConfig {
  * as well as application context and state which is used by the Sanity React hooks. Your application
  * must be wrapped with the SanityApp component to function properly.
  *
- * The `config` prop on the SanityApp component accepts either a single {@link SanityConfig} object, or an array of them.
- * This allows your app to work with one or more of your organization's datasets.
+ * The `config` prop accepts a {@link SanityConfig} object. Use the `resources` prop to declare
+ * one or more named data resources for your app.
  *
- * When rendered inside a Sanity Studio that provides `SDKStudioContext`, the `config` prop is
- * optional — `SanityApp` will automatically derive `projectId`, `dataset`, and auth from the
- * Studio workspace.
+ * When rendered inside a Sanity Studio that provides `SDKStudioContext`, the `config` and `resources`
+ * props are optional — `SanityApp` will automatically derive them from the Studio workspace.
  *
- * @remarks
- * When passing multiple SanityConfig objects to the `config` prop, the first configuration in the array becomes the default
- * configuration used by the App SDK Hooks.
- *
- * When both `config` and `SDKStudioContext` are available, the explicit `config` takes precedence.
+ * When both `config` and `SDKStudioContext` are available, the explicit props take precedence.
  *
  * @category Components
  * @param props - Your Sanity configuration and the React children to render
  * @returns Your Sanity application, integrated with your Sanity configuration and application context
  *
- * @example
+ * @example Single project
  * ```tsx
- * import { SanityApp, type SanityConfig } from '@sanity/sdk-react'
- *
- * import MyAppRoot from './Root'
+ * import { SanityApp } from '@sanity/sdk-react'
  *
- * // Single project configuration
- * const mySanityConfig: SanityConfig = {
- *   projectId: 'my-project-id',
- *   dataset: 'production',
+ * export default function MyApp() {
+ *   return (
+ *     <SanityApp
+ *       resources={{
+ *         default: { projectId: 'my-project-id', dataset: 'production' },
+ *       }}
+ *       fallback={<div>Loading…</div>}
+ *     >
+ *       <MyAppRoot />
+ *     </SanityApp>
+ *   )
  * }
+ * ```
  *
- * // Or multiple project configurations
- * const multipleConfigs: SanityConfig[] = [
- *   // Configuration for your main project. This will be used as the default project for hooks.
- *   {
- *     projectId: 'marketing-website-project',
- *     dataset: 'production',
- *   },
- *   // Configuration for a separate blog project
- *   {
- *     projectId: 'blog-project',
- *     dataset: 'production',
- *   },
- *   // Configuration for a separate ecommerce project
- *   {
- *     projectId: 'ecommerce-project',
- *     dataset: 'production',
- *   }
- * ]
+ * @example Multiple resources
+ * ```tsx
+ * import { SanityApp } from '@sanity/sdk-react'
  *
  * export default function MyApp() {
  *   return (
- *     <SanityApp config={mySanityConfig} fallback={<div>Loading…</div>}>
+ *     <SanityApp
+ *       resources={{
+ *         default: { projectId: 'abc123', dataset: 'production' },
+ *         'blog-project': { projectId: 'def456', dataset: 'production' },
+ *       }}
+ *       fallback={<div>Loading…</div>}
+ *     >
  *       <MyAppRoot />
  *     </SanityApp>
  *   )
@@ -589,6 +634,7 @@ export declare function SanityApp({
   children,
   fallback,
   config: configProp,
+  resources: resourcesProp,
   ...props
 }: SanityAppProps): ReactElement
 
@@ -598,15 +644,17 @@ export declare function SanityApp({
  */
 export declare interface SanityAppProps {
   /**
-   * One or more SanityConfig objects providing a project ID and dataset name.
-   * Optional when `SanityApp` is rendered inside an `SDKStudioContext` provider
-   * (e.g. inside Sanity Studio) — the config is derived from the workspace
-   * automatically.
+   * Core configuration for the SDK instance (auth, studio, perspective).
+   * Optional when `SanityApp` is rendered inside an `SDKStudioContext`
+   * provider (e.g. inside Sanity Studio) — the config is derived from
+   * the workspace automatically.
    */
-  config?: SanityConfig | SanityConfig[]
-  /** @deprecated use the `config` prop instead. */
-  sanityConfigs?: SanityConfig[]
-  sources?: Record<string, DocumentSource>
+  config?: SanityConfig
+  /**
+   * Named document resources for the application. The resource keyed `"default"`
+   * is used automatically when no explicit resource is specified in hooks.
+   */
+  resources?: Record<string, DocumentResource>
   children: React.ReactNode
   fallback: React.ReactNode
 }
@@ -619,12 +667,15 @@ export {SanityProjectMember}
  * @internal
  *
  * Top-level context provider that provides access to the Sanity SDK.
- * Creates a hierarchy of ResourceProviders, each providing a SanityInstance that can be
- * accessed by hooks. The first configuration in the array becomes the default instance.
+ *
+ * Creates a single `ResourceProvider` (and therefore a single `SanityInstance`)
+ * for the given config. Resource resolution is handled by `ResourcesContext`
+ * and the `"default"` named resource.
  */
 export declare function SDKProvider({
   children,
   config,
+  resources,
   fallback,
   ...props
 }: SDKProviderProps): ReactElement
@@ -634,9 +685,13 @@ export declare function SDKProvider({
  */
 export declare interface SDKProviderProps extends AuthBoundaryProps {
   children: ReactNode
-  config: SanityConfig | SanityConfig[]
+  config: SanityConfig
+  /**
+   * Named document resources map. Provided to `ResourcesContext` for
+   * name-based resource resolution in hooks.
+   */
+  resources?: Record<string, DocumentResource>
   fallback: ReactNode
-  sources?: Record<string, DocumentSource>
 }
 
 /**
@@ -677,6 +732,12 @@ export declare const SDKStudioContext: Context<StudioWorkspaceHandle | null>
 
 export {SortOrderingItem}
 
+export {StrictDocumentHandle}
+
+export {StrictDocumentTypeHandle}
+
+export {StrictResourceHandle}
+
 /**
  * Minimal duck-typed interface representing a Sanity Studio workspace.
  * The Studio's `Workspace` type satisfies this naturally — no import
@@ -689,6 +750,12 @@ export declare interface StudioWorkspaceHandle {
   projectId: string
   /** The dataset name for this workspace. */
   dataset: string
+  /**
+   * Whether the Studio has determined the user is authenticated.
+   * When `true` and the token source emits `null`, the SDK infers
+   * cookie-based auth is in use and skips the logged-out state.
+   */
+  authenticated?: boolean
   /** Authentication state for this workspace. */
   auth: {
     /**
@@ -723,13 +790,6 @@ declare interface Subscription {
 
 declare type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
 
-/**
- * @public
- */
-declare type UseActiveReleases = {
-  (): ReleaseDocument[]
-}
-
 /**
  * @public
 
@@ -745,6 +805,14 @@ declare type UseActiveReleases = {
  * const activeReleases = useActiveReleases()
  * ```
  */
+declare type UseActiveReleases = {
+  (options?: ResourceHandle | undefined): ReleaseDocument[]
+}
+
+/**
+ * @public
+ * @function
+ */
 export declare const useActiveReleases: UseActiveReleases
 
 /**
@@ -814,8 +882,8 @@ export declare const useActiveReleases: UseActiveReleases
  *
  * @category Agent Actions
  */
-export declare const useAgentGenerate: () => (
-  options: AgentGenerateOptions,
+export declare function useAgentGenerate(): (
+  options: AgentGenerateOptions & WithResourceNameSupport<AgentResourceOptions>,
 ) => Subscribable<unknown>
 
 /**
@@ -967,7 +1035,9 @@ export declare const useAgentGenerate: () => (
  *
  * @category Agent Actions
  */
-export declare const useAgentPatch: () => (options: AgentPatchOptions) => Promise<AgentPatchResult>
+export declare function useAgentPatch(): (
+  options: AgentPatchOptions & WithResourceNameSupport<AgentResourceOptions>,
+) => Promise<AgentPatchResult>
 
 /**
  * @alpha
@@ -1063,8 +1133,8 @@ export declare const useAgentPatch: () => (options: AgentPatchOptions) => Promis
  *
  * @category Agent Actions
  */
-export declare const useAgentPrompt: () => (
-  options: AgentPromptOptions,
+export declare function useAgentPrompt(): (
+  options: AgentPromptOptions & WithResourceNameSupport<AgentResourceOptions>,
 ) => Promise<AgentPromptResult>
 
 /**
@@ -1170,8 +1240,8 @@ export declare function useAgentResourceContext(options: AgentResourceContextOpt
  *
  * @category Agent Actions
  */
-export declare const useAgentTransform: () => (
-  options: AgentTransformOptions,
+export declare function useAgentTransform(): (
+  options: AgentTransformOptions & WithResourceNameSupport<AgentResourceOptions>,
 ) => Subscribable<unknown>
 
 /**
@@ -1264,8 +1334,8 @@ export declare const useAgentTransform: () => (
  *
  * @category Agent Actions
  */
-export declare const useAgentTranslate: () => (
-  options: AgentTranslateOptions,
+export declare function useAgentTranslate(): (
+  options: AgentTranslateOptions & WithResourceNameSupport<AgentResourceOptions>,
 ) => Subscribable<unknown>
 
 /**
@@ -1280,8 +1350,8 @@ declare interface UseApplyDocumentActions {
     action:
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
-    options?: ApplyDocumentActionsOptions,
-  ) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
+    options?: ResourceHandle,
+  ) => Promise<ActionsResult>
 }
 
 /**
@@ -1573,11 +1643,12 @@ declare type UseDatasets = {
    * Returns metadata for each dataset the current user has access to.
    *
    * @category Datasets
-   * @returns The metadata for your the datasets
+   * @param options - An object containing the `projectId` to list datasets for.
+   * @returns The metadata for the datasets
    *
    * @example
    * ```tsx
-   * const datasets = useDatasets()
+   * const datasets = useDatasets({projectId: 'my-project-id'})
    *
    * return (
    *   <select>
@@ -1589,7 +1660,7 @@ declare type UseDatasets = {
    * ```
    *
    */
-  (): DatasetsResponse
+  (options: {projectId: string}): DatasetsResponse
 }
 
 /**
@@ -1608,8 +1679,8 @@ export declare const useDatasets: UseDatasets
  *   - `action` - Action to perform (currently only 'edit' is supported). Will prompt a picker if multiple handlers are available.
  *   - `intentId` - Specific ID of the intent to dispatch. Either `action` or `intentId` is required.
  *   - `documentHandle` - The document handle containing document ID, type, and either:
- *     - `projectId` and `dataset` for traditional dataset sources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
- *     - `source` for media library, canvas, or dataset sources, like `{documentId: '123', documentType: 'sanity.asset', source: mediaLibrarySource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', source: canvasSource('canvas123')}`
+ *     - `projectId` and `dataset` for traditional dataset resources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
+ *     - `resource` for media library, canvas, or dataset resources, like `{documentId: '123', documentType: 'sanity.asset', resource: mediaLibraryResource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', resource: canvasResource('canvas123')}`
  *   - `paremeters` - Optional parameters to include in the dispatch; will be passed to the resolved intent handler
  * @returns An object containing:
  * - `dispatchIntent` - Function to dispatch the intent message
@@ -1658,187 +1729,121 @@ export declare function useDispatchIntent(params: UseDispatchIntentParams): Disp
 declare interface UseDispatchIntentParams {
   action?: 'edit'
   intentId?: string
-  documentHandle: WithSourceNameSupport<DocumentHandle>
+  documentHandle: DocumentHandle
   parameters?: Record<string, unknown>
 }
 
 declare interface UseDocument {
-  /** @internal */
-  <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
-    options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
-  ): {
-    data: SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`> | null
-  }
-  /** @internal */
-  <
-    TPath extends string,
-    TDocumentType extends string,
-    TDataset extends string = string,
-    TProjectId extends string = string,
-  >(
-    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
-  ): {
-    data: JsonMatch<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>, TPath> | undefined
-  }
-  /** @internal */
-  <TData>(options: DocumentOptions<undefined>): {
-    data: TData | null
-  }
-  /** @internal */
-  <TData>(options: DocumentOptions<string>): {
-    data: TData | undefined
-  }
   /**
-   * ## useDocument via Type Inference (Recommended)
-   *
    * @public
    *
-   * The preferred way to use this hook when working with Sanity Typegen.
+   * ## useDocument with Explicit Types (no path)
    *
-   * Features:
-   * - Automatically infers document types from your schema
-   * - Provides type-safe access to documents and nested fields
-   * - Supports project/dataset-specific type inference
-   * - Works seamlessly with Typegen-generated types
+   * Provide an explicit type parameter `TData` to type the returned document data.
+   * You can define your own interfaces or use types generated by your Sanity Studio.
    *
-   * This hook will suspend while the document data is being fetched and loaded.
-   *
-   * When fetching a full document:
-   * - Returns the complete document object if it exists
-   * - Returns `null` if the document doesn't exist
-   *
-   * When fetching with a path:
-   * - Returns the value at the specified path if both the document and path exist
-   * - Returns `undefined` if either the document doesn't exist or the path doesn't exist in the document
+   * This hook will suspend while the document data is being fetched.
    *
-   * @category Documents
+   * @typeParam TData - The explicit type for the document
    * @param options - Configuration including `documentId`, `documentType`, and optionally:
-   *   - `path`: To select a nested value (returns typed value at path)
    *   - `projectId`/`dataset`: For multi-project/dataset setups
-   * @returns The document state (or nested value if path provided).
+   * @returns The document state
    *
-   * @example Basic document fetch
+   * @example Basic document fetch with explicit type
    * ```tsx
-   * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
+   * import {useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'
+   *
+   * interface Book extends SanityDocument {
+   *   _type: 'book'
+   *   title: string
+   *   author: string
+   * }
    *
-   * interface ProductViewProps {
-   *   doc: DocumentHandle<'product'> // Typegen infers product type
+   * interface BookViewProps {
+   *   doc: DocumentHandle
    * }
    *
-   * function ProductView({doc}: ProductViewProps) {
-   *   const {data: product} = useDocument({...doc}) // Fully typed product
-   *   return <h1>{product.title ?? 'Untitled'}</h1>
+   * function BookView({doc}: BookViewProps) {
+   *   const {data: book} = useDocument<Book>({...doc})
+   *   return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
    * }
    * ```
    *
-   * @example Fetching a specific field
+   * @inlineType DocumentOptions
+   */
+  <TData>(options: UseDocumentOptions<undefined>): {
+    data: TData | null
+  }
+  /**
+   * @public
+   *
+   * ## useDocument with Explicit Types (with path)
+   *
+   * Provide an explicit type parameter `TData` to type the returned field data
+   * when using a `path` to select a nested value.
+   *
+   * @typeParam TData - The explicit type for the field
+   * @param options - Configuration including `documentId`, `documentType`, `path`, and optionally:
+   *   - `projectId`/`dataset`: For multi-project/dataset setups
+   * @returns The field value at the specified path
+   *
+   * @example Fetching a specific field with explicit type
    * ```tsx
    * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
    *
-   * interface ProductTitleProps {
-   *   doc: DocumentHandle<'product'>
-   * }
-   *
-   * function ProductTitle({doc}: ProductTitleProps) {
-   *   const {data: title} = useDocument({
-   *     ...doc,
-   *     path: 'title' // Returns just the title field
-   *   })
+   * function BookTitle({doc}: {doc: DocumentHandle}) {
+   *   const {data: title} = useDocument<string>({...doc, path: 'title'})
    *   return <h1>{title ?? 'Untitled'}</h1>
    * }
    * ```
    *
    * @inlineType DocumentOptions
    */
-  <
-    TPath extends string | undefined = undefined,
-    TDocumentType extends string = string,
-    TDataset extends string = string,
-    TProjectId extends string = string,
-  >(
-    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
-  ): TPath extends string
-    ? {
-        data:
-          | JsonMatch<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>
-          | undefined
-      }
-    : {
-        data: SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`> | null
-      }
+  <TData>(options: UseDocumentOptions<string>): {
+    data: TData | undefined
+  }
   /**
    * @public
    *
-   * ## useDocument via Explicit Types
+   * ## useDocument (default)
    *
-   * Use this version when:
-   * - You're not using Sanity Typegen
-   * - You need to manually specify document types
-   * - You're working with dynamic document types
+   * When no explicit type parameter is provided, the hook returns `SanityDocument`.
    *
-   * Key differences from Typegen version:
-   * - Requires manual type specification via `TData`
-   * - Returns `TData | null` for full documents
-   * - Returns `TData | undefined` for nested values
+   * This hook will suspend while the document data is being fetched and loaded.
    *
-   * This hook will suspend while the document data is being fetched.
+   * When fetching a full document:
+   * - Returns the complete document object if it exists
+   * - Returns `null` if the document doesn't exist
    *
-   * @typeParam TData - The explicit type for the document or field
-   * @typeParam TPath - Optional path to a nested value
-   * @param options - Configuration including `documentId` and optionally:
+   * When fetching with a path:
+   * - Returns the value at the specified path if both the document and path exist
+   * - Returns `undefined` if either the document doesn't exist or the path doesn't exist in the document
+   *
+   * @category Documents
+   * @param options - Configuration including `documentId`, `documentType`, and optionally:
    *   - `path`: To select a nested value
    *   - `projectId`/`dataset`: For multi-project/dataset setups
-   * @returns The document state (or nested value if path provided)
-   *
-   * @example Basic document fetch with explicit type
-   * ```tsx
-   * import {useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'
-   *
-   * interface Book extends SanityDocument {
-   *   _type: 'book'
-   *   title: string
-   *   author: string
-   * }
-   *
-   * interface BookViewProps {
-   *   doc: DocumentHandle
-   * }
-   *
-   * function BookView({doc}: BookViewProps) {
-   *   const {data: book} = useDocument<Book>({...doc})
-   *   return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
-   * }
-   * ```
+   * @returns The document state (or nested value if path provided).
    *
-   * @example Fetching a specific field with explicit type
+   * @example Basic document fetch
    * ```tsx
    * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
    *
-   * interface BookTitleProps {
-   *   doc: DocumentHandle
-   * }
-   *
-   * function BookTitle({doc}: BookTitleProps) {
-   *   const {data: title} = useDocument<string>({...doc, path: 'title'})
-   *   return <h1>{title ?? 'Untitled'}</h1>
+   * function ProductView({doc}: {doc: DocumentHandle}) {
+   *   const {data: product} = useDocument({...doc})
+   *   return <h1>{product?.title ?? 'Untitled'}</h1>
    * }
    * ```
    *
    * @inlineType DocumentOptions
    */
-  <TData, TPath extends string>(
-    options: DocumentOptions<TPath>,
-  ): TPath extends string
-    ? {
-        data: TData | undefined
-      }
-    : {
-        data: TData | null
-      }
+  (options: UseDocumentOptions<undefined>): {
+    data: SanityDocument | null
+  }
   /**
    * @internal
    */
-  (options: DocumentOptions): {
+  (options: UseDocumentOptions): {
     data: unknown
   }
 }
@@ -1847,10 +1852,11 @@ declare interface UseDocument {
  * @public
  * Reads and subscribes to a document's realtime state, incorporating both local and remote changes.
  *
- * This hook comes in two main flavors to suit your needs:
+ * You can provide an explicit type parameter for full type safety:
+ * - `useDocument<MyType>({...})` returns `{data: MyType | null}`
+ * - `useDocument<string>({..., path: 'title'})` returns `{data: string | undefined}`
  *
- * 1. **[Type Inference](#usedocument-via-type-inference-recommended)** (Recommended) - Automatically gets types from your Sanity schema
- * 2. **[Explicit Types](#usedocument-via-explicit-types)** - Manually specify types when needed
+ * Without a type parameter, data is typed as `SanityDocument`.
  *
  * @remarks
  * `useDocument` is ideal for realtime editing interfaces where you need immediate feedback on changes.
@@ -1875,19 +1881,19 @@ export declare const useDocument: UseDocument
  * Subscribes an event handler to events in your application's document store.
  *
  * @category Documents
- * @param options - An object containing the event handler (`onEvent`) and optionally a `DatasetHandle` (projectId and dataset). If the handle is not provided, the nearest Sanity instance from context will be used.
+ * @param options - An object containing the event handler (`onEvent`) and optionally a `resource`. If no resource is provided, the nearest resource from context will be used.
  * @example Creating a custom hook for document event toasts
  * ```tsx
- * import {createDatasetHandle, type DatasetHandle, type DocumentEvent, useDocumentEvent} from '@sanity/sdk-react'
+ * import {type DocumentResource, type DocumentEvent, useDocumentEvent} from '@sanity/sdk-react'
  * import {useToast} from './my-ui-library'
  *
- * // Define options for the custom hook, extending DatasetHandle
- * interface DocumentToastsOptions extends DatasetHandle {
- *   // Could add more options, e.g., { includeEvents: DocumentEvent['type'][] }
+ * // Define options for the custom hook
+ * interface DocumentToastsOptions {
+ *   resource?: DocumentResource
  * }
  *
  * // Define the custom hook
- * function useDocumentToasts({...datasetHandle}: DocumentToastsOptions = {}) {
+ * function useDocumentToasts({resource}: DocumentToastsOptions = {}) {
  *   const showToast = useToast() // Get the toast function
  *
  *   // Define the event handler logic to show toasts on specific events
@@ -1899,24 +1905,20 @@ export declare const useDocument: UseDocument
  *     } else if (event.type === 'deleted') {
  *       showToast(`Document ${event.documentId} deleted.`)
  *     } else {
- *       // Optionally log other events for debugging
  *       console.log('Document Event:', event.type, event.documentId)
  *     }
  *   }
  *
- *   // Call the original hook, spreading the handle properties
  *   useDocumentEvent({
- *     ...datasetHandle, // Spread the dataset handle (projectId, dataset)
+ *     resource,
  *     onEvent: handleEvent,
  *   })
  * }
  *
  * function MyComponentWithToasts() {
- *   // Use the custom hook, passing specific handle info
- *   const specificHandle = createDatasetHandle({ projectId: 'p1', dataset: 'ds1' })
- *   useDocumentToasts(specificHandle)
+ *   useDocumentToasts({resource: {projectId: 'p1', dataset: 'ds1'}})
  *
- *   // // Or use it relying on context for the handle
+ *   // Or rely on context for the resource:
  *   // useDocumentToasts()
  *
  *   return <div>...</div>
@@ -1934,10 +1936,19 @@ export declare function useDocumentEvent<
 declare interface UseDocumentEventOptions<
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DatasetHandle<TDataset, TProjectId> {
+> extends ResourceHandle<TProjectId, TDataset> {
   onEvent: (documentEvent: DocumentEvent) => void
 }
 
+declare type UseDocumentOptions<
+  TPath extends string | undefined = undefined,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> = DocumentHandle<TDocumentType, TDataset, TProjectId> & {
+  path?: TPath
+}
+
 /**
  *
  * @public
@@ -2023,7 +2034,7 @@ export declare function useDocumentPermissions(
  * @public
  *
  * Attempts to infer preview values of a document (specified via a `DocumentHandle`),
- * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
+ * including the document's `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
  * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview
  * resolution will only occur if the `ref` is intersecting the current viewport.
  *
@@ -2032,18 +2043,22 @@ export declare function useDocumentPermissions(
  * @remarks
  * Values returned by this hook may not be as expected. It is currently unable to read preview values as defined in your schema;
  * instead, it attempts to infer these preview values by checking against a basic set of potential fields on your document.
- * We are anticipating being able to significantly improve this hook’s functionality and output in a future release.
+ * We are anticipating being able to significantly improve this hook's functionality and output in a future release.
  * For now, we recommend using {@link useDocumentProjection} for rendering individual document fields (or projections of those fields).
  *
+ * Internally, this hook is implemented as a specialized projection with post-processing logic.
+ * It uses a fixed GROQ projection to fetch common preview fields (title, subtitle, media) and
+ * transforms the results into the PreviewValue format.
+ *
  * @category Documents
  * @param options - The document handle for the document you want to infer preview values for, and an optional ref
  * @returns The inferred values for the given document and a boolean to indicate whether the resolution is pending
  *
  * @example Combining with useDocuments to render a collection of document previews
  * ```
- * // PreviewComponent.jsx
- * export default function PreviewComponent({ document }) {
- *   const { data: { title, subtitle, media }, isPending } = useDocumentPreview({ document })
+ * // PreviewComponent.tsx
+ * export default function PreviewComponent(docHandle: DocumentHandle) {
+ *   const { data: { title, subtitle, media }, isPending } = useDocumentPreview(docHandle)
  *   return (
  *     <article style={{ opacity: isPending ? 0.5 : 1}}>
  *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
@@ -2053,16 +2068,16 @@ export declare function useDocumentPermissions(
  *   )
  * }
  *
- * // DocumentList.jsx
- * const { data } = useDocuments({ filter: '_type == "movie"' })
+ * // DocumentList.tsx
+ * const { data } = useDocuments({ documentType: 'movie' })
  * return (
  *   <div>
  *     <h1>Movies</h1>
  *     <ul>
  *       {data.map(movie => (
- *         <li key={movie._id}>
+ *         <li key={movie.documentId}>
  *           <Suspense fallback='Loading…'>
- *             <PreviewComponent document={movie} />
+ *             <PreviewComponent {...movie} />
  *           </Suspense>
  *         </li>
  *       ))}
@@ -2093,7 +2108,7 @@ export declare interface useDocumentPreviewOptions extends DocumentHandle {
  * @category Types
  */
 export declare interface useDocumentPreviewResults {
-  /** The results of inferring the document’s preview values */
+  /** The results of inferring the document's preview values */
   data: PreviewValue
   /** True when inferred preview values are being refreshed */
   isPending: boolean
@@ -2109,80 +2124,11 @@ export declare interface useDocumentPreviewResults {
  *
  * @category Documents
  * @remarks
- * This hook has multiple signatures allowing for fine-grained control over type inference:
- * - Using Typegen: Infers the return type based on the `documentType`, `dataset`, `projectId`, and `projection`.
- * - Using explicit type parameter: Allows specifying a custom return type `TData`.
+ * This hook allows specifying an explicit type parameter `TData` for the projected result.
  *
  * @param options - An object containing the `DocumentHandle` properties (`documentId`, `documentType`, etc.), the `projection` string, optional `params`, and an optional `ref`.
  * @returns An object containing the projection results (`data`) and a boolean indicating whether the resolution is pending (`isPending`). Note: Suspense handles initial loading states; `data` being `undefined` after initial loading means the document doesn't exist or the projection yielded no result.
  */
-/**
- * @public
- * Fetch a projection, relying on Typegen for the return type based on the handle and projection.
- *
- * @category Documents
- * @param options - Options including the document handle properties (`documentId`, `documentType`, etc.) and the `projection`.
- * @returns The projected data, typed based on Typegen.
- *
- * @example Using Typegen for a book preview
- * ```tsx
- * // ProjectionComponent.tsx
- * import {useDocumentProjection, type DocumentHandle} from '@sanity/sdk-react'
- * import {useRef} from 'react'
- * import {defineProjection} from 'groq'
- *
- * // Define props using DocumentHandle with the specific document type
- * type ProjectionComponentProps = {
- *   doc: DocumentHandle<'book'> // Typegen knows 'book'
- * }
- *
- * // This is required for typegen to generate the correct return type
- * const myProjection = defineProjection(`{
- *   title,
- *   'coverImage': cover.asset->url,
- *   'authors': array::join(authors[]->{'name': firstName + ' ' + lastName}.name, ', ')
- * }`)
- *
- * export default function ProjectionComponent({ doc }: ProjectionComponentProps) {
- *   const ref = useRef(null) // Optional ref to track viewport intersection for lazy loading
- *
- *   // Spread the doc handle into the options
- *   // Typegen infers the return type based on 'book' and the projection
- *   const { data } = useDocumentProjection({
- *     ...doc, // Pass the handle properties
- *     ref,
- *     projection: myProjection,
- *   })
- *
- *   // Suspense handles initial load, check for data existence after
- *   return (
- *     <article ref={ref}>
- *       <h2>{data.title ?? 'Untitled'}</h2>
- *       {data.coverImage && <img src={data.coverImage} alt={data.title} />}
- *       <p>{data.authors ?? 'Unknown authors'}</p>
- *     </article>
- *   )
- * }
- *
- * // Usage:
- * // import {createDocumentHandle} from '@sanity/sdk-react'
- * // const myDocHandle = createDocumentHandle({ documentId: 'book123', documentType: 'book' })
- * // <Suspense fallback='Loading preview...'>
- * //   <ProjectionComponent doc={myDocHandle} />
- * // </Suspense>
- * ```
- */
-export declare function useDocumentProjection<
-  TProjection extends string = string,
-  TDocumentType extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
->(
-  options: useDocumentProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
-): useDocumentProjectionResults<
-  SanityProjectionResult<TProjection, TDocumentType, `${TProjectId}.${TDataset}`>
->
-
 /**
  * @public
  * Fetch a projection with an explicitly defined return type `TData`.
@@ -2241,7 +2187,7 @@ export declare interface useDocumentProjectionOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends WithSourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
+> extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
   /** The GROQ projection string */
   projection: TProjection
   /** Optional parameters for the projection query */
@@ -2272,18 +2218,16 @@ export declare interface useDocumentProjectionResults<TData> {
  * @returns An object containing the list of document handles, the loading state, the total count of retrieved document handles, and a function to load more
  *
  * @remarks
- * - The returned document handles include projectId and dataset information from the current Sanity instance
+ * - The returned document handles include resource information from the current Sanity instance
  * - This makes them ready to use with document operations and other document hooks
- * - The hook automatically uses the correct Sanity instance based on the projectId and dataset in the options
+ * - The hook automatically uses the correct Sanity instance based on the resource in the options
  *
  * @example Basic infinite list with loading more
  * ```tsx
  * import {
  *   useDocuments,
- *   createDatasetHandle,
- *   type DatasetHandle,
  *   type DocumentHandle,
- *   type SortOrderingItem
+ *   type DocumentResource,
  * } from '@sanity/sdk-react'
  * import {Suspense} from 'react'
  *
@@ -2299,14 +2243,14 @@ export declare interface useDocumentProjectionResults<TData> {
  *
  * // Define props for the list component
  * interface DocumentListProps {
- *   dataset: DatasetHandle
+ *   resource: DocumentResource
  *   documentType: string
  *   search?: string
  * }
  *
- * function DocumentList({dataset, documentType, search}: DocumentListProps) {
+ * function DocumentList({resource, documentType, search}: DocumentListProps) {
  *   const { data, hasMore, isPending, loadMore, count } = useDocuments({
- *     ...dataset,
+ *     resource,
  *     documentType,
  *     search,
  *     batchSize: 10,
@@ -2320,7 +2264,7 @@ export declare interface useDocumentProjectionResults<TData> {
  *         {data.map((docHandle) => (
  *           <li key={docHandle.documentId}>
  *            <Suspense fallback="Loading…">
- *              <MyDocumentComponent docHandle={docHandle} />
+ *              <MyDocumentComponent doc={docHandle} />
  *            </Suspense>
  *           </li>
  *         ))}
@@ -2335,8 +2279,7 @@ export declare interface useDocumentProjectionResults<TData> {
  * }
  *
  * // Usage:
- * // const myDatasetHandle = createDatasetHandle({ projectId: 'p1', dataset: 'production' })
- * // <DocumentList dataset={myDatasetHandle} documentType="post" search="Sanity" />
+ * // <DocumentList resource={{projectId: 'p1', dataset: 'production'}} documentType="post" search="Sanity" />
  * ```
  *
  * @example Using `filter` and `params` options for narrowing a collection
@@ -2381,7 +2324,7 @@ export declare function useDocuments<
   filter,
   orderings,
   documentType,
-  ...options
+  ...rawOptions
 }: DocumentsOptions<TDocumentType, TDataset, TProjectId>): DocumentsResponse<
   TDocumentType,
   TDataset,
@@ -2393,9 +2336,9 @@ declare type UseDocumentSyncStatus = {
    * Exposes the document's sync status between local and remote document states.
    *
    * @category Documents
-   * @param doc - The document handle to get sync status for. If you pass a `DocumentHandle` with specified `projectId` and `dataset`,
-   * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `projectId` or `dataset` is provided,
-   * the document will use the nearest instance from context.
+   * @param doc - The document handle to get sync status for. If you pass a `resource` in the handle,
+   * the document will be read from the specified resource. If no `resource` is provided,
+   * the resource will be resolved from context.
    * @returns `true` if local changes are synced with remote, `false` if changes are pending. Note: Suspense handles loading states.
    * @example Show sync status indicator
    * ```tsx
@@ -2430,67 +2373,28 @@ declare type UseDocumentSyncStatus = {
  */
 export declare const useDocumentSyncStatus: UseDocumentSyncStatus
 
-/**
- * @public
- * Edit an entire document, relying on Typegen for the type.
- *
- * @param options - Document options including `documentId`, `documentType`, and optionally `projectId`/`dataset`.
- * @returns A stable function to update the document state. Accepts either the new document state or an updater function `(currentValue) => nextValue`.
- *          Returns a promise resolving to the {@link ActionsResult}.
- */
-export declare function useEditDocument<
-  TDocumentType extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
->(
-  options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
-): (
-  nextValue: Updater<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>,
-) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
-
-/**
- * @public
- * Edit a specific path within a document, relying on Typegen for the type.
- *
- * @param options - Document options including `documentId`, `documentType`, `path`, and optionally `projectId`/`dataset`.
- * @returns A stable function to update the value at the specified path. Accepts either the new value or an updater function `(currentValue) => nextValue`.
- *          Returns a promise resolving to the {@link ActionsResult}.
- */
-export declare function useEditDocument<
-  TPath extends string = string,
-  TDocumentType extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
->(
-  options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
-): (
-  nextValue: Updater<
-    JsonMatch<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>
-  >,
-) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
-
 /**
  * @public
  * Edit an entire document with an explicit type `TData`.
  *
- * @param options - Document options including `documentId` and optionally `projectId`/`dataset`.
+ * @param options - Document options including `documentId` and optionally `resource` or `resourceName`.
  * @returns A stable function to update the document state. Accepts either the new document state (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
  *          Returns a promise resolving to the {@link ActionsResult}.
  */
 export declare function useEditDocument<TData>(
-  options: DocumentOptions<undefined>,
+  options: EditDocumentOptions<undefined>,
 ): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
 /**
  * @public
  * Edit a specific path within a document with an explicit type `TData`.
  *
- * @param options - Document options including `documentId`, `path`, and optionally `projectId`/`dataset`.
+ * @param options - Document options including `documentId`, `path`, and optionally `resource` or `resourceName`.
  * @returns A stable function to update the value at the specified path. Accepts either the new value (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
  *          Returns a promise resolving to the {@link ActionsResult}.
  */
 export declare function useEditDocument<TData>(
-  options: DocumentOptions<string>,
+  options: EditDocumentOptions<string>,
 ): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
 /**
@@ -2626,8 +2530,7 @@ export declare const useLogOut: () => () => Promise<void>
 export declare function useManageFavorite({
   documentId,
   documentType,
-  projectId: paramProjectId,
-  dataset: paramDataset,
+  resource: paramResource,
   resourceId: paramResourceId,
   resourceType,
   schemaName,
@@ -2703,18 +2606,16 @@ export declare function useNavigateToStudioDocument(
  * @returns An object containing the list of document handles, pagination details, and functions to navigate between pages
  *
  * @remarks
- * - The returned document handles include projectId and dataset information from the current Sanity instance
+ * - The returned document handles include resource information from the current Sanity instance
  * - This makes them ready to use with document operations and other document hooks
- * - The hook automatically uses the correct Sanity instance based on the projectId and dataset in the options
+ * - The hook automatically uses the correct Sanity instance based on the resource in the options
  *
  * @example Paginated list of documents with navigation
  * ```tsx
  * import {
  *   usePaginatedDocuments,
- *   createDatasetHandle,
- *   type DatasetHandle,
  *   type DocumentHandle,
- *   type SortOrderingItem,
+ *   type DocumentResource,
  *   useDocumentProjection
  * } from '@sanity/sdk-react'
  * import {Suspense} from 'react'
@@ -2737,10 +2638,10 @@ export declare function useNavigateToStudioDocument(
  * // Define props for the list component
  * interface PaginatedDocumentListProps {
  *   documentType: string
- *   dataset?: DatasetHandle
+ *   resource?: DocumentResource
  * }
  *
- * function PaginatedDocumentList({documentType, dataset}: PaginatedDocumentListProps) {
+ * function PaginatedDocumentList({documentType, resource}: PaginatedDocumentListProps) {
  *   const {
  *     data,
  *     isPending,
@@ -2751,7 +2652,7 @@ export declare function useNavigateToStudioDocument(
  *     hasNextPage,
  *     hasPreviousPage
  *   } = usePaginatedDocuments({
- *     ...dataset,
+ *     resource,
  *     documentType,
  *     pageSize: 10,
  *     orderings: [{field: '_createdAt', direction: 'desc'}],
@@ -2783,8 +2684,7 @@ export declare function useNavigateToStudioDocument(
  * }
  *
  * // Usage:
- * // const myDatasetHandle = createDatasetHandle({ projectId: 'p1', dataset: 'production' })
- * // <PaginatedDocumentList dataset={myDatasetHandle} documentType="post" />
+ * // <PaginatedDocumentList resource={{projectId: 'p1', dataset: 'production'}} documentType="post" />
  * ```
  */
 export declare function usePaginatedDocuments<
@@ -2798,20 +2698,13 @@ export declare function usePaginatedDocuments<
   params,
   orderings,
   search,
-  ...options
+  ...rawOptions
 }: PaginatedDocumentsOptions<TDocumentType, TDataset, TProjectId>): PaginatedDocumentsResponse<
   TDocumentType,
   TDataset,
   TProjectId
 >
 
-/**
- * @public
- */
-declare type UsePerspective = {
-  (perspectiveHandle: PerspectiveHandle): string | string[]
-}
-
 /**
  * @public
  * @function
@@ -2825,22 +2718,34 @@ declare type UsePerspective = {
  * @example
  * ```tsx
  * import {usePerspective, useQuery} from '@sanity/sdk-react'
-
- * const perspective = usePerspective({perspective: 'rxg1346', projectId: 'abc123', dataset: 'production'})
- * const {data} = useQuery<Movie[]>('*[_type == "movie"]', {
- *   perspective: perspective,
+ *
+ * const perspective = usePerspective({
+ *   perspective: 'rxg1346',
+ *   resource: {projectId: 'abc123', dataset: 'production'},
+ * })
+ * const {data} = useQuery<Movie[]>({
+ *   query: '*[_type == "movie"]',
+ *   perspective,
  * })
  * ```
  *
  * @returns The perspective for the given perspective handle.
  */
+declare type UsePerspective = {
+  (perspectiveHandle?: ResourceHandle): string | string[]
+}
+
+/**
+ * @public
+ * @function
+ */
 export declare const usePerspective: UsePerspective
 
 /**
  * A hook for subscribing to presence information for the current project.
  * @public
  */
-export declare function usePresence(): {
+export declare function usePresence(options?: ResourceHandle): {
   locations: UserPresence[]
 }
 
@@ -2850,12 +2755,12 @@ declare type UseProject = {
    * Returns metadata for a given project
    *
    * @category Projects
-   * @param projectId - The ID of the project to retrieve metadata for
+   * @param projectHandle - An optional project handle identifying which project to retrieve metadata for
    * @returns The metadata for the project
    * @example
    * ```tsx
    *  function ProjectMetadata({ projectId }: { projectId: string }) {
-   *    const project = useProject(projectId)
+   *    const project = useProject({ projectId })
    *
    *    return (
    *      <figure style={{ backgroundColor: project.metadata.color || 'lavender'}}>
@@ -2911,79 +2816,11 @@ declare type UseProjects = <TIncludeMembers extends boolean = false>(options?: {
  */
 export declare const useProjects: UseProjects
 
-/**
- * @public
- * Executes a GROQ query, inferring the result type from the query string and options.
- * Leverages Sanity Typegen if configured for enhanced type safety.
- *
- * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
- * @returns An object containing `data` (typed based on the query) and `isPending` (for transitions).
- *
- * @example Basic usage (Inferred Type)
- * ```tsx
- * import {useQuery} from '@sanity/sdk-react'
- * import {defineQuery} from 'groq'
- *
- * const myQuery = defineQuery(`*[_type == "movie"]{_id, title}`)
- *
- * function MovieList() {
- *   // Typegen infers the return type for data
- *   const {data} = useQuery({ query: myQuery })
- *
- *   return (
- *     <div>
- *       <h2>Movies</h2>
- *       <ul>
- *         {data.map(movie => <li key={movie._id}>{movie.title}</li>)}
- *       </ul>
- *     </div>
- *   )
- * }
- * // Suspense boundary should wrap <MovieList /> for initial load
- * ```
- *
- * @example Using parameters (Inferred Type)
- * ```tsx
- * import {useQuery} from '@sanity/sdk-react'
- * import {defineQuery} from 'groq'
- *
- * const myQuery = defineQuery(`*[_type == "movie" && _id == $id][0]`)
- *
- * function MovieDetails({movieId}: {movieId: string}) {
- *   // Typegen infers the return type based on query and params
- *   const {data, isPending} = useQuery({
- *     query: myQuery,
- *     params: { id: movieId }
- *   })
- *
- *   return (
- *     // utilize `isPending` to signal to users that new data is coming in
- *     // (e.g. the `movieId` changed and we're loading in the new one)
- *     <div style={{ opacity: isPending ? 0.5 : 1 }}>
- *       {data ? <h1>{data.title}</h1> : <p>Movie not found</p>}
- *     </div>
- *   )
- * }
- * ```
- */
-export declare function useQuery<
-  TQuery extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
->(
-  options: UseQueryOptions<TQuery, TDataset, TProjectId>,
-): {
-  /** The query result, typed based on the GROQ query string */
-  data: SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>
-  /** True if a query transition is in progress */
-  isPending: boolean
-}
-
 /**
  * @public
  * Executes a GROQ query with an explicitly provided result type `TData`.
  *
- * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
+ * @param options - Configuration for the query, including `query`, optional `params`, `resource`, etc.
  * @returns An object containing `data` (cast to `TData`) and `isPending` (indicates whether a query resolution is pending; note that Suspense handles initial loading states). *
  * @example Manually typed query result
  * ```tsx
@@ -3007,23 +2844,13 @@ export declare function useQuery<
  * }
  * ```
  */
-export declare function useQuery<TData>(options: WithSourceNameSupport<QueryOptions>): {
+export declare function useQuery<TData>(options: ReactQueryOptions): {
   /** The query result, cast to the provided type TData */
   data: TData
   /** True if another query is resolving in the background (suspense handles the initial loading state) */
   isPending: boolean
 }
 
-/**
- * Hook options for useQuery, supporting both direct source and sourceName.
- * @beta
- */
-declare type UseQueryOptions<
-  TQuery extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
-> = WithSourceNameSupport<QueryOptions<TQuery, TDataset, TProjectId>>
-
 /**
  * @internal
  * Hook for managing document interaction history in Sanity Studio.
@@ -3086,6 +2913,30 @@ declare interface UseRecordDocumentHistoryEventProps extends DocumentHandle {
   schemaName?: string
 }
 
+/**
+ * Returns the current {@link DocumentResource} from context.
+ *
+ * @public
+ *
+ * @category Platform
+ * @returns The resource set by the nearest `ResourceProvider`, or `undefined`
+ *
+ * @remarks
+ * With the flat instance model, nested `ResourceProvider`s override the
+ * active resource via React context rather than creating child instances.
+ * Use this hook when you need the current project/dataset/resource for a
+ * subtree instead of reading from `useSanityInstance().config`.
+ *
+ * @example Get the current resource
+ * ```tsx
+ * const resource = useResource()
+ * if (resource && 'projectId' in resource) {
+ *   console.log(resource.projectId, resource.dataset)
+ * }
+ * ```
+ */
+export declare function useResource(): DocumentResource | undefined
+
 /**
  * @public
  * @category Types
@@ -3125,60 +2976,26 @@ export declare interface UsersResult {
 }
 
 /**
- * Retrieves the current Sanity instance or finds a matching instance from the hierarchy
+ * Retrieves the current Sanity instance from React context.
  *
  * @public
  *
  * @category Platform
- * @param config - Optional configuration to match against when finding an instance
- * @returns The current or matching Sanity instance
+ * @returns The current instance
  *
  * @remarks
- * This hook accesses the nearest Sanity instance from the React context. When provided with
- * a configuration object, it traverses up the instance hierarchy to find the closest instance
- * that matches the specified configuration using shallow comparison of properties.
- *
- * The hook must be used within a component wrapped by a `ResourceProvider` or `SanityApp`.
- *
- * Use this hook when you need to:
- * - Access the current SanityInstance from context
- * - Find a specific instance with matching project/dataset configuration
- * - Access a parent instance with specific configuration values
+ * This hook accesses the nearest Sanity instance from React context,
+ * provided by a `ResourceProvider` or `SanityApp`.
  *
  * @example Get the current instance
  * ```tsx
- * // Get the current instance from context
  * const instance = useSanityInstance()
- * console.log(instance.config.projectId)
- * ```
- *
- * @example Find an instance with specific configuration
- * ```tsx
- * // Find an instance matching the given project and dataset
- * const instance = useSanityInstance({
- *   projectId: 'abc123',
- *   dataset: 'production'
- * })
- *
- * // Use instance for API calls
- * const fetchDocument = (docId) => {
- *   // Instance is guaranteed to have the matching config
- *   return client.fetch(`*[_id == $id][0]`, { id: docId })
- * }
- * ```
- *
- * @example Match partial configuration
- * ```tsx
- * // Find an instance with specific auth configuration
- * const instance = useSanityInstance({
- *   auth: { requireLogin: true }
- * })
+ * console.log(instance.config)
  * ```
  *
  * @throws Error if no SanityInstance is found in context
- * @throws Error if no matching instance is found for the provided config
  */
-export declare const useSanityInstance: (config?: SanityConfig) => SanityInstance
+export declare const useSanityInstance: () => SanityInstance
 
 /**
  * Hook that fetches studio workspaces and organizes them by projectId:dataset
@@ -3368,26 +3185,19 @@ export declare type WindowMessageHandler<TFrameMessage extends FrameMessage> = (
 ) => TFrameMessage['response']
 
 /**
- * Adds React hook support (sourceName resolution) to core types.
- * This wrapper allows hooks to accept `sourceName` as a convenience,
- * which is then resolved to a `DocumentSource` at the React layer.
- * For now, we are trying to avoid source name resolution in core --
- * functions having sources explicitly passed will reduce complexity.
- *
- * @typeParam T - The core type to extend (must have optional `source` field)
- * @beta
+ * You should generally prefer to use the React-layer handle types (ResourceHandle, DocumentHandle) from '\@sanity/sdk-react' instead.
+ * This type is useful for non-handles (like document actions) that we still want to resolve resources for.
+ * Adds React hook support (resourceName resolution) to core types.
+ * @internal
  */
-declare type WithSourceNameSupport<
-  T extends {
-    source?: DocumentSource
-  },
-> = T & {
+declare type WithResourceNameSupport<T> = Omit<T, 'resource'> & {
+  resource?: DocumentResource
   /**
-   * Optional name of a source to resolve from context.
-   * If provided, will be resolved to a `DocumentSource` via `SourcesContext`.
+   * Optional name of a resource to resolve from context.
+   * If provided, will be resolved to a `DocumentResource` via `ResourcesContext`.
    * @beta
    */
-  sourceName?: string
+  resourceName?: string
 }
 
 declare interface WorkspacesByProjectIdDataset {