@sanity/sdk-react 3.4.0-rc.0 → 3.5.0-next.20260922182803

package/src/hooks/dashboard/useAgentResourceContext.test.tsx

@@ -1,7 +1,9 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost, type PayloadOf} from '@sanity/sdk/dashboard'
 import {renderHook} from '@testing-library/react'
-import {beforeEach, describe, expect, it, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {AppProviders} from '../../../test/test-utils'
+import {AppProviders, renderHook as renderHookWithInstance} from '../../../test/test-utils'
 import {useWindowConnection} from '../comlink/useWindowConnection'
 import {useAgentResourceContext} from './useAgentResourceContext'
 
@@ -243,3 +245,66 @@ describe('useAgentResourceContext', () => {
     })
   })
 })
+
+describe('useAgentResourceContext (message bus)', () => {
+  const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+  let host: MessageBusHost
+
+  const collect = (): PayloadOf<'applications.context.update'>[] => {
+    const payloads: PayloadOf<'applications.context.update'>[] = []
+    host.subscribe('applications.context.update', (message) => payloads.push(message.payload))
+    return payloads
+  }
+
+  beforeEach(() => {
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+  })
+
+  it('maps the options to an application context payload', () => {
+    const payloads = collect()
+
+    renderHookWithInstance(() =>
+      useAgentResourceContext({projectId: 'proj', dataset: 'ds', documentId: 'doc'}),
+    )
+
+    expect(payloads).toEqual([{resource: {id: 'proj.ds', type: 'dataset'}, document: {id: 'doc'}}])
+    expect(useWindowConnection).not.toHaveBeenCalled()
+  })
+
+  it('does not re-emit when re-rendered with equal options', () => {
+    const payloads = collect()
+
+    const {rerender} = renderHookWithInstance((options) => useAgentResourceContext(options), {
+      initialProps: {projectId: 'proj', dataset: 'ds', documentId: 'doc'},
+    })
+    rerender({projectId: 'proj', dataset: 'ds', documentId: 'doc'})
+
+    expect(payloads).toHaveLength(1)
+  })
+
+  it('sets document to null when no documentId is given', () => {
+    const payloads = collect()
+
+    renderHookWithInstance(() => useAgentResourceContext({projectId: 'proj', dataset: 'ds'}))
+
+    expect(payloads).toEqual([{resource: {id: 'proj.ds', type: 'dataset'}, document: null}])
+  })
+
+  it.each([
+    {projectId: '', dataset: 'ds'},
+    {projectId: 'proj', dataset: ''},
+  ])('publishes null when a required field is missing (%o)', ({projectId, dataset}) => {
+    const payloads = collect()
+
+    renderHookWithInstance(() => useAgentResourceContext({projectId, dataset, documentId: 'doc'}))
+
+    expect(payloads).toEqual([null])
+  })
+})

package/src/hooks/dashboard/useAgentResourceContext.ts

