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

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

@@ -1,106 +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())
-  })
-})
+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: 'pureslides',
+        appSlug: 'slides',
+        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: 'slides',
+    } 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: 'pureslides',
+        appSlug: 'slides',
+        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())
+  })
+})

package/src/bridge/react/usePlatformViewportResource.tsx

@@ -1,72 +1,72 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
-import { bridge } from '../client.mjs'
-import { PLATFORM_BRIDGE_EVENTS } from '../events.mjs'
-import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
-import type { PlatformBridgeReadyMeta, ResourceOpenEvent } from '../types.js'
-
-function isResourceOpenEvent(value: unknown): value is ResourceOpenEvent {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    typeof (value as ResourceOpenEvent).path === 'string' &&
-    (value as ResourceOpenEvent).path.trim().length > 0
-  )
-}
-
-export interface UsePlatformViewportResourceResult {
-  /** Latest resource for this viewport (boot binding or warm `resource.open`). */
-  resource: ResourceOpenEvent | null
-  /** Clears `resource` after the app has applied it (avoids re-open loops). */
-  clearResource: () => void
-}
-
-/**
- * Per-tab resource binding from the shell workspace.
- * Prefer `meta.viewport.resource` on bridge ready; also listens for `resource.open`.
- */
-export function usePlatformViewportResource(
-  ready: boolean,
-  meta: PlatformBridgeReadyMeta | null,
-): UsePlatformViewportResourceResult {
-  const [resource, setResource] = useState<ResourceOpenEvent | null>(null)
-  const bootTabIdRef = useRef<string | null>(null)
-
-  useEffect(() => {
-    return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.RESOURCE_OPEN, payload => {
-      if (!isResourceOpenEvent(payload)) return
-      setResource(payload)
-    })
-  }, [])
-
-  useEffect(() => {
-    if (!ready || !meta?.viewport) return
-    if (bootTabIdRef.current === meta.viewport.tabId) return
-    bootTabIdRef.current = meta.viewport.tabId
-    if (meta.viewport.resource) {
-      setResource(meta.viewport.resource)
-      return
-    }
-
-    let cancelled = false
-    bridge
-      .call<{ resource?: ResourceOpenEvent | null }>(
-        PLATFORM_BRIDGE_METHODS.CATALOG_CONSUME_PENDING_OPEN,
-        [],
-      )
-      .then(result => {
-        if (cancelled || !isResourceOpenEvent(result?.resource)) return
-        setResource(result.resource)
-      })
-      .catch(() => undefined)
-
-    return () => {
-      cancelled = true
-    }
-  }, [meta, ready])
-
-  const clearResource = useCallback(() => {
-    setResource(null)
-  }, [])
-
-  return { resource, clearResource }
-}
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from '../events.mjs'
+import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
+import type { PlatformBridgeReadyMeta, ResourceOpenEvent } from '../types.js'
+
+function isResourceOpenEvent(value: unknown): value is ResourceOpenEvent {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as ResourceOpenEvent).path === 'string' &&
+    (value as ResourceOpenEvent).path.trim().length > 0
+  )
+}
+
+export interface UsePlatformViewportResourceResult {
+  /** Latest resource for this viewport (boot binding or warm `resource.open`). */
+  resource: ResourceOpenEvent | null
+  /** Clears `resource` after the app has applied it (avoids re-open loops). */
+  clearResource: () => void
+}
+
+/**
+ * Per-tab resource binding from the shell workspace.
+ * Prefer `meta.viewport.resource` on bridge ready; also listens for `resource.open`.
+ */
+export function usePlatformViewportResource(
+  ready: boolean,
+  meta: PlatformBridgeReadyMeta | null,
+): UsePlatformViewportResourceResult {
+  const [resource, setResource] = useState<ResourceOpenEvent | null>(null)
+  const bootTabIdRef = useRef<string | null>(null)
+
+  useEffect(() => {
+    return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.RESOURCE_OPEN, payload => {
+      if (!isResourceOpenEvent(payload)) return
+      setResource(payload)
+    })
+  }, [])
+
+  useEffect(() => {
+    if (!ready || !meta?.viewport) return
+    if (bootTabIdRef.current === meta.viewport.tabId) return
+    bootTabIdRef.current = meta.viewport.tabId
+    if (meta.viewport.resource) {
+      setResource(meta.viewport.resource)
+      return
+    }
+
+    let cancelled = false
+    bridge
+      .call<{ resource?: ResourceOpenEvent | null }>(
+        PLATFORM_BRIDGE_METHODS.CATALOG_CONSUME_PENDING_OPEN,
+        [],
+      )
+      .then(result => {
+        if (cancelled || !isResourceOpenEvent(result?.resource)) return
+        setResource(result.resource)
+      })
+      .catch(() => undefined)
+
+    return () => {
+      cancelled = true
+    }
+  }, [meta, ready])
+
+  const clearResource = useCallback(() => {
+    setResource(null)
+  }, [])
+
+  return { resource, clearResource }
+}

