@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1

package/src/bridge/react/usePlatformAgentSessions.tsx

@@ -0,0 +1,60 @@
+import type {
+  PlatformAgentSessionRecord,
+  PlatformAgentSessionSummary,
+  PlatformCreateAgentSessionRequest,
+  PlatformListAgentSessionsRequest,
+  PlatformReadAgentSessionRequest,
+  PlatformUpdateAgentSessionRequest,
+} from '../agentTypes.js'
+import {
+  createAgentSession,
+  deleteAgentSession,
+  listAgentSessions,
+  readAgentSession,
+  updateAgentSession,
+} from '../agents.mjs'
+import { useIpc, type UseIpcOptions, type UseIpcResult } from './useIpc.js'
+
+export function usePlatformAgentSessionList(
+  request: PlatformListAgentSessionsRequest,
+  options: UseIpcOptions = {},
+): UseIpcResult<PlatformAgentSessionSummary[]> {
+  return useIpc(
+    () => listAgentSessions(request),
+    [request.scope, request.appSlug],
+    options,
+  )
+}
+
+export function usePlatformAgentSession(
+  request: PlatformReadAgentSessionRequest | null,
+  options: UseIpcOptions = {},
+): UseIpcResult<PlatformAgentSessionRecord | null> {
+  const enabled = Boolean(request) && (options.enabled ?? true)
+  return useIpc(
+    async () => {
+      if (!request) return null
+      return readAgentSession(request)
+    },
+    [request?.scope, request?.appSlug, request?.sessionId],
+    { ...options, enabled },
+  )
+}
+
+export async function createPlatformAgentSession(
+  request: PlatformCreateAgentSessionRequest,
+): Promise<PlatformAgentSessionRecord> {
+  return createAgentSession(request)
+}
+
+export async function updatePlatformAgentSession(
+  request: PlatformUpdateAgentSessionRequest,
+): Promise<PlatformAgentSessionRecord> {
+  return updateAgentSession(request)
+}
+
+export async function deletePlatformAgentSession(
+  request: PlatformReadAgentSessionRequest,
+): Promise<void> {
+  return deleteAgentSession(request)
+}

package/src/bridge/react/usePlatformAgentTools.tsx

@@ -0,0 +1,82 @@
+import { useEffect, useRef } from 'react'
+import { onAgentToolInvoke, registerAgentTools } from '../agents.mjs'
+
+export interface AgentToolInvokeContext {
+  toolCallId: string
+  shortName: string
+  arguments: Record<string, unknown>
+}
+
+export interface AgentToolHandlerResult {
+  content: string
+  isError?: boolean
+}
+
+export type AgentToolHandler = (
+  ctx: AgentToolInvokeContext,
+) => Promise<AgentToolHandlerResult>
+
+export interface UsePlatformAgentToolsOptions {
+  ready: boolean
+  tools: readonly string[]
+  handlers: Record<string, AgentToolHandler>
+  logLabel?: string
+  /** When set, instanceof checks map domain errors to message text. */
+  errorType?: new (message: string) => Error
+}
+
+export function usePlatformAgentTools({
+  ready,
+  tools,
+  handlers,
+  logLabel = 'app',
+  errorType,
+}: UsePlatformAgentToolsOptions): void {
+  const handlersRef = useRef(handlers)
+  handlersRef.current = handlers
+
+  useEffect(() => {
+    if (!ready) return
+
+    void registerAgentTools({ tools: [...tools] }).catch(error => {
+      console.error(`[${logLabel}] agents.tools.register failed`, error)
+    })
+
+    return onAgentToolInvoke(async payload => {
+      try {
+        const handler = handlersRef.current[payload.shortName]
+        if (!handler) {
+          return {
+            toolCallId: payload.toolCallId,
+            content: `Unknown tool "${payload.shortName}"`,
+            isError: true,
+          }
+        }
+
+        const result = await handler({
+          toolCallId: payload.toolCallId,
+          shortName: payload.shortName,
+          arguments: payload.arguments,
+        })
+
+        return {
+          toolCallId: payload.toolCallId,
+          content: result.content,
+          isError: result.isError,
+        }
+      } catch (error) {
+        const message =
+          errorType && error instanceof errorType
+            ? error.message
+            : error instanceof Error
+            ? error.message
+            : String(error)
+        return {
+          toolCallId: payload.toolCallId,
+          content: message,
+          isError: true,
+        }
+      }
+    })
+  }, [errorType, logLabel, ready, tools])
+}

