@sanity/sdk-react 3.3.0-rc.0 → 3.3.0

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

@@ -0,0 +1,77 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost, TopicError} from '@sanity/sdk/dashboard'
+import {Suspense} from 'react'
+import {ErrorBoundary} from 'react-error-boundary'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {act, render, screen} from '../../../test/test-utils'
+import {useApplicationBasePath} from './useApplicationBasePath'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+describe('useApplicationBasePath', () => {
+  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('suspends until Dashboard publishes, then follows updates', async () => {
+    function BasePath() {
+      const basePath = useApplicationBasePath()
+      expectTypeOf(basePath).toEqualTypeOf<string>()
+      return <span>{basePath}</span>
+    }
+
+    render(
+      <Suspense fallback="Loading">
+        <BasePath />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) =>
+        client.emit('applications.base-path', {ok: true, value: '/application/app'}),
+      )
+    })
+    expect(await screen.findByText('/application/app')).toBeInTheDocument()
+
+    act(() =>
+      host.connections.subscribe((client) =>
+        client.emit('applications.base-path', {ok: true, value: '/application/app-2'}),
+      ),
+    )
+    expect(screen.getByText('/application/app-2')).toBeInTheDocument()
+  })
+
+  it('throws a TopicError when the application is unknown', () => {
+    host.connections.subscribe((client) => client.emit('applications.base-path', {ok: false}))
+    const onError = vi.fn()
+
+    function BasePath() {
+      return <span>{useApplicationBasePath()}</span>
+    }
+
+    render(
+      <ErrorBoundary fallback={<span>Failed</span>} onError={onError}>
+        <Suspense fallback="Loading">
+          <BasePath />
+        </Suspense>
+      </ErrorBoundary>,
+    )
+
+    expect(screen.getByText('Failed')).toBeInTheDocument()
+    const error = onError.mock.calls[0][0] as TopicError
+    expect(error).toBeInstanceOf(TopicError)
+    expect(error.topic).toBe('applications.base-path')
+  })
+})

package/src/hooks/dashboard/useApplicationBasePath.ts

@@ -0,0 +1,23 @@
+import {type TopicData} from '@sanity/sdk/dashboard'
+
+import {useTopic} from './useTopic'
+
+/**
+ * Returns the base path for an application.
+ *
+ * Suspends until Dashboard publishes the path and throws a `TopicError` when the application is
+ * unknown.
+ *
+ * @example
+ * ```tsx
+ * function ApplicationBasePath() {
+ *   const basePath = useApplicationBasePath()
+ *   return <span>{basePath}</span>
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useApplicationBasePath(): TopicData<'applications.base-path'> {
+  return useTopic('applications.base-path')
+}

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

@@ -134,15 +134,24 @@ describe('useApplications', () => {
     vi.restoreAllMocks()
   })
 
-  it('returns minimal applications with loadable views and web workers', () => {
+  it('returns full applications with loadable views and web workers', () => {
     emitApplications([application, nonFederatedApplication, nonSingletonApplication])
 
     const {result} = renderHook(() => useApplications())
 
     expectTypeOf(result.current).toEqualTypeOf<DashboardApplication[]>()
+    expectTypeOf<
+      Extract<keyof DashboardApplication, 'activeDeployment' | 'config'>
+    >().toEqualTypeOf<'activeDeployment' | 'config'>()
     const [federated, nonFederated, nonSingleton] = result.current
-    expect(federated).not.toHaveProperty('activeDeployment')
-    expect(federated).not.toHaveProperty('config')
+    expect(federated).toMatchObject({
+      activeDeployment: {id: 'deployment-1'},
+      config: {mfManifest: {}},
+    })
+    expect(federated?.views[0]?.application).not.toHaveProperty('activeDeployment')
+    expect(federated?.views[0]?.application).not.toHaveProperty('config')
+    expect(federated?.webWorkers[0]?.application).not.toHaveProperty('activeDeployment')
+    expect(federated?.webWorkers[0]?.application).not.toHaveProperty('config')
     expect(federated?.views).toEqual([
       expect.objectContaining({
         application: expect.objectContaining({id: 'application-1'}),

package/src/hooks/dashboard/useApplications.ts

@@ -1,4 +1,5 @@
 import {type ApplicationBase} from '@sanity/sdk'
+import {getApplicationOrigin} from '@sanity/sdk/_internal'
 import {type RemoteModuleRef, type ValueOf} from '@sanity/sdk/dashboard'
 import {useMemo} from 'react'
 
@@ -38,31 +39,11 @@ export type DashboardWebWorker = Extract<DashboardApplicationInterface, {type: '
  * The minimal Brett application fields with its loadable views and web workers.
  * @public
  */
