@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.9

package/src/bridge/react/usePlatformAppSettings.tsx

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useState } from 'react'
+import {
+  getPlatformAppSettings,
+  updatePlatformAppSettings,
+} from '../appSettings.mjs'
+
+export interface UsePlatformAppSettingsOptions<
+  TSettings extends Record<string, unknown> = Record<string, unknown>,
+> {
+  appSlug: string | null
+  /** Wait for bridge ready before loading (default: true when appSlug exists). */
+  enabled?: boolean
+  /** Normalize stored settings into the app-owned settings shape. */
+  parse?: (value: Record<string, unknown>) => TSettings
+  initialSettings?: TSettings
+}
+
+export interface UsePlatformAppSettingsResult<
+  TSettings extends Record<string, unknown> = Record<string, unknown>,
+> {
+  settings: TSettings
+  loading: boolean
+  error: Error | null
+  /** Shallow-merge a patch through shell `settings.app.update`. */
+  patchSettings: (patch: Record<string, unknown>) => Promise<TSettings>
+  reload: () => void
+}
+
+function defaultParse<TSettings extends Record<string, unknown>>(
+  value: Record<string, unknown>,
+): TSettings {
+  return value as TSettings
+}
+
+/**
+ * Load and update the current app's settings through `settings.app.*`.
+ * App settings are small per-app preferences, not user-visible documents.
+ */
+export function usePlatformAppSettings<
+  TSettings extends Record<string, unknown> = Record<string, unknown>,
+>({
+  appSlug,
+  enabled = Boolean(appSlug),
+  parse = defaultParse<TSettings>,
+  initialSettings = {} as TSettings,
+}: UsePlatformAppSettingsOptions<TSettings>): UsePlatformAppSettingsResult<TSettings> {
+  const [settings, setSettings] = useState<TSettings>(initialSettings)
+  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 || !appSlug) return
+
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+
+    void getPlatformAppSettings(appSlug)
+      .then(raw => {
+        if (!cancelled) setSettings(parse(raw))
+      })
+      .catch((cause: unknown) => {
+        if (!cancelled) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)))
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [appSlug, enabled, parse, reloadToken])
+
+  const patchSettings = useCallback(
+    async (patch: Record<string, unknown>): Promise<TSettings> => {
+      if (!appSlug) throw new Error('appSlug is required to update app settings')
+      try {
+        const next = parse(
+          await updatePlatformAppSettings({
+            appSlug,
+            patch,
+          }),
+        )
+        setSettings(next)
+        setError(null)
+        return next
+      } catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause))
+        setError(error)
+        throw error
+      }
+    },
+    [appSlug, parse],
+  )
+
+  return { settings, loading, error, patchSettings, reload }
+}

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