package/src/bridge/react/usePlatformAppManifest.tsx

@@ -0,0 +1,32 @@
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
+import type { PlatformAppManifest, PlatformShellManifest } from '../types.js'
+import { useIpc } from './useIpc.js'
+
+export interface UsePlatformAppManifestResult {
+  manifest: PlatformAppManifest | null
+  loading: boolean
+  error: Error | null
+}
+
+/**
+ * Fetches the shell catalog manifest and returns the `PlatformAppManifest`
+ * for the current app (matched by `appSlug`).
+ */
+export function usePlatformAppManifest(
+  appSlug: string | null,
+  ready: boolean,
+): UsePlatformAppManifestResult {
+  const { data, loading, error } = useIpc(
+    () =>
+      bridge.call<PlatformShellManifest>(
+        PLATFORM_BRIDGE_METHODS.CATALOG_MANIFEST,
+      ),
+    [],
+    { enabled: ready && appSlug !== null },
+  )
+
+  const manifest = data?.apps.find(app => app.slug === appSlug) ?? null
+
+  return { manifest, loading, error }
+}

package/src/bridge/react/usePlatformBridge.tsx

@@ -0,0 +1,56 @@
+import { useEffect, useState } from 'react'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
+import type { PlatformBridgeReadyMeta } from '../types.js'
+
+export interface UsePlatformBridgeResult {
+  bridge: typeof bridge
+  meta: PlatformBridgeReadyMeta | null
+  error: Error | null
+  ready: boolean
+}
+
+export function usePlatformBridge(): UsePlatformBridgeResult {
+  const [meta, setMeta] = useState<PlatformBridgeReadyMeta | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    bridge
+      .waitForReady()
+      .then(result => {
+        if (!cancelled) setMeta(result)
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)))
+        }
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  // Cmd/Ctrl-K belongs to the shell's universal jump palette, but key
+  // events land in whichever iframe has focus — forward them up.
+  useEffect(() => {
+    if (window.parent === window) return undefined
+    const onKey = (event: KeyboardEvent): void => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+        event.preventDefault()
+        void bridge
+          .call(PLATFORM_BRIDGE_METHODS.WORKSPACE_OPEN_PALETTE, [])
+          .catch(() => undefined)
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [])
+
+  return {
+    bridge,
+    meta,
+    error,
+    ready: meta !== null,
+  }
+}

package/src/bridge/react/usePlatformDeepLink.tsx

@@ -0,0 +1,57 @@
+import { useEffect, useRef } from 'react'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from '../events.mjs'
+import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
+
+/**
+ * Consume deep links sent via `workspace.openApp({appSlug, resourceId})`.
+ * The shell delivers them as resource events with the pseudo-path
+ * `purescience://<appSlug>/<resourceId>`; this hook matches this app's
+ * slug and hands the resource id to the callback. Subscribe-on-mount so
+ * cold-launch deliveries are not missed.
+ */
+export function usePlatformDeepLink(
+  appSlug: string,
+  onOpen: (resourceId: string) => void,
+): void {
+  const onOpenRef = useRef(onOpen)
+  onOpenRef.current = onOpen
+
+  useEffect(() => {
+    const prefix = `purescience://${appSlug}/`
+    const handlePath = (path: string): void => {
+      if (path.startsWith(prefix)) {
+        const resourceId = path.slice(prefix.length)
+        if (resourceId) onOpenRef.current(resourceId)
+      }
+    }
+
+    const unsubscribe = bridge.onEvent(
+      PLATFORM_BRIDGE_EVENTS.RESOURCE_OPEN,
+      payload => {
+        handlePath((payload as { path?: string } | null)?.path ?? '')
+      },
+    )
+
+    // Cold launches: the live event can be posted before this app
+    // subscribed, so the shell keeps the intent pending — collect it.
+    let cancelled = false
+    void bridge
+      .waitForReady()
+      .then(() =>
+        bridge.call<{ resource?: { path?: string } | null }>(
+          PLATFORM_BRIDGE_METHODS.CATALOG_CONSUME_PENDING_OPEN,
+          [],
+        ),
+      )
+      .then(result => {
+        if (!cancelled) handlePath(result?.resource?.path ?? '')
+      })
+      .catch(() => undefined)
+
+    return () => {
+      cancelled = true
+      unsubscribe()
+    }
+  }, [appSlug])
+}

