@sanity/sdk-react 2.5.0 → 2.7.0

package/dist/index.d.ts

@@ -10,6 +10,7 @@ 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'
@@ -49,6 +50,7 @@ import {SanityQueryResult} from 'groq'
 import {SanityUser} from '@sanity/sdk'
 import {SortOrderingItem} from '@sanity/types'
 import {StudioResource} from '@sanity/message-protocol'
+import {TokenSource} from '@sanity/sdk'
 import {UserPresence} from '@sanity/sdk'
 import {WindowMessage} from '@sanity/sdk'
 
@@ -176,18 +178,6 @@ declare interface DispatchIntent {
   dispatchIntent: () => void
 }
 
-/**
- * Document handle that optionally includes a source (e.g., media library source)
- * or projectId and dataset for traditional dataset sources
- * (but now marked optional since it's valid to just use a source)
- * @beta
- */
-declare interface DocumentHandleWithSource extends Omit<DocumentHandle, 'projectId' | 'dataset'> {
-  source?: DocumentSource
-  projectId?: string
-  dataset?: string
-}
-
 declare interface DocumentInteractionHistory {
   recordEvent: (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => void
 }
@@ -218,6 +208,7 @@ export declare interface DocumentsOptions<
   batchSize?: number
   /**
    * Sorting configuration for the results
+   * @beta
    */
   orderings?: SortOrderingItem[]
   /**
@@ -307,6 +298,13 @@ 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
+}
+
 /**
  * @public
  * @category Types
@@ -343,6 +341,7 @@ export declare interface PaginatedDocumentsOptions<
   pageSize?: number
   /**
    * Sorting configuration for the results
+   * @beta
    */
   orderings?: SortOrderingItem[]
   /**
@@ -446,6 +445,18 @@ export declare type ProjectWithoutMembers = Omit<SanityProject_2, 'members'>
  */
 export declare const REACT_SDK_VERSION: {}
 
+/** @internal */
+export declare function renderSanityApp(
+  rootElement: HTMLElement | null,
+  namedSources: NamedSources,
+  options: RenderSanitySDKAppOptions,
+  children: React.ReactNode,
+): () => void
+
+declare interface RenderSanitySDKAppOptions {
+  reactStrictMode?: boolean
+}
+
 /**
  * Provides a Sanity instance to child components through React Context
  *
@@ -518,12 +529,18 @@ export declare interface ResourceProviderProps extends SanityConfig {
  * 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.
+ * This allows your app to work with one or more of your organization's datasets.
+ *
+ * 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.
  *
  * @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.
+ *
  * @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
@@ -571,7 +588,7 @@ export declare interface ResourceProviderProps extends SanityConfig {
 export declare function SanityApp({
   children,
   fallback,
-  config,
+  config: configProp,
   ...props
 }: SanityAppProps): ReactElement
 
@@ -580,9 +597,16 @@ export declare function SanityApp({
  * @category Types
  */
 export declare interface SanityAppProps {
-  config: SanityConfig | SanityConfig[]
+  /**
+   * 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.
+   */
+  config?: SanityConfig | SanityConfig[]
   /** @deprecated use the `config` prop instead. */
   sanityConfigs?: SanityConfig[]
+  sources?: Record<string, DocumentSource>
   children: React.ReactNode
   fallback: React.ReactNode
 }
@@ -612,10 +636,73 @@ export declare interface SDKProviderProps extends AuthBoundaryProps {
   children: ReactNode
   config: SanityConfig | SanityConfig[]
   fallback: ReactNode
+  sources?: Record<string, DocumentSource>
 }
 
+/**
+ * React context that allows the SDK to auto-detect when it is running
+ * inside a Sanity Studio. The Studio provides a workspace handle via this
+ * context, and `SanityApp` reads it to derive `projectId`, `dataset`, and
+ * a reactive auth token — eliminating the need for manual configuration.
+ *
+ * @remarks
+ * This context is defined in `@sanity/sdk-react` and provided by the Studio.
+ * The Studio imports it from this package and wraps its component tree:
+ *
+ * ```tsx
+ * import {SDKStudioContext} from '@sanity/sdk-react'
+ *
+ * function StudioRoot({children}) {
+ *   const workspace = useWorkspace()
+ *   return (
+ *     <SDKStudioContext.Provider value={workspace}>
+ *       {children}
+ *     </SDKStudioContext.Provider>
+ *   )
+ * }
+ * ```
+ *
+ * When `SanityApp` is rendered inside this provider, it auto-configures
+ * without any `config` prop:
+ *
+ * ```tsx
+ * <SanityApp fallback={<Loading />}>
+ *   <MyComponent />
+ * </SanityApp>
+ * ```
+ *
+ * @public
+ */
+export declare const SDKStudioContext: Context<StudioWorkspaceHandle | null>
+
 export {SortOrderingItem}
 
+/**
+ * Minimal duck-typed interface representing a Sanity Studio workspace.
+ * The Studio's `Workspace` type satisfies this naturally — no import
+ * dependency on the `sanity` package is required.
+ *
+ * @public
+ */
+export declare interface StudioWorkspaceHandle {
+  /** The Sanity project ID for this workspace. */
+  projectId: string
+  /** The dataset name for this workspace. */
+  dataset: string
+  /** Authentication state for this workspace. */
+  auth: {
+    /**
+     * Reactive token source from the Studio's auth store.
+     * When present, the SDK subscribes for ongoing token sync — the Studio
+     * is the single authority for auth and handles token refresh.
+     *
+     * Optional because Studios before Aug 2022 may not expose it. When
+     * absent, the SDK falls back to localStorage/cookie discovery.
+     */
+    token?: TokenSource
+  }
+}
+
 declare interface StudioWorkspacesResult {
   workspacesByProjectIdAndDataset: WorkspacesByProjectIdDataset
   error: string | null
@@ -663,11 +750,69 @@ export declare const useActiveReleases: UseActiveReleases
 /**
  * @alpha
  * Generates content for a document (or specific fields) via Sanity Agent Actions.
+ *
+ * @remarks
+ * This hook provides a stable callback to trigger AI-powered content generation for documents.
+ *
+ * Features:
  * - Uses instruction templates with `$variables` and supports `instructionParams` (constants, fields, documents, GROQ queries).
  * - Can target specific paths/fields; supports image generation when targeting image fields.
  * - Supports optional `temperature`, `async`, `noWrite`, and `conditionalPaths`.
+ * - Returns a Subscribable stream for tracking generation progress.
+ *
+ * @returns A stable callback that triggers the action and yields a Subscribable stream.
  *
- * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ * @example Basic content generation
+ * ```tsx
+ * import {useAgentGenerate} from '@sanity/sdk-react'
+ *
+ * function GenerateDescription({documentId}: {documentId: string}) {
+ *   const generate = useAgentGenerate()
+ *
+ *   const handleGenerate = () => {
+ *     generate({
+ *       documentId,
+ *       instruction: 'Write a compelling product description based on the title: $title',
+ *       instructionParams: {
+ *         title: {type: 'field', path: 'title'},
+ *       },
+ *       targetPaths: ['description'],
+ *     }).subscribe({
+ *       next: (result) => console.log('Generation progress:', result),
+ *       complete: () => console.log('Generation complete'),
+ *       error: (err) => console.error('Generation failed:', err),
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleGenerate}>Generate Description</button>
+ * }
+ * ```
+ *
+ * @example Image generation
+ * ```tsx
+ * import {useAgentGenerate} from '@sanity/sdk-react'
+ *
+ * function GenerateProductImage({documentId}: {documentId: string}) {
+ *   const generate = useAgentGenerate()
+ *
+ *   const handleGenerateImage = () => {
+ *     generate({
+ *       documentId,
+ *       instruction: 'Generate a product photo for: $productName',
+ *       instructionParams: {
+ *         productName: {type: 'field', path: 'name'},
+ *       },
+ *       targetPaths: ['mainImage'],
+ *     }).subscribe({
+ *       complete: () => console.log('Image generated'),
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleGenerateImage}>Generate Image</button>
+ * }
+ * ```
+ *
+ * @category Agent Actions
  */
 export declare const useAgentGenerate: () => (
   options: AgentGenerateOptions,
@@ -676,22 +821,247 @@ export declare const useAgentGenerate: () => (
 /**
  * @alpha
  * Schema-aware patching with Sanity Agent Actions.
+ *
+ * @remarks
+ * This hook provides a stable callback to apply schema-validated patches to documents.
+ * Unlike {@link useEditDocument}, this uses the Agent Actions API which provides
+ * additional schema validation and safe merging capabilities.
+ *
+ * Features:
  * - Validates provided paths/values against the document schema and merges object values safely.
  * - Prevents duplicate keys and supports array appends (including after a specific keyed item).
  * - Accepts `documentId` or `targetDocument` (mutually exclusive).
+ * - Requires `schemaId` (e.g., `'_.schemas.default'`) and `target` to specify patch operations.
  * - Optional `async`, `noWrite`, `conditionalPaths`.
  *
- * Returns a stable callback that triggers the action and resolves a Promise with the patch result.
+ * Each entry in `target` specifies a `path`, an `operation` (`'set'`, `'append'`, `'mixed'`, or `'unset'`),
+ * and a `value` (required for all operations except `'unset'`).
+ *
+ * @returns A stable callback that triggers the action and resolves a Promise with the patch result.
+ *
+ * @example Basic field update
+ * ```tsx
+ * import {useAgentPatch} from '@sanity/sdk-react'
+ *
+ * function UpdateTitle({documentId}: {documentId: string}) {
+ *   const patch = useAgentPatch()
+ *
+ *   const handleUpdate = async () => {
+ *     const result = await patch({
+ *       documentId,
+ *       schemaId: '_.schemas.default',
+ *       target: [
+ *         {
+ *           path: 'title',
+ *           operation: 'set',
+ *           value: 'Updated Title',
+ *         },
+ *         {
+ *           path: 'lastModified',
+ *           operation: 'set',
+ *           value: new Date().toISOString(),
+ *         },
+ *       ],
+ *     })
+ *     console.log('Patch result:', result)
+ *   }
+ *
+ *   return <button onClick={handleUpdate}>Update Title</button>
+ * }
+ * ```
+ *
+ * @example Append items to an array
+ * ```tsx
+ * import {useAgentPatch} from '@sanity/sdk-react'
+ *
+ * function AddTag({documentId}: {documentId: string}) {
+ *   const patch = useAgentPatch()
+ *
+ *   const handleAddTag = async (newTag: string) => {
+ *     await patch({
+ *       documentId,
+ *       schemaId: '_.schemas.default',
+ *       target: {
+ *         path: 'tags',
+ *         operation: 'append',
+ *         value: [newTag],
+ *       },
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => handleAddTag('featured')}>
+ *       Add Featured Tag
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example Insert array item after a specific key
+ * ```tsx
+ * import {useAgentPatch} from '@sanity/sdk-react'
+ *
+ * function InsertContentBlock({
+ *   documentId,
+ *   afterKey,
+ * }: {
+ *   documentId: string
+ *   afterKey: string
+ * }) {
+ *   const patch = useAgentPatch()
+ *
+ *   const handleInsert = async () => {
+ *     await patch({
+ *       documentId,
+ *       schemaId: '_.schemas.default',
+ *       target: {
+ *         path: ['content', {_key: afterKey}],
+ *         operation: 'append',
+ *         value: [{_type: 'block', text: 'New paragraph inserted here.'}],
+ *       },
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleInsert}>Insert Block</button>
+ * }
+ * ```
+ *
+ * @example Create a new document with targetDocument
+ * ```tsx
+ * import {useAgentPatch} from '@sanity/sdk-react'
+ *
+ * function CreateProduct() {
+ *   const patch = useAgentPatch()
+ *
+ *   const handleCreate = async () => {
+ *     const result = await patch({
+ *       targetDocument: {
+ *         operation: 'create',
+ *         _type: 'product',
+ *       },
+ *       schemaId: '_.schemas.default',
+ *       target: [
+ *         {
+ *           path: 'title',
+ *           operation: 'set',
+ *           value: 'New Product',
+ *         },
+ *         {
+ *           path: 'price',
+ *           operation: 'set',
+ *           value: 29.99,
+ *         },
+ *         {
+ *           path: 'inStock',
+ *           operation: 'set',
+ *           value: true,
+ *         },
+ *       ],
+ *     })
+ *     console.log('Created document:', result.documentId)
+ *   }
+ *
+ *   return <button onClick={handleCreate}>Create Product</button>
+ * }
+ * ```
+ *
+ * @category Agent Actions
  */
 export declare const useAgentPatch: () => (options: AgentPatchOptions) => Promise<AgentPatchResult>
 
 /**
  * @alpha
- * Prompts the LLM using the same instruction template format as other actions.
+ * Prompts the Content Agent using the same instruction template format as other agent actions.
+ *
+ * @remarks
+ * This hook provides a stable callback to send prompts to the Content Agent and receive responses.
+ * Unlike the other agent action hooks, this one does not modify documents—it simply
+ * returns the AI's response.
+ *
+ * Features:
+ * - Uses the same instruction template format with `$variables` as other actions.
  * - `format`: 'string' or 'json' (instruction must contain the word "json" for JSON responses).
- * - Optional `temperature`.
+ * - Supports `instructionParams` for dynamic content (constants, fields, documents, GROQ queries).
+ * - Optional `temperature` for controlling response creativity.
+ *
+ * @returns A stable callback that triggers the action and resolves a Promise with the prompt result.
  *
- * Returns a stable callback that triggers the action and resolves a Promise with the prompt result.
+ * @example Basic string prompt
+ * ```tsx
+ * import {useState} from 'react'
+ * import {useAgentPrompt} from '@sanity/sdk-react'
+ *
+ * function AskQuestion() {
+ *   const prompt = useAgentPrompt()
+ *   const [answer, setAnswer] = useState<string>('')
+ *
+ *   const handleAsk = async () => {
+ *     const result = await prompt({
+ *       instruction: 'What are the top 3 benefits of content modeling?',
+ *       format: 'string',
+ *     })
+ *     setAnswer(result.output)
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleAsk}>Ask AI</button>
+ *       {answer && <p>{answer}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example JSON response with instruction params
+ * ```tsx
+ * import {useState} from 'react'
+ * import {useAgentPrompt} from '@sanity/sdk-react'
+ *
+ * interface TagSuggestions {
+ *   tags: string[]
+ *   reasoning: string
+ * }
+ *
+ * function SuggestTags({documentId}: {documentId: string}) {
+ *   const prompt = useAgentPrompt()
+ *   const [suggestions, setSuggestions] = useState<TagSuggestions | null>(null)
+ *
+ *   const handleSuggest = async () => {
+ *     const result = await prompt({
+ *       instruction: `
+ *         Based on the following article title and content, suggest relevant tags.
+ *         Return as json with "tags" (array of strings) and "reasoning" (string).
+ *         Title: $title
+ *         Content: $body
+ *       `,
+ *       instructionParams: {
+ *         title: {type: 'field', path: 'title', documentId},
+ *         body: {type: 'field', path: 'body', documentId},
+ *       },
+ *       format: 'json',
+ *     })
+ *     setSuggestions(result.output as TagSuggestions)
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleSuggest}>Suggest Tags</button>
+ *       {suggestions && (
+ *         <div>
+ *           <p>Reasoning: {suggestions.reasoning}</p>
+ *           <ul>
+ *             {suggestions.tags.map((tag) => (
+ *               <li key={tag}>{tag}</li>
+ *             ))}
+ *           </ul>
+ *         </div>
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @category Agent Actions
  */
 export declare const useAgentPrompt: () => (
   options: AgentPromptOptions,
@@ -732,12 +1102,73 @@ export declare function useAgentResourceContext(options: AgentResourceContextOpt
 /**
  * @alpha
  * Transforms an existing document or selected fields using Sanity Agent Actions.
+ *
+ * @remarks
+ * This hook provides a stable callback to apply AI-powered transformations to document content.
+ *
+ * Features:
  * - Accepts `instruction` and `instructionParams` (constants, fields, documents, GROQ queries).
  * - Can write to the same or a different `targetDocument` (create/edit), and target specific paths.
  * - Supports per-path image transform instructions and image description operations.
  * - Optional `temperature`, `async`, `noWrite`, `conditionalPaths`.
  *
- * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ * @returns A stable callback that triggers the action and yields a Subscribable stream.
+ *
+ * @example Transform text content
+ * ```tsx
+ * import {useAgentTransform} from '@sanity/sdk-react'
+ *
+ * function SummarizeArticle({documentId}: {documentId: string}) {
+ *   const transform = useAgentTransform()
+ *
+ *   const handleSummarize = () => {
+ *     transform({
+ *       documentId,
+ *       instruction: 'Summarize the following content into 2-3 sentences: $body',
+ *       instructionParams: {
+ *         body: {type: 'field', path: 'body'},
+ *       },
+ *       targetPaths: ['summary'],
+ *     }).subscribe({
+ *       complete: () => console.log('Summary generated'),
+ *       error: (err) => console.error('Transform failed:', err),
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleSummarize}>Generate Summary</button>
+ * }
+ * ```
+ *
+ * @example Transform and write to a different document
+ * ```tsx
+ * import {useAgentTransform} from '@sanity/sdk-react'
+ *
+ * function CreateVariant({sourceDocumentId}: {sourceDocumentId: string}) {
+ *   const transform = useAgentTransform()
+ *
+ *   const handleCreateVariant = () => {
+ *     transform({
+ *       documentId: sourceDocumentId,
+ *       instruction: 'Rewrite this product description for a younger audience: $description',
+ *       instructionParams: {
+ *         description: {type: 'field', path: 'description'},
+ *       },
+ *       targetDocument: {
+ *         operation: 'create',
+ *         _type: 'product',
+ *       },
+ *       targetPaths: ['description'],
+ *     }).subscribe({
+ *       next: (result) => console.log('New document:', result),
+ *       complete: () => console.log('Variant created'),
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleCreateVariant}>Create Youth Variant</button>
+ * }
+ * ```
+ *
+ * @category Agent Actions
  */
 export declare const useAgentTransform: () => (
   options: AgentTransformOptions,
@@ -746,11 +1177,92 @@ export declare const useAgentTransform: () => (
 /**
  * @alpha
  * Translates documents or fields using Sanity Agent Actions.
+ *
+ * @remarks
+ * This hook provides a stable callback to translate document content between languages using AI.
+ *
+ * Features:
  * - Configure `fromLanguage`/`toLanguage`, optional `styleGuide`, and `protectedPhrases`.
  * - Can write into a different `targetDocument`, and/or store language in a field.
  * - Optional `temperature`, `async`, `noWrite`, `conditionalPaths`.
  *
- * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ * @returns A stable callback that triggers the action and yields a Subscribable stream.
+ *
+ * @example Basic translation
+ * ```tsx
+ * import {useAgentTranslate} from '@sanity/sdk-react'
+ *
+ * function TranslateArticle({documentId}: {documentId: string}) {
+ *   const translate = useAgentTranslate()
+ *
+ *   const handleTranslate = () => {
+ *     translate({
+ *       documentId,
+ *       fromLanguage: 'en',
+ *       toLanguage: 'es',
+ *       targetPaths: ['title', 'body'],
+ *     }).subscribe({
+ *       complete: () => console.log('Translation complete'),
+ *       error: (err) => console.error('Translation failed:', err),
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleTranslate}>Translate to Spanish</button>
+ * }
+ * ```
+ *
+ * @example Translation with style guide and protected phrases
+ * ```tsx
+ * import {useAgentTranslate} from '@sanity/sdk-react'
+ *
+ * function TranslateWithBrandTerms({documentId}: {documentId: string}) {
+ *   const translate = useAgentTranslate()
+ *
+ *   const handleTranslate = () => {
+ *     translate({
+ *       documentId,
+ *       fromLanguage: 'en',
+ *       toLanguage: 'fr',
+ *       styleGuide: 'Use formal French appropriate for business communication.',
+ *       protectedPhrases: ['Acme Corp', 'PowerWidget Pro'],
+ *       targetPaths: ['title', 'description'],
+ *     }).subscribe({
+ *       complete: () => console.log('Translation complete'),
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleTranslate}>Translate to French</button>
+ * }
+ * ```
+ *
+ * @example Translate to a new document
+ * ```tsx
+ * import {useAgentTranslate} from '@sanity/sdk-react'
+ *
+ * function CreateTranslatedCopy({documentId}: {documentId: string}) {
+ *   const translate = useAgentTranslate()
+ *
+ *   const handleCreateTranslation = () => {
+ *     translate({
+ *       documentId,
+ *       fromLanguage: 'en',
+ *       toLanguage: 'de',
+ *       targetDocument: {
+ *         operation: 'create',
+ *         _type: 'article',
+ *       },
+ *       languageFieldPath: 'language',
+ *     }).subscribe({
+ *       next: (result) => console.log('New translated document:', result),
+ *       complete: () => console.log('Translated copy created'),
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleCreateTranslation}>Create German Copy</button>
+ * }
+ * ```
+ *
+ * @category Agent Actions
  */
 export declare const useAgentTranslate: () => (
   options: AgentTranslateOptions,
@@ -1146,7 +1658,7 @@ export declare function useDispatchIntent(params: UseDispatchIntentParams): Disp
 declare interface UseDispatchIntentParams {
   action?: 'edit'
   intentId?: string
-  documentHandle: DocumentHandleWithSource
+  documentHandle: WithSourceNameSupport<DocumentHandle>
   parameters?: Record<string, unknown>
 }
 
@@ -1729,7 +2241,7 @@ export declare interface useDocumentProjectionOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
+> extends WithSourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
   /** The GROQ projection string */
   projection: TProjection
   /** Optional parameters for the projection query */
@@ -2459,7 +2971,7 @@ export declare function useQuery<
   TDataset extends string = string,
   TProjectId extends string = string,
 >(
-  options: QueryOptions<TQuery, TDataset, TProjectId>,
+  options: UseQueryOptions<TQuery, TDataset, TProjectId>,
 ): {
   /** The query result, typed based on the GROQ query string */
   data: SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>
@@ -2495,13 +3007,23 @@ export declare function useQuery<
  * }
  * ```
  */
-export declare function useQuery<TData>(options: QueryOptions): {
+export declare function useQuery<TData>(options: WithSourceNameSupport<QueryOptions>): {
   /** 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.
@@ -2845,6 +3367,29 @@ export declare type WindowMessageHandler<TFrameMessage extends FrameMessage> = (
   event: TFrameMessage['data'],
 ) => 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
+ */
+declare type WithSourceNameSupport<
+  T extends {
+    source?: DocumentSource
+  },
+> = T & {
+  /**
+   * Optional name of a source to resolve from context.
+   * If provided, will be resolved to a `DocumentSource` via `SourcesContext`.
+   * @beta
+   */
+  sourceName?: string
+}
+
 declare interface WorkspacesByProjectIdDataset {
   [key: `${string}:${string}`]: DashboardResource[]
 }