@@ -0,0 +1,152 @@
+// @vitest-environment happy-dom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+import { usePlatformJsonStore } from './usePlatformJsonStore.js'
+
+type ReactActGlobal = typeof globalThis & {
+  IS_REACT_ACT_ENVIRONMENT?: boolean
+}
+
+interface Store {
+  items: string[]
+}
+
+const storageMock = vi.hoisted(() => ({
+  readPlatformStorageJson: vi.fn(),
+  writePlatformStorageJson: vi.fn(),
+}))
+
+vi.mock('../storage.mjs', () => storageMock)
+
+let latest: ReturnType<typeof usePlatformJsonStore<Store>> | null = null
+
+const EMPTY_STORE: Store = { items: [] }
+
+function parseStore(value: unknown): Store {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return EMPTY_STORE
+  }
+  const record = value as Record<string, unknown>
+  return {
+    items: Array.isArray(record.items)
+      ? record.items.filter((item): item is string => typeof item === 'string')
+      : [],
+  }
+}
+
+function Probe(): React.ReactElement {
+  latest = usePlatformJsonStore<Store>({
+    appSlug: 'tasks',
+    fileName: 'tasks-items.json',
+    initialValue: EMPTY_STORE,
+    parse: parseStore,
+  })
+  return <div />
+}
+
+async function flushEffects(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+}
+
+describe('usePlatformJsonStore', () => {
+  let host: HTMLDivElement
+  let root: Root
+
+  beforeAll(() => {
+    ;(globalThis as ReactActGlobal).IS_REACT_ACT_ENVIRONMENT = true
+  })
+
+  beforeEach(() => {
+    latest = null
+    host = document.createElement('div')
+    document.body.appendChild(host)
+    root = createRoot(host)
+    storageMock.readPlatformStorageJson.mockResolvedValue({
+      path: '/data/tasks-items.json',
+      value: { items: ['one', 2, 'two'] },
+    })
+    storageMock.writePlatformStorageJson.mockResolvedValue({
+      path: '/data/tasks-items.json',
+      ok: true,
+    })
+  })
+
+  afterEach(() => {
+    act(() => root.unmount())
+    host.remove()
+    vi.clearAllMocks()
+  })
+
+  it('loads and normalizes a JSON store file', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    expect(storageMock.readPlatformStorageJson).toHaveBeenCalledWith({
+      appSlug: 'tasks',
+      fileName: 'tasks-items.json',
+    })
+    expect(latest?.value).toEqual({ items: ['one', 'two'] })
+    expect(latest?.path).toBe('/data/tasks-items.json')
+  })
+
+  it('saves the complete next JSON store value', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    await act(async () => {
+      await latest?.saveValue({ items: ['next'] })
+    })
+
+    expect(storageMock.writePlatformStorageJson).toHaveBeenCalledWith({
+      appSlug: 'tasks',
+      fileName: 'tasks-items.json',
+      value: { items: ['next'] },
+    })
+    expect(latest?.value).toEqual({ items: ['next'] })
+  })
+
+  it('applies queued updates to the latest saved value', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    await act(async () => {
+      const first = latest?.updateValue(current => ({
+        items: [...current.items, 'three'],
+      }))
+      const second = latest?.updateValue(current => ({
+        items: [...current.items, 'four'],
+      }))
+      await Promise.all([first, second])
+    })
+
+    expect(storageMock.writePlatformStorageJson).toHaveBeenNthCalledWith(1, {
+      appSlug: 'tasks',
+      fileName: 'tasks-items.json',
+      value: { items: ['one', 'two', 'three'] },
+    })
+    expect(storageMock.writePlatformStorageJson).toHaveBeenNthCalledWith(2, {
+      appSlug: 'tasks',
+      fileName: 'tasks-items.json',
+      value: { items: ['one', 'two', 'three', 'four'] },
+    })
+    expect(latest?.value).toEqual({ items: ['one', 'two', 'three', 'four'] })
+  })
+})