package/src/bridge/react/usePlatformFileBinaryDataUrl.tsx

@@ -0,0 +1,54 @@
+import { useEffect, useState } from 'react'
+import { readPlatformFileBinaryDataUrl } from '../fs.mjs'
+
+export interface UsePlatformFileBinaryDataUrlResult {
+  src: string | null
+  loading: boolean
+  error: string | null
+}
+
+/** React binding for {@link readPlatformFileBinaryDataUrl}. */
+export function usePlatformFileBinaryDataUrl(
+  path: string | null,
+  enabled: boolean,
+  maxBytes?: number,
+): UsePlatformFileBinaryDataUrlResult {
+  const [src, setSrc] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!enabled || !path?.trim()) {
+      setSrc(null)
+      setLoading(false)
+      setError(null)
+      return
+    }
+
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+    setSrc(null)
+
+    void readPlatformFileBinaryDataUrl(path, maxBytes)
+      .then(dataUrl => {
+        if (cancelled) return
+        setSrc(dataUrl)
+      })
+      .catch(cause => {
+        if (cancelled) return
+        setError(
+          cause instanceof Error ? cause.message : 'Failed to load preview.',
+        )
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [enabled, maxBytes, path])
+
+  return { src, loading, error }
+}

package/src/bridge/react/usePlatformFilePreview.tsx