package/src/bridge/react/useScheduledTask.tsx

@@ -1,59 +1,59 @@
-import { useEffect, useRef } from 'react'
-import { bridge } from '../client.mjs'
-import { PLATFORM_BRIDGE_EVENTS } from '../events.mjs'
-import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
-
-/**
- * Run `task` every `everyMinutes`, scheduled by the shell
- * (`scheduler.register` + `schedule.fire` events) so all recurring work
- * across the suite is declared in one place. Outside the shell
- * (standalone dev) it falls back to a plain interval. `enabled: false`
- * unregisters.
- */
-export function useScheduledTask(
-  taskName: string,
-  everyMinutes: number,
-  task: () => void,
-  options?: { enabled?: boolean },
-): void {
-  const taskRef = useRef(task)
-  taskRef.current = task
-  const enabled = options?.enabled ?? true
-
-  useEffect(() => {
-    if (!enabled) return undefined
-
-    const standalone = typeof window !== 'undefined' && window.parent === window
-    if (standalone) {
-      const timer = setInterval(
-        () => taskRef.current(),
-        Math.max(1, everyMinutes) * 60_000,
-      )
-      return () => clearInterval(timer)
-    }
-
-    const unsubscribe = bridge.onEvent(
-      PLATFORM_BRIDGE_EVENTS.SCHEDULE_FIRE,
-      payload => {
-        if ((payload as { taskName?: string } | null)?.taskName === taskName) {
-          taskRef.current()
-        }
-      },
-    )
-    void bridge
-      .waitForReady()
-      .then(() =>
-        bridge.call(PLATFORM_BRIDGE_METHODS.SCHEDULER_REGISTER, [
-          { taskName, everyMinutes },
-        ]),
-      )
-      .catch(() => undefined)
-
-    return () => {
-      unsubscribe()
-      void bridge
-        .call(PLATFORM_BRIDGE_METHODS.SCHEDULER_UNREGISTER, [{ taskName }])
-        .catch(() => undefined)
-    }
-  }, [enabled, everyMinutes, taskName])
-}
+import { useEffect, useRef } from 'react'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from '../events.mjs'
+import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
+
+/**
+ * Run `task` every `everyMinutes`, scheduled by the shell
+ * (`scheduler.register` + `schedule.fire` events) so all recurring work
+ * across the suite is declared in one place. Outside the shell
+ * (standalone dev) it falls back to a plain interval. `enabled: false`
+ * unregisters.
+ */
+export function useScheduledTask(
+  taskName: string,
+  everyMinutes: number,
+  task: () => void,
+  options?: { enabled?: boolean },
+): void {
+  const taskRef = useRef(task)
+  taskRef.current = task
+  const enabled = options?.enabled ?? true
+
+  useEffect(() => {
+    if (!enabled) return undefined
+
+    const standalone = typeof window !== 'undefined' && window.parent === window
+    if (standalone) {
+      const timer = setInterval(
+        () => taskRef.current(),
+        Math.max(1, everyMinutes) * 60_000,
+      )
+      return () => clearInterval(timer)
+    }
+
+    const unsubscribe = bridge.onEvent(
+      PLATFORM_BRIDGE_EVENTS.SCHEDULE_FIRE,
+      payload => {
+        if ((payload as { taskName?: string } | null)?.taskName === taskName) {
+          taskRef.current()
+        }
+      },
+    )
+    void bridge
+      .waitForReady()
+      .then(() =>
+        bridge.call(PLATFORM_BRIDGE_METHODS.SCHEDULER_REGISTER, [
+          { taskName, everyMinutes },
+        ]),
+      )
+      .catch(() => undefined)
+
+    return () => {
+      unsubscribe()
+      void bridge
+        .call(PLATFORM_BRIDGE_METHODS.SCHEDULER_UNREGISTER, [{ taskName }])
+        .catch(() => undefined)
+    }
+  }, [enabled, everyMinutes, taskName])
+}

package/src/bridge/render.d.mts