-export type DashboardApplication = ApplicationBase & {
+export type DashboardApplication = DashboardTopicApplication & {
   readonly views: DashboardView[]
   readonly webWorkers: DashboardWebWorker[]
 }
 
-type SanityGlobal = typeof globalThis & {__SANITY_STAGING__?: boolean}
-
-// `null` when neither address exists: the caller exposes no modules for that application
-// rather than failing the whole list on one bad record.
-const applicationOrigin = (application: ApplicationBase): string | null => {
-  if (application.externalUrl !== null) return new URL(application.externalUrl).origin
-  if (application.slug === null) return null
-
-  // Read at runtime, not via a bundler define: a remote is built once and runs in whichever
-  // host page loaded it, and the host sets this flag. Mirrors workbench's `getSanityEnv`.
-  const staging = (globalThis as SanityGlobal).__SANITY_STAGING__ === true
-  if (application.isSingleton) {
-    const domain = staging ? 'run.sanity.work' : 'sanity.run'
-    return `https://${application.slug}-apps-${application.organizationId}.${domain}`
-  }
-
-  const domain = staging ? 'studio.sanity.work' : 'sanity.studio'
-  return `https://${application.slug}.${domain}`
-}
-
 // Only a federated deployment (one with a module federation manifest) exposes loadable modules.
 const loadableInterfaces = ({
   activeDeployment,
@@ -74,8 +55,8 @@ const toApplication = (application: DashboardTopicApplication): DashboardApplica
   const {activeDeployment: _activeDeployment, config: _config, ...applicationBase} = application
   const interfaces = loadableInterfaces(application)
   // Nothing to load without interfaces or an origin to load them from.
-  const entry = interfaces.length === 0 ? null : applicationOrigin(applicationBase)
-  if (entry === null) return {...applicationBase, views: [], webWorkers: []}
+  const entry = interfaces.length === 0 ? null : getApplicationOrigin(applicationBase)
+  if (entry === null) return {...application, views: [], webWorkers: []}
 
   const views: DashboardView[] = []
   const webWorkers: DashboardWebWorker[] = []
@@ -103,7 +84,7 @@ const toApplication = (application: DashboardTopicApplication): DashboardApplica
     } as DashboardView)
   }
 