package/src/bridge/react/usePlatformJsonStore.tsx

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  readPlatformStorageJson,
+  writePlatformStorageJson,
+} from '../storage.mjs'
+
+export type PlatformJsonStoreFileName = `${string}.json`
+
+export interface UsePlatformJsonStoreOptions<TValue> {
+  appSlug: string | null
+  fileName: PlatformJsonStoreFileName | null
+  /** Default value when the JSON file does not exist yet. */
+  initialValue: TValue
+  /** Wait for bridge ready before loading (default: true when appSlug/fileName exist). */
+  enabled?: boolean
+  /** Normalize parsed JSON into the app-owned store shape. */
+  parse?: (value: unknown) => TValue
+}
+
+export interface UsePlatformJsonStoreResult<TValue> {
+  value: TValue
+  path: string | null
+  loading: boolean
+  saving: boolean
+  error: Error | null
+  saveValue: (next: TValue) => Promise<TValue>
+  updateValue: (updater: (current: TValue) => TValue) => Promise<TValue>
+  reload: () => void
+}
+
+function defaultParse<TValue>(value: unknown): TValue {
+  return value as TValue
+}
+
+/**
+ * Load and replace one shell-managed JSON store file through `storage.*`.
+ * Use this for app-owned internal records, not for user-visible documents.
+ */
+export function usePlatformJsonStore<TValue>({
+  appSlug,
+  fileName,
+  initialValue,
+  enabled = Boolean(appSlug && fileName),
+  parse = defaultParse<TValue>,
+}: UsePlatformJsonStoreOptions<TValue>): UsePlatformJsonStoreResult<TValue> {
+  const [value, setValue] = useState<TValue>(initialValue)
+  const [path, setPath] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [reloadToken, setReloadToken] = useState(0)
+  const valueRef = useRef(value)
+  const writeChainRef = useRef<Promise<TValue>>(Promise.resolve(value))
+  valueRef.current = value
+
+  const reload = useCallback(() => {
+    setReloadToken(token => token + 1)
+  }, [])
+
+  useEffect(() => {
+    if (!enabled || !appSlug || !fileName) return
+
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+
+    void readPlatformStorageJson({ appSlug, fileName })
+      .then(result => {
+        if (cancelled) return
+        const next =
+          result.value === null ? initialValue : parse(result.value)
+        valueRef.current = next
+        setValue(next)
+        setPath(result.path)
+      })
+      .catch((cause: unknown) => {
+        if (!cancelled) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)))
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [appSlug, enabled, fileName, initialValue, parse, reloadToken])
+
+  const queueSave = useCallback(
+    (resolveNext: (current: TValue) => TValue): Promise<TValue> => {
+      if (!appSlug || !fileName) {
+        throw new Error('appSlug and fileName are required to save JSON storage')
+      }
+
+      const write = async (): Promise<TValue> => {
+        const next = resolveNext(valueRef.current)
+        setSaving(true)
+        try {
+          const result = await writePlatformStorageJson({
+            appSlug,
+            fileName,
+            value: next,
+          })
+          valueRef.current = next
+          setValue(next)
+          setPath(result.path)
+          setError(null)
+          return next
+        } catch (cause) {
+          const error =
+            cause instanceof Error ? cause : new Error(String(cause))
+          setError(error)
+          throw error
+        } finally {
+          setSaving(false)
+        }
+      }
+
+      const queued = writeChainRef.current.then(write, write)
+      writeChainRef.current = queued.catch(() => valueRef.current)
+      return queued
+    },
+    [appSlug, fileName],
+  )
+
+  const saveValue = useCallback(
+    (next: TValue): Promise<TValue> => queueSave(() => next),
+    [queueSave],
+  )
+
+  const updateValue = useCallback(
+    (updater: (current: TValue) => TValue): Promise<TValue> => {
+      return queueSave(updater)
+    },
+    [queueSave],
+  )
+
+  return {
+    value,
+    path,
+    loading,
+    saving,
+    error,
+    saveValue,
+    updateValue,
+    reload,
+  }
+}