@@ -1,31 +1,31 @@
-import type {
-  PrintPageSize,
-  RenderPagedPreviewRequest,
-  RenderPagedPreviewResult,
-  RenderPagedSnapshotRequest,
-  RenderPagedSnapshotResult,
-  RenderPrintHtmlRequest,
-} from './types.js'
-
-export declare function renderPrintHtml(
-  request: RenderPrintHtmlRequest,
-): Promise<string>
-
-export declare function preparePagedPreview(
-  request: RenderPagedPreviewRequest,
-): Promise<RenderPagedPreviewResult>
-
-export declare function capturePagedSnapshot(
-  request: RenderPagedSnapshotRequest,
-): Promise<RenderPagedSnapshotResult>
-
-export declare function getDefaultPrintStylesheet(
-  pageSize?: PrintPageSize,
-): Promise<string>
-
-/** @returns unsubscribe */
-export declare function onRenderProgress(
-  listener: (event: import('./types.js').RenderProgress) => void,
-): () => void
-
-export declare function renderCancel(): Promise<void>
+import type {
+  PrintPageSize,
+  RenderPagedPreviewRequest,
+  RenderPagedPreviewResult,
+  RenderPagedSnapshotRequest,
+  RenderPagedSnapshotResult,
+  RenderPrintHtmlRequest,
+} from './types.js'
+
+export declare function renderPrintHtml(
+  request: RenderPrintHtmlRequest,
+): Promise<string>
+
+export declare function preparePagedPreview(
+  request: RenderPagedPreviewRequest,
+): Promise<RenderPagedPreviewResult>
+
+export declare function capturePagedSnapshot(
+  request: RenderPagedSnapshotRequest,
+): Promise<RenderPagedSnapshotResult>
+
+export declare function getDefaultPrintStylesheet(
+  pageSize?: PrintPageSize,
+): Promise<string>
+
+/** @returns unsubscribe */
+export declare function onRenderProgress(
+  listener: (event: import('./types.js').RenderProgress) => void,
+): () => void
+
+export declare function renderCancel(): Promise<void>

package/src/bridge/render.mjs

@@ -1,62 +1,62 @@
-import { bridge } from './client.mjs'
-import { PLATFORM_BRIDGE_EVENTS } from './events.mjs'
-import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
-
-/**
- * Print an app-prepared HTML file to PDF (shell: Paged.js + Electron printToPDF).
- * Requires `render` permission in plugin.json.
- *
- * @param {import('./types.js').RenderPrintHtmlRequest} request
- * @returns {Promise<string>} Absolute path to the output PDF
- */
-export async function renderPrintHtml(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_PRINT_HTML, [request])
-}
-
-/**
- * Prepare an app print HTML file for preview (shell: Paged.js pagination).
- * Requires `render` permission in plugin.json.
- *
- * @param {import('./types.js').RenderPagedPreviewRequest} request
- * @returns {Promise<import('./types.js').RenderPagedPreviewResult>}
- */
-export async function preparePagedPreview(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_PREPARE_PAGED_PREVIEW, [
-    request,
-  ])
-}
-
-/**
- * Capture a paginated page image from an app print HTML file.
- * Requires `render` permission.
- *
- * @param {import('./types.js').RenderPagedSnapshotRequest} request
- * @returns {Promise<import('./types.js').RenderPagedSnapshotResult>}
- */
-export async function capturePagedSnapshot(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_CAPTURE_PAGED_SNAPSHOT, [
-    request,
-  ])
-}
-
-/**
- * Default Paged.js print CSS for a built-in page size (shell-owned).
- * Requires `render` permission.
- *
- * @param {import('./types.js').PrintPageSize} [pageSize='A5']
- * @returns {Promise<string>}
- */
-export async function getDefaultPrintStylesheet(pageSize = 'A5') {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_GET_PRINT_STYLESHEET, [
-    pageSize,
-  ])
-}
-
-/** @returns {() => void} unsubscribe */
-export function onRenderProgress(listener) {
-  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.RENDER_PROGRESS, listener)
-}
-
-export async function renderCancel() {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_CANCEL, [])
-}
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from './events.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * Print an app-prepared HTML file to PDF (shell: Paged.js + Electron printToPDF).
+ * Requires `render` permission in plugin.json.
+ *
+ * @param {import('./types.js').RenderPrintHtmlRequest} request
+ * @returns {Promise<string>} Absolute path to the output PDF
+ */
+export async function renderPrintHtml(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_PRINT_HTML, [request])
+}
+
+/**
+ * Prepare an app print HTML file for preview (shell: Paged.js pagination).
+ * Requires `render` permission in plugin.json.
+ *
+ * @param {import('./types.js').RenderPagedPreviewRequest} request
+ * @returns {Promise<import('./types.js').RenderPagedPreviewResult>}
+ */
+export async function preparePagedPreview(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_PREPARE_PAGED_PREVIEW, [
+    request,
+  ])
+}
+
+/**
+ * Capture a paginated page image from an app print HTML file.
+ * Requires `render` permission.
+ *
+ * @param {import('./types.js').RenderPagedSnapshotRequest} request
+ * @returns {Promise<import('./types.js').RenderPagedSnapshotResult>}
+ */
+export async function capturePagedSnapshot(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_CAPTURE_PAGED_SNAPSHOT, [
+    request,
+  ])
+}
+
+/**
+ * Default Paged.js print CSS for a built-in page size (shell-owned).
+ * Requires `render` permission.
+ *
+ * @param {import('./types.js').PrintPageSize} [pageSize='A5']
+ * @returns {Promise<string>}
+ */
+export async function getDefaultPrintStylesheet(pageSize = 'A5') {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_GET_PRINT_STYLESHEET, [
+    pageSize,
+  ])
+}
+
+/** @returns {() => void} unsubscribe */
+export function onRenderProgress(listener) {
+  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.RENDER_PROGRESS, listener)
+}
+
+export async function renderCancel() {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.RENDER_CANCEL, [])
+}