@@ -0,0 +1,92 @@
+import { useEffect, useState } from 'react'
+import {
+  PLATFORM_FILE_TEXT_PREVIEW_MAX_BYTES,
+  readPlatformFilePreview,
+  readPlatformFilePreviewUrl,
+} from '../fs.mjs'
+import type { PlatformFilePreviewEntry } from '../types.js'
+import {
+  previewKindForEntry,
+  shouldFetchPreviewUrl,
+  shouldFetchTextPreview,
+  type FilePreviewKind,
+} from '../filePreviewKind.js'
+
+export interface UsePlatformFilePreviewResult {
+  previewKind: FilePreviewKind | null
+  textContent: string | null
+  textTruncated: boolean
+  mediaUrl: string | null
+  loading: boolean
+  error: string | null
+}
+
+/** Load inline file preview via shell bridge (text + streamed media URLs). */
+export function usePlatformFilePreview(
+  entry: PlatformFilePreviewEntry | null,
+): UsePlatformFilePreviewResult {
+  const [textContent, setTextContent] = useState<string | null>(null)
+  const [textTruncated, setTextTruncated] = useState(false)
+  const [mediaUrl, setMediaUrl] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const previewKind = entry ? previewKindForEntry(entry) : null
+
+  useEffect(() => {
+    let cancelled = false
+
+    setTextContent(null)
+    setTextTruncated(false)
+    setMediaUrl(null)
+    setError(null)
+
+    if (!entry || entry.isDirectory) return
+
+    const fetchText = shouldFetchTextPreview(entry)
+    const fetchMedia = shouldFetchPreviewUrl(entry)
+    if (!fetchText && !fetchMedia) return
+
+    setLoading(true)
+
+    void (async () => {
+      try {
+        if (fetchText) {
+          const result = await readPlatformFilePreview(
+            entry.path,
+            PLATFORM_FILE_TEXT_PREVIEW_MAX_BYTES,
+          )
+          if (cancelled) return
+          setTextContent(result.content)
+          setTextTruncated(result.truncated)
+        }
+
+        if (fetchMedia) {
+          const result = await readPlatformFilePreviewUrl(entry.path)
+          if (cancelled) return
+          setMediaUrl(result.url)
+        }
+      } catch (err) {
+        if (cancelled) return
+        setTextContent(null)
+        setMediaUrl(null)
+        setError(err instanceof Error ? err.message : String(err))
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    })()
+
+    return () => {
+      cancelled = true
+    }
+  }, [entry])
+
+  return {
+    previewKind,
+    textContent,
+    textTruncated,
+    mediaUrl,
+    loading,
+    error,
+  }
+}

package/src/bridge/react/usePlatformPreferences.tsx

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useState } from 'react'
+import {
+  getPlatformPreferences,
+  patchPlatformPreferences,
+} from '../preferences.mjs'
+import type { PlatformShellPreferences } from '../types.js'
+
+export interface UsePlatformPreferencesOptions {
+  /** Wait for bridge ready before loading (default true). */
+  enabled?: boolean
+}
+
+export interface UsePlatformPreferencesResult {
+  prefs: PlatformShellPreferences | null
+  loading: boolean
+  error: Error | null
+  /** Merge a partial patch via shell `settings.prefs.set`. */
+  updatePrefs: (
+    patch: Partial<PlatformShellPreferences>,
+  ) => Promise<PlatformShellPreferences>
+  reload: () => void
+}
+
+/**
+ * Load and update shell preferences from a plugin iframe (`settings.prefs.*`).
+ * Host renderer should use shell IPC helpers instead of this hook.
+ */
+export function usePlatformPreferences(
+  options: UsePlatformPreferencesOptions = {},
+): UsePlatformPreferencesResult {
+  const enabled = options.enabled ?? true
+  const [prefs, setPrefs] = useState<PlatformShellPreferences | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [reloadToken, setReloadToken] = useState(0)
+
+  const reload = useCallback(() => {
+    setReloadToken(token => token + 1)
+  }, [])
+
+  useEffect(() => {
+    if (!enabled) return
+
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+
+    void getPlatformPreferences()
+      .then(next => {
+        if (!cancelled) setPrefs(next)
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          setPrefs(null)
+          setError(err instanceof Error ? err : new Error(String(err)))
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [enabled, reloadToken])
+
+  const updatePrefs = useCallback(
+    async (patch: Partial<PlatformShellPreferences>) => {
+      const next = await patchPlatformPreferences(patch)
+      setPrefs(next)
+      return next
+    },
+    [],
+  )
+
+  return { prefs, loading, error, updatePrefs, reload }
+}

package/src/bridge/react/usePlatformThemeDocumentAttrs.ts

@@ -0,0 +1,35 @@
+import { useEffect, useState } from 'react'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from '../events.mjs'
+
+export interface PlatformThemeDocumentAttrs {
+  mode: string
+  surfacePalette: string
+}
+
+function readThemeDocumentAttrs(): PlatformThemeDocumentAttrs {
+  const root = document.documentElement
+  return {
+    mode: root.dataset.platformTheme ?? '',
+    surfacePalette: root.dataset.platformSurfacePalette ?? '',
+  }
+}
+
+/** Mirror shell-injected `data-platform-*` attrs for AppFrame styled selectors. */
+export function usePlatformThemeDocumentAttrs(
+  enabled = true,
+): PlatformThemeDocumentAttrs {
+  const [attrs, setAttrs] = useState<PlatformThemeDocumentAttrs>(() =>
+    enabled ? readThemeDocumentAttrs() : { mode: '', surfacePalette: '' },
+  )
+
+  useEffect(() => {
+    if (!enabled) return
+    setAttrs(readThemeDocumentAttrs())
+    return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.THEME_CHANGED, () => {
+      setAttrs(readThemeDocumentAttrs())
+    })
+  }, [enabled])
+
+  return attrs
+}

package/src/bridge/react/usePlatformThemeFromBridge.tsx

@@ -0,0 +1,16 @@
+import { useEffect } from 'react'
+import { applyThemeFromHost } from '../applyThemeFromHost.mjs'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from '../events.mjs'
+import type { PlatformThemeBridgePayload } from '../types.js'
+
+/** Subscribe to shell theme updates in a plugin iframe (cross-origin safe). */
+export function usePlatformThemeFromBridge(enabled = true): void {
+  useEffect(() => {
+    if (!enabled) return
+
+    return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.THEME_CHANGED, payload => {
+      applyThemeFromHost(payload as PlatformThemeBridgePayload)
+    })
+  }, [enabled])
+}

package/src/bridge/react/usePlatformViewportResource.test.tsx

@@ -0,0 +1,106 @@
+import React, { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
+import type { PlatformBridgeReadyMeta, ResourceOpenEvent } from '../types.js'
+import { usePlatformViewportResource } from './usePlatformViewportResource.js'
+
+const reactActGlobal = globalThis as typeof globalThis & {
+  IS_REACT_ACT_ENVIRONMENT?: boolean
+}
+reactActGlobal.IS_REACT_ACT_ENVIRONMENT = true
+
+const originalCall = bridge.call
+const originalOnEvent = bridge.onEvent
+
+function renderProbe(
+  meta: PlatformBridgeReadyMeta,
+  onResource: (resource: ResourceOpenEvent | null) => void,
+): Root {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+
+  function Probe(): React.ReactElement {
+    const { resource } = usePlatformViewportResource(true, meta)
+    onResource(resource)
+    return <div />
+  }
+
+  act(() => {
+    root.render(<Probe />)
+  })
+
+  return root
+}
+
+describe('usePlatformViewportResource', () => {
+  afterEach(() => {
+    bridge.call = originalCall
+    bridge.onEvent = originalOnEvent
+    document.body.innerHTML = ''
+    vi.restoreAllMocks()
+  })
+
+  it('uses the bridge-ready viewport resource', async () => {
+    bridge.call = vi.fn()
+    bridge.onEvent = vi.fn(() => () => undefined)
+    const resources: Array<ResourceOpenEvent | null> = []
+    const resource = {
+      path: '/tmp/example.slides',
+      name: 'Example',
+      kind: 'folder',
+    } satisfies ResourceOpenEvent
+
+    const root = renderProbe(
+      {
+        version: 1,
+        pluginId: 'pureslides2',
+        appSlug: 'slides2',
+        methods: [],
+        viewport: { tabId: 'tab-1', resource },
+      },
+      next => resources.push(next),
+    )
+
+    await act(async () => undefined)
+
+    expect(resources.at(-1)).toEqual(resource)
+    expect(bridge.call).not.toHaveBeenCalled()
+    act(() => root.unmount())
+  })
+
+  it('consumes a per-tab pending open when ready metadata has no resource', async () => {
+    const resource = {
+      path: '/tmp/reopened.slides',
+      name: 'Reopened',
+      kind: 'folder',
+      sourceAppSlug: 'slides2',
+    } satisfies ResourceOpenEvent
+    bridge.call = vi.fn(async (method: string) => {
+      expect(method).toBe(PLATFORM_BRIDGE_METHODS.CATALOG_CONSUME_PENDING_OPEN)
+      return { resource }
+    }) as typeof bridge.call
+    bridge.onEvent = vi.fn(() => () => undefined)
+    const resources: Array<ResourceOpenEvent | null> = []
+
+    const root = renderProbe(
+      {
+        version: 1,
+        pluginId: 'pureslides2',
+        appSlug: 'slides2',
+        methods: [],
+        viewport: { tabId: 'tab-2', resource: null },
+      },
+      next => resources.push(next),
+    )
+
+    await act(async () => {
+      await Promise.resolve()
+    })
+
+    expect(resources.at(-1)).toEqual(resource)
+    act(() => root.unmount())
+  })
+})