@@ -1,8 +1,12 @@
+/* eslint-disable react-compiler/react-compiler -- the transport branch in `useAgentResourceContext` is a deliberate rules-of-hooks exception; the compiler refuses files that disable it */
 import {type Events, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {isDashboardEnvironment} from '@sanity/sdk/_internal'
 import {type FrameMessage} from '@sanity/sdk/comlink'
-import {useCallback, useEffect, useRef} from 'react'
+import {type ApplicationContext} from '@sanity/sdk/dashboard'
+import {useCallback, useEffect, useMemo, useRef} from 'react'
 
 import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useApplicationContext} from './useApplicationContext'
 
 /**
  * @public
@@ -24,12 +28,14 @@ export interface AgentResourceContextOptions {
 
 /**
  * @public
- * Hook for emitting agent resource context updates to the Dashboard.
- * This allows the Agent to understand what resource the user is currently
- * interacting with (e.g., which document they're editing).
+ * Hook for reporting the resource the user is currently interacting with (for example, which
+ * document they're editing) so the Agent can understand their context. The hook reports on mount
+ * and again whenever the context changes.
  *
- * The hook will automatically emit the context when it changes, and also
- * emit the initial context when the hook is first mounted.
+ * The two Dashboard runtimes differ in transport, but the signature is the same:
+ * - In an iframe (Comlink), it emits the `dashboard/v1/events/agent/resource/update` event.
+ * - In a federated app (message bus), it publishes {@link useApplicationContext}'s
+ *   `applications.context.update` topic. Reach for `useApplicationContext` directly in new code.
  *
  * @category Agent
  * @param options - The resource context options containing projectId, dataset, and optional documentId
@@ -53,6 +59,29 @@ export interface AgentResourceContextOptions {
  * ```
  */
 export function useAgentResourceContext(options: AgentResourceContextOptions): void {
+  // The branch is stable: the transport is fixed for the page lifetime, so one set of hooks
+  // always runs and the other never does.
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- transport is fixed for the page lifetime
+  if (isDashboardEnvironment()) return useBusAgentResourceContext(options)
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- transport is fixed for the page lifetime
+  return useComlinkAgentResourceContext(options)
+}
+
+function useBusAgentResourceContext({projectId, dataset, documentId}: AgentResourceContextOptions) {
+  const context = useMemo<ApplicationContext | null>(
+    () =>
+      projectId && dataset
+        ? {
+            resource: {id: `${projectId}.${dataset}`, type: 'dataset'},
+            document: documentId ? {id: documentId} : null,
+          }
+        : null,
+    [projectId, dataset, documentId],
+  )
+  useApplicationContext(context)
+}
+
+function useComlinkAgentResourceContext(options: AgentResourceContextOptions): void {
   const {projectId, dataset, documentId} = options
   const {sendMessage} = useWindowConnection<Events.AgentResourceUpdateMessage, FrameMessage>({
     name: SDK_NODE_NAME,

package/src/hooks/dashboard/useApplicationContext.test.tsx

@@ -0,0 +1,95 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {
+  type ApplicationContext,
+  type MessageBusHost,
+  type MessageBusMeta,
+  type PayloadOf,
+} from '@sanity/sdk/dashboard'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {useApplicationContext} from './useApplicationContext'
+
+type ContextUpdate = {
+  payload: PayloadOf<'applications.context.update'>
+  meta: MessageBusMeta
+}
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+const context: ApplicationContext = {
+  resource: {id: 'proj.ds', type: 'dataset'},
+  document: {id: 'doc'},
+}
+
+describe('useApplicationContext', () => {
+  beforeEach(() => {
+    // The SDK resolves its own app ID from the CLI-embedded global.
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+  })
+
+  const collect = (): ContextUpdate[] => {
+    const messages: ContextUpdate[] = []
+    host.subscribe('applications.context.update', (message) =>
+      messages.push({payload: message.payload, meta: message.meta}),
+    )
+    return messages
+  }
+
+  it('emits the context on mount', () => {
+    const messages = collect()
+
+    renderHook(() => useApplicationContext(context))
+
+    expect(messages.map((message) => message.payload)).toEqual([context])
+  })
+
+  it('does not re-emit when re-rendered with the same context', () => {
+    const messages = collect()
+
+    const {rerender} = renderHook(({value}) => useApplicationContext(value), {
+      initialProps: {value: context},
+    })
+    rerender({value: context})
+
+    expect(messages).toHaveLength(1)
+  })
+
+  it('clears the old context before publishing a new one', () => {
+    const messages = collect()
+
+    const {rerender} = renderHook(({value}) => useApplicationContext(value), {
+      initialProps: {value: context},
+    })
+    const next: ApplicationContext = {resource: {id: 'proj.ds', type: 'dataset'}, document: null}
+    rerender({value: next})
+
+    expect(messages.map((message) => message.payload)).toEqual([context, null, next])
+  })
+
+  it('emits null on unmount', () => {
+    const messages = collect()
+
+    const {unmount} = renderHook(() => useApplicationContext(context))
+    unmount()
+
+    expect(messages.map((message) => message.payload)).toEqual([context, null])
+  })
+
+  it('stamps the sending application id on the message', () => {
+    const messages = collect()
+
+    renderHook(() => useApplicationContext(context))
+
+    expect(messages[0].meta.appId).toBe('app')
+  })
+})

package/src/hooks/dashboard/useApplicationContext.ts

@@ -0,0 +1,47 @@
+import {type ApplicationContext} from '@sanity/sdk/dashboard'
+import {useEffect} from 'react'
+
+import {useEmit} from './useEmit'
+
+/**
+ * Publishes what this application is currently showing to the Dashboard message bus, so the host
+ * can hold the foreground application's context. Pass `null` when nothing is open.
+ *
+ * The context is published on mount and whenever it changes, and cleared with `null` on unmount.
+ * A change publishes `null` before the new context, as the component has stopped showing the old
+ * one. Pass a memoised value: the hook compares by reference, so a new object on every render
+ * republishes on every render.
+ *
+ * The host reads the sending application from `message.meta.appId`, so the payload carries no
+ * application ID.
+ *
+ * @param context - The application context to publish, or `null` to clear it
+ *
+ * @example
+ * ```tsx
+ * import {useApplicationContext} from '@sanity/sdk-react/dashboard'
+ * import {useMemo} from 'react'
+ *
+ * function DocumentView({documentId}: {documentId: string}) {
+ *   const context = useMemo(
+ *     () => ({resource: {id: 'my-project.production', type: 'dataset' as const}, document: {id: documentId}}),
+ *     [documentId],
+ *   )
+ *   useApplicationContext(context)
+ *   return <div>Editing {documentId}</div>
+ * }
+ * ```
+ *
+ * @public
+ * @category Dashboard
+ */
+export function useApplicationContext(context: ApplicationContext | null): void {
+  const emit = useEmit('applications.context.update')
+
+  useEffect(() => {
+    emit(context)
+    return () => {
+      emit(null)
+    }
+  }, [emit, context])
+}

package/src/hooks/dashboard/useApplications.test.tsx

@@ -1,5 +1,16 @@
+import {
+  type Application,
+  type ApplicationInclude,
+  type Installation,
+  type InstallationInclude,
+} from '@sanity/sdk'
 import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
-import {type MessageBusHost, TopicError, type ValueOf} from '@sanity/sdk/dashboard'
+import {
+  type LocalApplication,
+  type MessageBusHost,
+  TopicError,
+  type ValueOf,
+} from '@sanity/sdk/dashboard'
 import {Suspense} from 'react'
 import {ErrorBoundary} from 'react-error-boundary'
 import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
@@ -62,7 +73,7 @@ const application = {
         title: 'Summary',
         version: '1',
         moduleId: 'views/summary',
-        metadata: null,
+        metadata: {size: 'small'},
       },
       {
         id: 'asset-source-1',
@@ -84,7 +95,7 @@ const application = {
       },
     ],
   },
-}
+} satisfies Application<ApplicationInclude>
 
 const nonFederatedApplication = {
   ...application,
@@ -95,7 +106,7 @@ const nonFederatedApplication = {
   title: 'Legacy',
   isSingleton: false,
   config: {},
-}
+} satisfies Application<ApplicationInclude>
 
 const nonSingletonApplication = {
   ...application,
@@ -105,7 +116,7 @@ const nonSingletonApplication = {
   slug: 'canvas',
   title: 'Canvas',
   isSingleton: false,
-}
+} satisfies Application<ApplicationInclude>
 
 const externalApplication = {
   ...application,
@@ -113,7 +124,57 @@ const externalApplication = {
   name: 'external',
   slug: null,
   externalUrl: 'https://apps.example.com/external/index.html',
-}
+} satisfies Application<ApplicationInclude>
+
+// The workbench synthesises a dev-server app into the deployed shape and marks it with `local`.
+const localApplication = {
+  ...application,
+  id: 'application-5',
+  name: 'dev',
+  slug: null,
+  isSingleton: false,
+  externalUrl: 'http://localhost:3333',
+  organizationId: 'local',
+  local: {host: 'localhost', port: 3333},
+} satisfies LocalApplication
+
+const installation = {
+  id: 'installation-1',
+  applicationId: 'app-remote-1',
+  organizationId: 'organization-1',
+  installedBy: 'user-1',
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-02T00:00:00.000Z',
+  application: {
+    title: 'Remote App',
+    name: 'remote',
+    reference: 'sanity/remote',
+    slug: 'remote',
+    icon: null,
+    // Distinct from the installing org: the bundle is hosted under the publisher's org.
+    organizationId: 'organization-publisher',
+  },
+  interfaces: [
+    {
+      id: 'remote-view-1',
+      type: 'app',
+      name: 'remote',
+      title: 'Remote App',
+      version: '1',
+      moduleId: 'App',
+      metadata: null,
+    },
+    {
+      id: 'remote-panel-1',
+      type: 'panel',
+      name: 'remote-panel',
+      title: 'Remote Panel',
+      version: '1',
+      moduleId: 'views/panel',
+      metadata: null,
+    },
+  ],
+} satisfies Installation<InstallationInclude>
 
 const emitApplications = (value: unknown[]) =>
   host.connections.subscribe((client) =>
@@ -140,8 +201,12 @@ describe('useApplications', () => {
     const {result} = renderHook(() => useApplications())
 
     expectTypeOf(result.current).toEqualTypeOf<DashboardApplication[]>()
+    // The application member keeps its raw deployment fields; the union also admits installations.
     expectTypeOf<
-      Extract<keyof DashboardApplication, 'activeDeployment' | 'config'>
+      Extract<
+        keyof Exclude<DashboardApplication, {type: 'installation'}>,
+        'activeDeployment' | 'config'
+      >
     >().toEqualTypeOf<'activeDeployment' | 'config'>()
     const [federated, nonFederated, nonSingleton] = result.current
     expect(federated).toMatchObject({
@@ -180,6 +245,99 @@ describe('useApplications', () => {
     ])
     expect(nonFederated).toMatchObject({views: [], webWorkers: []})
     expect(nonSingleton?.views[0]?.module.entry).toBe('https://canvas.sanity.studio')
+    expect(result.current.map(({isLocal}) => isLocal)).toEqual([false, false, false])
+  })
+
+  it('marks dev-server applications local and loads their modules from the dev server', () => {
+    emitApplications([application, localApplication, installation])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current.map(({id, isLocal}) => [id, isLocal])).toEqual([
+      ['application-1', false],
+      ['application-5', true],
+      ['installation-1', false],
+    ])
+    const local = result.current[1]
+    expect(local).toMatchObject({type: 'coreApp', local: {host: 'localhost', port: 3333}})
+    expect(local?.views[0]?.module.entry).toBe('http://localhost:3333')
+    expect(local?.views[0]?.application).toMatchObject({id: 'application-5', isLocal: true})
+  })
+
+  it('shapes installations alongside applications in one consistent shape', () => {
+    emitApplications([application, installation])
+
+    const {result} = renderHook(() => useApplications())
+
+    const shaped = result.current.find(({id}) => id === 'installation-1')
+    expect(shaped).toMatchObject({
+      id: 'installation-1',
+      type: 'installation',
+      title: 'Remote App',
+      name: 'remote',
+      reference: 'sanity/remote',
+      slug: 'remote',
+      icon: null,
+      isSingleton: true,
+      visibility: 'default',
+      externalUrl: null,
+      organizationId: 'organization-publisher',
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-02T00:00:00.000Z',
+      installation,
+    })
+    // Raw record fields must not leak onto the shaped entry, nor the raw record onto its views.
+    expect(shaped).not.toHaveProperty('applicationId')
+    expect(shaped).not.toHaveProperty('installedBy')
+    expect(shaped?.views[0]?.application).not.toHaveProperty('installation')
+    expect(shaped?.views).toEqual([
+      expect.objectContaining({
+        name: 'remote',
+        surface: 'window',
+        module: {
+          entry: 'https://remote-apps-organization-publisher.sanity.run',
+          moduleId: 'installation-1/App',
+          version: '1',
+        },
+      }),
+      expect.objectContaining({
+        name: 'remote-panel',
+        surface: 'panel',
+        module: expect.objectContaining({moduleId: 'installation-1/views/panel'}),
+      }),
+    ])
+    expect(shaped?.webWorkers).toEqual([])
+  })
+
+  it('exposes no views for an installation without interfaces', () => {
+    const {interfaces: _interfaces, ...withoutInterfaces} = installation
+    emitApplications([withoutInterfaces])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current[0]).toMatchObject({id: 'installation-1', views: [], webWorkers: []})
+  })
+
+  it('exposes no views for an installation without a slug to derive an origin from', () => {
+    emitApplications([{...installation, application: {...installation.application, slug: null}}])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current[0]).toMatchObject({id: 'installation-1', views: [], webWorkers: []})
+  })
+
+  it('loads a dev-server application without a module federation manifest', () => {
+    const {config: _config, ...withoutManifest} = localApplication
+    emitApplications([withoutManifest])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current[0]?.views.map(({name}) => name)).toEqual([
+      'inbox',
+      'notifications',
+      'summary',
+      'library',
+    ])
   })
 
   it('follows topic updates without remapping unchanged lists', () => {