-  return {...applicationBase, views, webWorkers}
+  return {...application, views, webWorkers}
 }
 
 /**

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

@@ -0,0 +1,48 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost} from '@sanity/sdk/dashboard'
+import {Suspense} from 'react'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {act, render, screen} from '../../../test/test-utils'
+import {useAuthToken} from './useAuthToken'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+describe('useAuthToken', () => {
+  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()
+  })
+
+  it('suspends until Dashboard publishes, then follows updates', async () => {
+    function Token() {
+      const token = useAuthToken()
+      expectTypeOf(token).toEqualTypeOf<string | null>()
+      return <span>{token ?? 'none'}</span>
+    }
+    render(
+      <Suspense fallback="Loading">
+        <Token />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('auth.token', null))
+    })
+    expect(await screen.findByText('none')).toBeInTheDocument()
+
+    act(() => host.connections.subscribe((client) => client.emit('auth.token', 'token-1')))
+    expect(screen.getByText('token-1')).toBeInTheDocument()
+  })
+})

package/src/hooks/dashboard/useAuthToken.ts

@@ -0,0 +1,20 @@
+import {useTopic} from './useTopic'
+
+/**
+ * Returns the session token for the reading connection, or `null` while signed out.
+ *
+ * Suspends until Dashboard publishes the token.
+ *
+ * @example
+ * ```tsx
+ * function AuthToken() {
+ *   const token = useAuthToken()
+ *   return <span>{token ?? 'Signed out'}</span>
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useAuthToken(): string | null {
+  return useTopic('auth.token')
+}

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

@@ -0,0 +1,57 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost} from '@sanity/sdk/dashboard'
+import {type CurrentUser} from '@sanity/types'
+import {Suspense} from 'react'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {act, render, screen} from '../../../test/test-utils'
+import {useCurrentUser} from './useCurrentUser'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+const user: CurrentUser = {
+  id: 'user-1',
+  name: 'Ada Lovelace',
+  email: 'ada@example.com',
+  role: '',
+  roles: [],
+}
+
+let host: MessageBusHost
+
+describe('useCurrentUser', () => {
+  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()
+  })
+
+  it('suspends until Dashboard publishes, then follows updates', async () => {
+    function User() {
+      const current = useCurrentUser()
+      expectTypeOf(current).toEqualTypeOf<CurrentUser | null>()
+      return <span>{current?.name ?? 'none'}</span>
+    }
+    render(
+      <Suspense fallback="Loading">
+        <User />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('users.current', null))
+    })
+    expect(await screen.findByText('none')).toBeInTheDocument()
+
+    act(() => host.connections.subscribe((client) => client.emit('users.current', user)))
+    expect(screen.getByText('Ada Lovelace')).toBeInTheDocument()
+  })
+})

package/src/hooks/dashboard/useCurrentUser.ts

@@ -0,0 +1,22 @@
+import {type CurrentUser} from '@sanity/types'
+
+import {useTopic} from './useTopic'
+
+/**
+ * Returns the signed-in user, or `null` while signed out.
+ *
+ * Suspends until Dashboard publishes the current user.
+ *
+ * @example
+ * ```tsx
+ * function CurrentUser() {
+ *   const user = useCurrentUser()
+ *   return <span>{user?.name ?? 'Signed out'}</span>
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useCurrentUser(): CurrentUser | null {
+  return useTopic('users.current')
+}

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

@@ -1,8 +1,11 @@
 import {getDashboardOrganizationId} from '@sanity/sdk'
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost} from '@sanity/sdk/dashboard'
 import {renderHook} from '@testing-library/react'
 import {throwError} from 'rxjs'
-import {describe, expect, it, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
+import {act} from '../../../test/test-utils'
 import {ResourceProvider} from '../../context/ResourceProvider'
 import {useOrganizationId} from './useOrganizationId'
 
@@ -11,6 +14,8 @@ vi.mock('@sanity/sdk', async (importOriginal) => {
   return {...(actual || {}), getDashboardOrganizationId: vi.fn()}
 })
 
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
 describe('useOrganizationId', () => {
   it('should return undefined when no organization ID is set', () => {
     const subscribe = vi.fn()
@@ -49,3 +54,49 @@ describe('useOrganizationId', () => {
     expect(result.current).toBe(mockOrgId)
   })
 })
+
+describe('useOrganizationId (message bus)', () => {
+  let host: MessageBusHost
+
+  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()
+  })
+
+  const wrapper = ({children}: {children: React.ReactNode}) => (
+    <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+      {children}
+    </ResourceProvider>
+  )
+
+  it('is undefined before the host publishes the current organization', () => {
+    const {result} = renderHook(() => useOrganizationId(), {wrapper})
+    expect(result.current).toBeUndefined()
+  })
+
+  it('returns the organization id once the host publishes it', () => {
+    const {result} = renderHook(() => useOrganizationId(), {wrapper})
+
+    act(() =>
+      host.connections.subscribe((client) =>
+        client.emit('organizations.current', {id: 'org_123', name: 'Org', slug: 'org'}),
+      ),
+    )
+
+    expect(result.current).toBe('org_123')
+  })
+
+  it('is undefined when the host publishes no active organization', () => {
+    const {result} = renderHook(() => useOrganizationId(), {wrapper})
+
+    act(() => host.connections.subscribe((client) => client.emit('organizations.current', null)))
+
+    expect(result.current).toBeUndefined()
+  })
+})

package/src/hooks/dashboard/useOrganizationId.tsx

@@ -1,13 +1,19 @@
-import {getDashboardOrganizationId} from '@sanity/sdk'
+import {getDashboardOrganizationId, type OrganizationBase} from '@sanity/sdk'
+import {getTopicState, isDashboardEnvironment} from '@sanity/sdk/_internal'
 import {useMemo, useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
+type CurrentOrganization = Pick<OrganizationBase, 'id' | 'name' | 'slug'> | null | undefined
+
 /**
  * @public
  *
  * A React hook that retrieves the dashboard organization ID that is currently selected in the Sanity Dashboard.
  *
+ * Works in both Dashboard runtimes: it reads the `organizations.current` message bus topic when a
+ * host has installed the bus, and falls back to the Comlink connection otherwise.
+ *
  * @example
  * ```tsx
  * function DashboardComponent() {
@@ -24,7 +30,14 @@ import {useSanityInstance} from '../context/useSanityInstance'
  */
 export function useOrganizationId(): string | undefined {
   const instance = useSanityInstance()
-  const {subscribe, getCurrent} = useMemo(() => getDashboardOrganizationId(instance), [instance])
+  const {subscribe, getCurrent} = useMemo(() => {
+    if (!isDashboardEnvironment()) return getDashboardOrganizationId(instance)
+    const source = getTopicState(instance, 'organizations.current')
+    return {
+      subscribe: source.subscribe,
+      getCurrent: () => (source.getCurrent() as CurrentOrganization)?.id ?? undefined,
+    }
+  }, [instance])
 
   return useSyncExternalStore(subscribe, getCurrent)
 }

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

