@puredesktop/puredesktop-ui-bridge 2.1.8 → 2.1.9

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

@@ -1,152 +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'] })
-  })
-})
+// @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

@@ -1,149 +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,
-  }
-}
+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 }
+}