package/src/bridge/react/usePlatformOperations.tsx

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  listPlatformOperations,
+  onPlatformOperationRecorded,
+} from '../operations.mjs'
+import type {
+  PlatformOperation,
+  PlatformOperationsListQuery,
+} from '../operations.d.mts'
+
+export interface UsePlatformOperationsResult {
+  /** Newest first; live — appends arrive via the operations.changed event. */
+  operations: PlatformOperation[]
+  /** True until the first list round-trip settles. */
+  loading: boolean
+  /** Re-fetch from the shell (the live stream normally makes this unnecessary). */
+  refresh: () => Promise<void>
+}
+
+/**
+ * The suite-wide operations feed for app UIs: one initial list, then live
+ * appends. Pass `lane` to follow a single lane ('user' | 'agent'); omit for
+ * both. Outside the desktop iframe (standalone dev) it settles to an empty
+ * feed instead of throwing.
+ */
+export function usePlatformOperations(
+  query: PlatformOperationsListQuery = {},
+): UsePlatformOperationsResult {
+  const [operations, setOperations] = useState<PlatformOperation[]>([])
+  const [loading, setLoading] = useState(true)
+  const laneRef = useRef(query.lane)
+  laneRef.current = query.lane
+  const limitRef = useRef(query.limit)
+  limitRef.current = query.limit
+
+  const refresh = useCallback(async (): Promise<void> => {
+    try {
+      const result = await listPlatformOperations({
+        ...(laneRef.current ? { lane: laneRef.current } : {}),
+        ...(limitRef.current !== undefined ? { limit: limitRef.current } : {}),
+      })
+      setOperations(result.operations)
+    } catch {
+      // Standalone dev / bridge unavailable: an empty feed, not a crash.
+      setOperations([])
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh, query.lane, query.limit])
+
+  useEffect(() => {
+    let unsubscribe: (() => void) | undefined
+    try {
+      unsubscribe = onPlatformOperationRecorded(operation => {
+        if (laneRef.current && operation.lane !== laneRef.current) return
+        setOperations(current => {
+          const next = [operation, ...current]
+          const limit = limitRef.current
+          return typeof limit === 'number' && limit >= 0
+            ? next.slice(0, limit)
+            : next
+        })
+      })
+    } catch {
+      // No bridge (standalone dev) — the initial refresh already settled.
+    }
+    return () => unsubscribe?.()
+  }, [])
+
+  return { operations, loading, refresh }
+}

package/src/bridge/storage.d.mts

@@ -1,24 +1,37 @@
-export type PlatformStorageJsonFileName = `${string}.json`
-
-export interface PlatformStorageJsonRequest {
-  appSlug: string
-  fileName: PlatformStorageJsonFileName
-}
+export type PlatformStorageJsonFileName = `${string}.json`
+
+export interface PlatformStorageJsonRequest {
+  appSlug: string
+  fileName: PlatformStorageJsonFileName
+}
 
 export interface PlatformStorageJsonReadResult {
   path: string
   value: unknown | null
+  /** Content hash for optimistic concurrency (null when the file is absent). */
+  version: string | null
 }
 
 export interface PlatformStorageJsonWriteRequest
   extends PlatformStorageJsonRequest {
   value: unknown
+  /**
+   * The version this write was derived from (null = file must not exist).
+   * Omit for an unconditional write. On mismatch nothing is written and the
+   * result carries conflict: true — re-read, re-apply, retry.
+   */
+  ifMatch?: string | null
 }
 
-export interface PlatformStorageJsonWriteResult {
-  path: string
-  ok: true
-}
+export type PlatformStorageJsonWriteResult =
+  | { path: string; ok: true; version: string }
+  | {
+      path: string
+      ok: false
+      conflict: true
+      value: unknown | null
+      version: string | null
+    }
 
 export declare function readPlatformStorageJson(
   request: PlatformStorageJsonRequest,

package/src/bridge/storage.mjs

@@ -3,15 +3,18 @@ import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
 
 /**
  * @param {{ appSlug: string, fileName: string }} request
- * @returns {Promise<{ path: string, value: unknown | null }>}
+ * @returns {Promise<{ path: string, value: unknown | null, version: string | null }>}
  */
 export async function readPlatformStorageJson(request) {
   return bridge.call(PLATFORM_BRIDGE_METHODS.STORAGE_READ_JSON, [request])
 }
 
 /**
- * @param {{ appSlug: string, fileName: string, value: unknown }} request
- * @returns {Promise<{ path: string, ok: true }>}
+ * Optional `ifMatch` (version from readPlatformStorageJson) makes the write
+ * conditional: on conflict nothing is written and the result has
+ * `conflict: true` with the current value — re-read, re-apply, retry.
+ * @param {{ appSlug: string, fileName: string, value: unknown, ifMatch?: string | null }} request
+ * @returns {Promise<{ path: string, ok: boolean, version: string | null, conflict?: true, value?: unknown | null }>}
  */
 export async function writePlatformStorageJson(request) {
   return bridge.call(PLATFORM_BRIDGE_METHODS.STORAGE_WRITE_JSON, [request])

package/src/bridge/storage.test.ts

@@ -20,7 +20,7 @@ beforeEach(() => {
 
 describe('storage bridge helpers', () => {
   it('reads JSON storage using the shell request object shape', async () => {
-    const request = { appSlug: 'puretasks', fileName: 'tasks.json' } as const
+    const request = { appSlug: 'puretasks', fileName: 'tasks.json' } as const
     bridgeCall.mockResolvedValue({ path: '/tmp/tasks.json', value: null })
 
     await readPlatformStorageJson(request)
@@ -32,11 +32,11 @@ describe('storage bridge helpers', () => {
   })
 
   it('writes JSON storage using the shell request object shape', async () => {
-    const request = {
-      appSlug: 'puretasks',
-      fileName: 'tasks.json',
-      value: { tasks: [] },
-    } as const
+    const request = {
+      appSlug: 'puretasks',
+      fileName: 'tasks.json',
+      value: { tasks: [] },
+    } as const
     bridgeCall.mockResolvedValue({ path: '/tmp/tasks.json', ok: true })
 
     await writePlatformStorageJson(request)

package/src/bridge/types.ts

@@ -2,6 +2,7 @@ export type PlatformBridgeEventName =
   import('./events.mjs').PlatformBridgeEventName
 
 import type { PlatformThemeMode } from '../theme/tokens.js'
+import type { PlatformAppContextManifest } from '../context/contextConfig.js'
 
 /** Shell prefs exposed via `settings.prefs.get` / `settings.prefs.set`. */
 export type PlatformThemePreference = PlatformThemeMode
@@ -80,6 +81,8 @@ export interface PlatformAppManifest {
   productName: string
   kind: string
   description: string
+  /** Declarative context-file config for this app's package objects. */
+  context?: PlatformAppContextManifest
   peopleProviders?: Array<{
     id: string
     label: string
@@ -205,6 +208,10 @@ export interface RenderPagedSnapshotMetrics {
   captionVisible?: boolean
   captionOrphaned?: boolean
   strandedHeading?: boolean | null
+  /** Blocks on the target page that collide with each other. */
+  overlappingBlocks?: number
+  /** Blocks escaping the page content box. */
+  overflowingBlocks?: number
 }
 
 export interface RenderPagedPreviewResult {

package/src/components/agents/AgentComposer.tsx

@@ -20,6 +20,7 @@ export interface AgentComposerProps {
   leading?: React.ReactNode
   followUps?: AgentUiFollowUp[]
   questionToolCalls?: AgentUiToolCall[]
+  questionPromptList?: React.ReactNode
   usage?: AgentUiRunUsage | null
   liveTurn?: AgentLiveTurn | null
   onChange: (value: string) => void
@@ -76,6 +77,7 @@ export function AgentComposer({
   leading,
   followUps = [],
   questionToolCalls = [],
+  questionPromptList = null,
   usage = null,
   liveTurn = null,
   onChange,
@@ -89,7 +91,7 @@ export function AgentComposer({
   const showUsage =
     liveTurn?.contextCompaction === 'summarizing' ||
     Boolean(usage && (usage.totalTokens > 0 || usage.contextFillTokens))
-  const hasQuestions = questionToolCalls.length > 0
+  const hasQuestions = questionPromptList !== null || questionToolCalls.length > 0
 
   return (
     <StyledRoot>
@@ -105,11 +107,13 @@ export function AgentComposer({
         preserveChildrenOnExit
         aria-hidden={!hasQuestions}
       >
-        <AgentQuestionPromptList
-          toolCalls={questionToolCalls}
-          onAnswer={onAnswerQuestionTool}
-          onDecline={onDeclineQuestionTool}
-        />
+        {questionPromptList ?? (
+          <AgentQuestionPromptList
+            toolCalls={questionToolCalls}
+            onAnswer={onAnswerQuestionTool}
+            onDecline={onDeclineQuestionTool}
+          />
+        )}
       </StyledQuestionPresence>
       <StyledComposerSurfaceAnchor>
         {showUsage ? (