@@ -1,6 +1,11 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost, TopicError, type ValueOf} from '@sanity/sdk/dashboard'
 import {renderHook, waitFor} from '@testing-library/react'
-import {describe, expect, it, vi} from 'vitest'
+import {Suspense} from 'react'
+import {ErrorBoundary} from 'react-error-boundary'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
+import {render, renderHook as renderHookWithInstance, screen} from '../../../test/test-utils'
 import {useWindowConnection} from '../comlink/useWindowConnection'
 import {useStudioWorkspacesByProjectIdDataset} from './useStudioWorkspacesByProjectIdDataset'
 
@@ -218,3 +223,139 @@ describe('useStudioWorkspacesByResourceId', () => {
     })
   })
 })
+
+describe('useStudioWorkspacesByProjectIdDataset (message bus)', () => {
+  const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+  let host: MessageBusHost
+
+  const deployment = {
+    id: 'deployment-1',
+    applicationId: 'studio-1',
+    size: null,
+    version: '4.0.0',
+    isAutoUpdating: true,
+    isActiveDeployment: true,
+    deployedBy: null,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-02T00:00:00.000Z',
+    interfaces: [],
+  }
+
+  const workspace = {
+    id: 'workspace-1',
+    name: 'production',
+    title: 'Production',
+    subtitle: null,
+    projectId: 'project1',
+    dataset: 'dataset1',
+    schemaDescriptorId: null,
+    basePath: '/production',
+    icon: null,
+  }
+
+  const studio = {
+    id: 'studio-1',
+    type: 'studio',
+    title: 'My Studio',
+    name: 'my-studio',
+    reference: 'organization-1/my-studio',
+    icon: null,
+    isSingleton: false,
+    visibility: 'default',
+    slug: 'my-studio',
+    externalUrl: null,
+    organizationId: 'organization-1',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-02T00:00:00.000Z',
+    config: {},
+    activeDeployment: {
+      ...deployment,
+      workspaces: [
+        workspace,
+        {...workspace, id: 'workspace-2', name: 'staging', title: null, basePath: null},
+        {...workspace, id: 'workspace-3', projectId: 'project2', dataset: 'dataset2'},
+      ],
+    },
+  }
+
+  const coreApp = {
+    ...studio,
+    id: 'app-1',
+    type: 'coreApp',
+    activeDeployment: {...deployment, applicationId: 'app-1', workspaces: [workspace]},
+  }
+
+  const emitApplications = (value: unknown[] | null) =>
+    host.connections.subscribe((client) =>
+      client.emit(
+        'applications.list',
+        (value === null ? null : {ok: true, value}) as ValueOf<'applications.list'>,
+      ),
+    )
+
+  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 studio workspaces to resources keyed by projectId:dataset', () => {
+    emitApplications([studio, coreApp])
+
+    const {result} = renderHookWithInstance(() => useStudioWorkspacesByProjectIdDataset())
+
+    expect(useWindowConnection).not.toHaveBeenCalled()
+    expect(result.current.error).toBeNull()
+    expect(result.current.workspacesByProjectIdAndDataset).toEqual({
+      'project1:dataset1': [
+        {
+          id: 'workspace-1',
+          name: 'production',
+          title: 'Production',
+          basePath: '/production',
+          projectId: 'project1',
+          dataset: 'dataset1',
+          type: 'studio',
+          userApplicationId: 'studio-1',
+          url: 'https://my-studio.sanity.studio',
+        },
+        expect.objectContaining({id: 'workspace-2', title: 'My Studio', basePath: ''}),
+      ],
+      'project2:dataset2': [expect.objectContaining({id: 'workspace-3'})],
+    })
+  })
+
+  it('returns an empty map when the dashboard clears its applications', () => {
+    emitApplications(null)
+
+    const {result} = renderHookWithInstance(() => useStudioWorkspacesByProjectIdDataset())
+
+    expect(result.current.workspacesByProjectIdAndDataset).toEqual({})
+  })
+
+  it('throws a TopicError to the error boundary when the dashboard fails to load applications', () => {
+    host.connections.subscribe((client) => client.emit('applications.list', {ok: false}))
+    const onError = vi.fn()
+
+    function Workspaces() {
+      const {workspacesByProjectIdAndDataset} = useStudioWorkspacesByProjectIdDataset()
+      return <span>{Object.keys(workspacesByProjectIdAndDataset).length} workspaces</span>
+    }
+
+    render(
+      <ErrorBoundary fallback={<span>Failed</span>} onError={onError}>
+        <Suspense fallback="Loading">
+          <Workspaces />
+        </Suspense>
+      </ErrorBoundary>,
+    )
+
+    expect(screen.getByText('Failed')).toBeInTheDocument()
+    expect(onError.mock.calls[0][0]).toBeInstanceOf(TopicError)
+  })
+})

package/src/hooks/dashboard/useStudioWorkspacesByProjectIdDataset.ts

@@ -1,7 +1,11 @@
+/* eslint-disable react-compiler/react-compiler -- the transport branch in `useStudioWorkspacesByProjectIdDataset` is a deliberate rules-of-hooks exception; the compiler refuses files that disable it */
 import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
-import {useEffect, useState} from 'react'
+import {getApplicationOrigin, isDashboardEnvironment} from '@sanity/sdk/_internal'
+import {type TopicData} from '@sanity/sdk/dashboard'
+import {useEffect, useMemo, useState} from 'react'
 
 import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useTopic} from './useTopic'
 
 export interface DashboardResource {
   id: string
@@ -24,8 +28,13 @@ interface StudioWorkspacesResult {
   error: string | null
 }
 
+type DashboardApplications = NonNullable<TopicData<'applications.list'>>
+
 /**
  * Hook that fetches studio workspaces and organizes them by projectId:dataset
+ *
+ * Works in both Dashboard runtimes: it derives workspaces from the `applications.list` message
+ * bus topic when a host has installed the bus, and falls back to the Comlink connection otherwise.
  * @internal
  *
  * @example
@@ -59,6 +68,54 @@ interface StudioWorkspacesResult {
  * ```
  */
 export function useStudioWorkspacesByProjectIdDataset(): StudioWorkspacesResult {
+  // 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 useBusStudioWorkspaces()
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- transport is fixed for the page lifetime
+  return useComlinkStudioWorkspaces()
+}
+
+// The legacy Comlink protocol models studios at the workspace level, so each workspace of a
+// studio's active deployment becomes one resource, addressed by the studio's origin.
+function toResources(application: DashboardApplications[number]): DashboardResource[] {
+  if (application.type !== 'studio') return []
+  const url = getApplicationOrigin(application) ?? ''
+  return (application.activeDeployment?.workspaces ?? []).map((workspace) => ({
+    id: workspace.id,
+    name: workspace.name,
+    title: workspace.title ?? application.title,
+    basePath: workspace.basePath ?? '',
+    projectId: workspace.projectId,
+    dataset: workspace.dataset,
+    type: 'studio',
+    userApplicationId: application.id,
+    url,
+  }))
+}
+
+function toWorkspaceMap(applications: DashboardApplications): WorkspacesByProjectIdDataset {
+  const workspaceMap: WorkspacesByProjectIdDataset = {}
+  for (const resource of applications.flatMap(toResources)) {
+    const key = `${resource.projectId}:${resource.dataset}` as const
+    workspaceMap[key] ??= []
+    workspaceMap[key].push(resource)
+  }
+  return workspaceMap
+}
+
+// Suspends until the host publishes its application list and throws a `TopicError` on failure,
+// like every bus hook, so `error` is always `null` on this path.
+function useBusStudioWorkspaces(): StudioWorkspacesResult {
+  const applications = useTopic('applications.list')
+  const workspacesByProjectIdAndDataset = useMemo(
+    () => toWorkspaceMap(applications ?? []),
+    [applications],
+  )
+  return {workspacesByProjectIdAndDataset, error: null}
+}
+
+function useComlinkStudioWorkspaces(): StudioWorkspacesResult {
   const [workspacesByProjectIdAndDataset, setWorkspacesByProjectIdAndDataset] =
     useState<WorkspacesByProjectIdDataset>({})
   const [error, setError] = useState<string | null>(null)