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

package/src/bridge/client.mjs

@@ -0,0 +1,147 @@
+/**
+ * Plugin-side bridge client (plain JS, no build step).
+ * Import: @purescience/platform-ui/bridge/client
+ */
+
+import { applyThemeFromHost } from './applyThemeFromHost.mjs'
+
+export { PLATFORM_BRIDGE_EVENTS } from './events.mjs'
+export {
+  PLATFORM_BRIDGE_METHODS,
+  PLATFORM_BRIDGE_METHOD_PREFIXES,
+} from './methods.mjs'
+export {
+  applyThemeFromHost,
+  PLATFORM_THEME_STYLE_ID,
+} from './applyThemeFromHost.mjs'
+
+const CHANNEL = 'purescience-plugin-bridge'
+const HANDSHAKE_MS = 800
+
+let readyPromise = null
+let bridgeMeta = null
+let eventListenerAttached = false
+const eventListeners = new Map()
+
+function postHandshake() {
+  window.parent.postMessage({ channel: CHANNEL, type: 'handshake' }, '*')
+}
+
+function ensureEventListener() {
+  if (eventListenerAttached) return
+  eventListenerAttached = true
+  window.addEventListener('message', event => {
+    const data = event.data
+    if (!data || data.channel !== CHANNEL || data.type !== 'event') return
+    const handlers = eventListeners.get(data.name)
+    if (!handlers) return
+    for (const handler of handlers) {
+      try {
+        handler(data.payload)
+      } catch (error) {
+        console.error('[plugin-bridge] event handler failed', error)
+      }
+    }
+  })
+}
+
+function onEvent(name, handler) {
+  ensureEventListener()
+  if (!eventListeners.has(name)) {
+    eventListeners.set(name, new Set())
+  }
+  eventListeners.get(name).add(handler)
+  return () => offEvent(name, handler)
+}
+
+function offEvent(name, handler) {
+  eventListeners.get(name)?.delete(handler)
+}
+
+function waitForReady() {
+  if (readyPromise) return readyPromise
+  readyPromise = new Promise((resolve, reject) => {
+    const timeout = window.setTimeout(() => {
+      window.clearInterval(handshakeTimer)
+      reject(
+        new Error(
+          'PureScience plugin bridge ready timeout (is this page inside the desktop iframe?)',
+        ),
+      )
+    }, 15_000)
+
+    const onMessage = event => {
+      const data = event.data
+      if (!data || data.channel !== CHANNEL || data.type !== 'ready') return
+      window.clearTimeout(timeout)
+      window.clearInterval(handshakeTimer)
+      window.removeEventListener('message', onMessage)
+      const viewport =
+        data.viewport &&
+        typeof data.viewport === 'object' &&
+        typeof data.viewport.tabId === 'string'
+          ? {
+              tabId: data.viewport.tabId,
+              resource:
+                data.viewport.resource &&
+                typeof data.viewport.resource === 'object' &&
+                typeof data.viewport.resource.path === 'string'
+                  ? data.viewport.resource
+                  : null,
+            }
+          : undefined
+      bridgeMeta = {
+        version: data.version,
+        pluginId: data.pluginId,
+        appSlug: data.appSlug,
+        methods: Array.isArray(data.methods) ? data.methods : [],
+        theme: data.theme,
+        ...(viewport ? { viewport } : {}),
+      }
+      applyThemeFromHost(data.theme)
+      resolve(bridgeMeta)
+    }
+
+    window.addEventListener('message', onMessage)
+    postHandshake()
+    const handshakeTimer = window.setInterval(postHandshake, HANDSHAKE_MS)
+  })
+  return readyPromise
+}
+
+function call(method, args = []) {
+  return waitForReady().then(
+    () =>
+      new Promise((resolve, reject) => {
+        const id = `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+        const onMessage = event => {
+          const data = event.data
+          if (
+            !data ||
+            data.channel !== CHANNEL ||
+            data.type !== 'response' ||
+            data.id !== id
+          ) {
+            return
+          }
+          window.removeEventListener('message', onMessage)
+          if (data.ok) resolve(data.result)
+          else reject(new Error(data.error || 'Bridge request failed'))
+        }
+        window.addEventListener('message', onMessage)
+        window.parent.postMessage(
+          { channel: CHANNEL, type: 'request', id, method, args },
+          '*',
+        )
+      }),
+  )
+}
+
+export const bridge = {
+  waitForReady,
+  call,
+  onEvent,
+  offEvent,
+  getMethods: () => bridgeMeta?.methods ?? [],
+  ping: () => call('ping'),
+}

package/src/bridge/collectionAssetAdapter.ts

@@ -0,0 +1,63 @@
+import type { Editor } from '@tiptap/core'
+import {
+  insertCollectionImageFromBinaryResult,
+  insertInlineAssetKind,
+} from '@purescience/platform-editor'
+import type { CollectionAssetDocumentAdapter } from '../components/assets/asset-library/types.js'
+import type { PlatformAssetSummary } from './types.js'
+
+function isFileCollectionAsset(asset: PlatformAssetSummary): boolean {
+  return asset.kind === 'image' || asset.kind === 'vector'
+}
+
+function altForAsset(asset: PlatformAssetSummary): string {
+  return asset.label.trim() || asset.fileName
+}
+
+export interface CreateCollectionAssetDocumentAdapterOptions {
+  getEditor: () => Editor | null | undefined
+  readBinary: (
+    absolutePath: string,
+  ) => Promise<{ mimeType: string; base64: string }>
+}
+
+export async function insertCollectionAsset(
+  editor: Editor | null | undefined,
+  asset: PlatformAssetSummary,
+  readBinary: CreateCollectionAssetDocumentAdapterOptions['readBinary'],
+): Promise<void> {
+  if (!editor || editor.isDestroyed) return
+
+  if (isFileCollectionAsset(asset)) {
+    const binary = await readBinary(asset.absolutePath)
+    insertCollectionImageFromBinaryResult(editor, {
+      relativePath: asset.relativePath,
+      alt: altForAsset(asset),
+      mimeType: binary.mimeType,
+      base64: binary.base64,
+    })
+    return
+  }
+
+  if (
+    asset.kind === 'mermaid' ||
+    asset.kind === 'table' ||
+    asset.kind === 'math'
+  ) {
+    insertInlineAssetKind(editor, asset.kind, asset.sourceCode)
+  }
+}
+
+export function createCollectionAssetDocumentAdapter(
+  options: CreateCollectionAssetDocumentAdapterOptions,
+): CollectionAssetDocumentAdapter {
+  return {
+    insertAsset: async (asset: PlatformAssetSummary) => {
+      await insertCollectionAsset(
+        options.getEditor(),
+        asset,
+        options.readBinary,
+      )
+    },
+  }
+}

package/src/bridge/collectionAssets.d.mts

@@ -0,0 +1 @@
+export declare const DEFAULT_COLLECTION_FIGURES_DIR: 'assets/figures'

package/src/bridge/collectionAssets.mjs

@@ -0,0 +1,2 @@
+/** Default relative folder for collection file uploads (figures, pasted images). */
+export const DEFAULT_COLLECTION_FIGURES_DIR = 'assets/figures'

package/src/bridge/collectionAssets.ts

@@ -0,0 +1 @@
+export { DEFAULT_COLLECTION_FIGURES_DIR } from './collectionAssets.mjs'

package/src/bridge/collectionDocumentHtml.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  absoluteCollectionAssetPath,
+  COLLECTION_ASSET_SRC_ATTR,
+  normalizeCollectionDocumentHtml,
+  prepareCollectionDocumentHtml,
+  relativeAssetSrcForHtml,
+  relativizeCollectionAssetPath,
+} from './collectionDocumentHtml.js'
+
+describe('collectionDocumentHtml', () => {
+  const collectionPath = '/home/user/MyBook.book'
+
+  it('resolves relative and in-collection absolute paths', () => {
+    expect(relativeAssetSrcForHtml('assets/fig.png', collectionPath)).toBe(
+      'assets/fig.png',
+    )
+    expect(
+      relativeAssetSrcForHtml(
+        `${collectionPath}/assets/fig.png`,
+        collectionPath,
+      ),
+    ).toBe('assets/fig.png')
+    expect(
+      relativeAssetSrcForHtml('https://example.com/x.png', collectionPath),
+    ).toBe(null)
+  })
+
+  it('relativizes absolute paths under the collection root', () => {
+    expect(
+      relativizeCollectionAssetPath(
+        `${collectionPath}/assets/fig.png`,
+        collectionPath,
+      ),
+    ).toBe('assets/fig.png')
+    expect(
+      relativizeCollectionAssetPath('/tmp/other.png', collectionPath),
+    ).toBeNull()
+  })
+
+  it('builds absolute asset paths', () => {
+    expect(absoluteCollectionAssetPath(collectionPath, 'assets/fig.png')).toBe(
+      `${collectionPath}/assets/fig.png`,
+    )
+  })
+
+  it('prepareCollectionDocumentHtml injects data URLs and storage attribute', async () => {
+    const html = '<p><img src="assets/fig.png" alt="fig"></p>'
+    const readBinary = vi.fn().mockResolvedValue({
+      mimeType: 'image/png',
+      base64: 'abc',
+    })
+
+    const display = await prepareCollectionDocumentHtml(
+      html,
+      collectionPath,
+      readBinary,
+    )
+    expect(readBinary).toHaveBeenCalledWith(`${collectionPath}/assets/fig.png`)
+    expect(display).toContain('data:image/png;base64,abc')
+    expect(display).toContain(`${COLLECTION_ASSET_SRC_ATTR}="assets/fig.png"`)
+  })
+
+  it('normalizeCollectionDocumentHtml restores relative src from storage attribute', () => {
+    const html = `<p><img src="data:image/png;base64,abc" ${COLLECTION_ASSET_SRC_ATTR}="assets/fig.png"></p>`
+    const stored = normalizeCollectionDocumentHtml(html, collectionPath)
+    expect(stored).toContain('src="assets/fig.png"')
+    expect(stored).not.toContain(COLLECTION_ASSET_SRC_ATTR)
+    expect(stored).not.toContain('data:image/png')
+  })
+})

package/src/bridge/collectionDocumentHtml.ts

@@ -0,0 +1,118 @@
+import { COLLECTION_ASSET_SRC_ATTR } from '@purescience/platform-editor'
+
+export { COLLECTION_ASSET_SRC_ATTR }
+
+export function isDisplayableAbsoluteSource(src: string): boolean {
+  return (
+    src.startsWith('http://') ||
+    src.startsWith('https://') ||
+    src.startsWith('data:') ||
+    src.startsWith('blob:')
+  )
+}
+
+export function absoluteCollectionAssetPath(
+  collectionPath: string,
+  relativePath: string,
+): string {
+  const clean = relativePath.replace(/\\/g, '/').replace(/^\/+/, '')
+  return `${collectionPath.replace(/\/+$/, '')}/${clean}`
+}
+
+export function relativizeCollectionAssetPath(
+  absolutePath: string,
+  collectionPath: string,
+): string | null {
+  const normalizedAbsolute = absolutePath.replace(/\\/g, '/')
+  const normalizedRoot = collectionPath.replace(/\/+$/, '')
+  if (!normalizedAbsolute.startsWith(`${normalizedRoot}/`)) return null
+  return normalizedAbsolute.slice(normalizedRoot.length + 1)
+}
+
+/** Relative path stored in HTML, or null if src should be left unchanged. */
+export function relativeAssetSrcForHtml(
+  src: string,
+  collectionPath: string,
+): string | null {
+  const trimmed = src.trim()
+  if (!trimmed || isDisplayableAbsoluteSource(trimmed)) return null
+  if (trimmed.startsWith('/')) {
+    return relativizeCollectionAssetPath(trimmed, collectionPath)
+  }
+  return trimmed.replace(/\\/g, '/').replace(/^\/+/, '')
+}
+
+export type ReadCollectionBinary = (
+  absolutePath: string,
+) => Promise<{ mimeType: string; base64: string }>
+
+/** Load relative image paths as data URLs for the iframe editor. */
+export async function prepareCollectionDocumentHtml(
+  html: string,
+  collectionPath: string,
+  readBinary: ReadCollectionBinary,
+): Promise<string> {
+  if (!html.trim() || !collectionPath.trim()) return html
+  const doc = new DOMParser().parseFromString(html, 'text/html')
+  let changed = false
+
+  for (const img of Array.from(doc.querySelectorAll('img'))) {
+    const src = img.getAttribute('src')?.trim()
+    if (!src || isDisplayableAbsoluteSource(src)) continue
+
+    const relative = relativeAssetSrcForHtml(src, collectionPath)
+    if (!relative) continue
+
+    try {
+      const absolute = absoluteCollectionAssetPath(collectionPath, relative)
+      const result = await readBinary(absolute)
+      img.setAttribute('src', `data:${result.mimeType};base64,${result.base64}`)
+      img.setAttribute(COLLECTION_ASSET_SRC_ATTR, relative)
+      changed = true
+    } catch {
+      // Keep relative src when the file is missing.
+    }
+  }
+
+  return changed ? doc.body.innerHTML : html
+}
+
+/** Persist relative `img src` values (strip injected data URLs). */
+export function normalizeCollectionDocumentHtml(
+  html: string,
+  collectionPath: string,
+): string {
+  if (!html.trim() || !collectionPath.trim()) return html
+  const doc = new DOMParser().parseFromString(html, 'text/html')
+  let changed = false
+
+  for (const img of Array.from(doc.querySelectorAll('img'))) {
+    const stored = img.getAttribute(COLLECTION_ASSET_SRC_ATTR)?.trim()
+    if (stored) {
+      img.setAttribute('src', stored)
+      img.removeAttribute(COLLECTION_ASSET_SRC_ATTR)
+      changed = true
+      continue
+    }
+
+    const src = img.getAttribute('src')?.trim()
+    if (!src) continue
+
+    if (src.startsWith('file://')) {
+      try {
+        const relative = relativizeCollectionAssetPath(
+          decodeURIComponent(new URL(src).pathname),
+          collectionPath,
+        )
+        if (relative) {
+          img.setAttribute('src', relative)
+          changed = true
+        }
+      } catch {
+        // ignore malformed file URLs
+      }
+    }
+  }
+
+  return changed ? doc.body.innerHTML : html
+}

package/src/bridge/collectionImagePaste.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildPastedFigureRelativePath,
+  normalizeCollectionImageMimeType,
+  stemFromImageFileName,
+} from './collectionImagePaste.js'
+
+describe('collectionImagePaste helpers', () => {
+  it('normalizes mime types from file names', () => {
+    expect(normalizeCollectionImageMimeType(undefined, 'photo.PNG')).toBe(
+      'image/png',
+    )
+    expect(normalizeCollectionImageMimeType('image/jpeg', 'x.bin')).toBe(
+      'image/jpeg',
+    )
+  })
+
+  it('builds stable relative paths under the figures subdir', () => {
+    expect(
+      buildPastedFigureRelativePath(
+        'assets/figures',
+        'My Diagram.png',
+        'image/png',
+        1_700_000_000_000,
+      ),
+    ).toBe('assets/figures/My-Diagram-1700000000000.png')
+  })
+
+  it('derives stems from file names', () => {
+    expect(stemFromImageFileName('figures/My Photo.jpg')).toBe('My-Photo')
+  })
+})

package/src/bridge/collectionImagePaste.ts

@@ -0,0 +1,130 @@
+import type { Editor } from '@tiptap/core'
+import { insertCollectionImage } from '@purescience/platform-editor'
+import { DEFAULT_COLLECTION_FIGURES_DIR } from './collectionAssets.js'
+import { absoluteCollectionAssetPath } from './collectionDocumentHtml.js'
+
+const SUPPORTED_MIME = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+])
+
+const EXT_FOR_MIME: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/svg+xml': 'svg',
+}
+
+export interface CollectionImagePastePayload {
+  name: string
+  bytes: Uint8Array
+  mimeType: string
+}
+
+export interface CollectionImagePasteHandlerOptions {
+  collectionPath?: string
+  subdir?: string
+  onError?: (message: string) => void
+  getEditor: () => Editor | null | undefined
+  writeBinary: (absolutePath: string, bytes: Uint8Array) => Promise<void>
+}
+
+export function normalizeCollectionImageMimeType(
+  mimeType: string | undefined,
+  name: string,
+): string | undefined {
+  const trimmed = mimeType?.trim().toLowerCase()
+  if (trimmed && SUPPORTED_MIME.has(trimmed)) return trimmed
+  const ext = name.split('.').pop()?.toLowerCase()
+  if (ext === 'png') return 'image/png'
+  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg'
+  if (ext === 'gif') return 'image/gif'
+  if (ext === 'webp') return 'image/webp'
+  if (ext === 'svg') return 'image/svg+xml'
+  return undefined
+}
+
+export function stemFromImageFileName(name: string): string {
+  const base = name.replace(/\\/g, '/').split('/').pop() ?? name
+  const dot = base.lastIndexOf('.')
+  const stem = dot > 0 ? base.slice(0, dot) : base
+  return stem.replace(/\s+/g, '-').replace(/[^\w.-]+/g, '') || 'image'
+}
+
+function extensionFromImageFileName(name: string): string | undefined {
+  const ext = name.split('.').pop()?.toLowerCase()
+  if (!ext) return undefined
+  if (['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'].includes(ext)) {
+    return ext === 'jpeg' ? 'jpg' : ext
+  }
+  return undefined
+}
+
+export function buildPastedFigureRelativePath(
+  subdir: string,
+  name: string,
+  mimeType?: string,
+  now = Date.now(),
+): string {
+  const normalizedMime =
+    normalizeCollectionImageMimeType(mimeType, name) ?? 'image/png'
+  if (!SUPPORTED_MIME.has(normalizedMime)) {
+    throw new Error(
+      'Unsupported image type. Supported: PNG, JPEG, GIF, WebP, SVG.',
+    )
+  }
+  const ext =
+    EXT_FOR_MIME[normalizedMime] ?? extensionFromImageFileName(name) ?? 'png'
+  const stem = stemFromImageFileName(name) || 'image'
+  return `${subdir}/${stem}-${now}.${ext}`
+}
+
+/** Persist pasted bytes under the collection and insert into the active editor. */
+export function createCollectionImagePasteHandler(
+  options: CollectionImagePasteHandlerOptions,
+): (payload: CollectionImagePastePayload) => Promise<void> {
+  const {
+    collectionPath,
+    subdir = DEFAULT_COLLECTION_FIGURES_DIR,
+    onError,
+    getEditor,
+    writeBinary,
+  } = options
+
+  return async ({ name, bytes, mimeType }) => {
+    if (!collectionPath?.trim()) {
+      onError?.('Open a collection before inserting images.')
+      throw new Error('No collection path')
+    }
+
+    const normalizedMime =
+      normalizeCollectionImageMimeType(mimeType, name) ?? 'image/png'
+    const relativePath = buildPastedFigureRelativePath(
+      subdir,
+      name,
+      normalizedMime,
+    )
+    const absolutePath = absoluteCollectionAssetPath(
+      collectionPath,
+      relativePath,
+    )
+    await writeBinary(absolutePath, bytes)
+
+    const stem = stemFromImageFileName(name)
+    const editor = getEditor()
+    if (
+      !insertCollectionImage(editor, {
+        relativePath,
+        alt: stem,
+        bytes,
+        mimeType: normalizedMime,
+      })
+    ) {
+      onError?.('Image nodes are not available in this editor.')
+    }
+  }
+}

package/src/bridge/context.mjs

@@ -0,0 +1,12 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * Publish structured context from this tab for agent sessions.
+ * Requires `agents` permission.
+ *
+ * @param {{ summary: string, label?: string }} request
+ */
+export async function publishContext(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CONTEXT_PUBLISH, [request])
+}

package/src/bridge/credentials.mjs

@@ -0,0 +1,22 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/** Credential vault bridge — status/list/set/delete only (no get). Requires `agents` permission. */
+
+export async function readCredentialStorageStatus() {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_STORAGE_STATUS, [])
+}
+
+export async function listCredentials() {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_LIST, [])
+}
+
+/** @param {{ id: string, value: string }} request */
+export async function setCredential(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_SET, [request])
+}
+
+/** @param {{ id: string }} request */
+export async function deleteCredential(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_DELETE, [request])
+}

package/src/bridge/dialog.d.mts

@@ -0,0 +1,5 @@
+export interface PlatformDialogPathResult {
+  path: string | null
+}
+
+export declare function openPlatformImageDialog(): Promise<string | null>

package/src/bridge/dialog.mjs

@@ -0,0 +1,13 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * @returns {Promise<string | null>} Absolute path to the picked image, or null if cancelled.
+ */
+export async function openPlatformImageDialog() {
+  const result = await bridge.call(
+    PLATFORM_BRIDGE_METHODS.DIALOG_OPEN_IMAGE,
+    [],
+  )
+  return result?.path ?? null
+}

package/src/bridge/events.d.mts

@@ -0,0 +1,14 @@
+export declare const PLATFORM_BRIDGE_EVENTS: {
+  readonly RESOURCE_OPEN: 'resource.open'
+  readonly THEME_CHANGED: 'theme.changed'
+  readonly RENDER_PROGRESS: 'render.progress'
+  readonly WATCH_CHANGE: 'watch.change'
+  readonly AGENT_RUN_EVENT: 'agents.run.event'
+  readonly AGENT_TOOL_INVOKE: 'agents.tool.invoke'
+  readonly DEBUG_TEST: 'debug.test'
+  readonly SCHEDULE_FIRE: 'schedule.fire'
+  readonly WINDOW_CAMERA_SHORTCUT: 'window.cameraShortcut'
+}
+
+export type PlatformBridgeEventName =
+  (typeof PLATFORM_BRIDGE_EVENTS)[keyof typeof PLATFORM_BRIDGE_EVENTS]

package/src/bridge/events.mjs

@@ -0,0 +1,12 @@
+/** Host → plugin bridge event names. Single source for shell + app SDK. */
+export const PLATFORM_BRIDGE_EVENTS = {
+  RESOURCE_OPEN: 'resource.open',
+  THEME_CHANGED: 'theme.changed',
+  RENDER_PROGRESS: 'render.progress',
+  WATCH_CHANGE: 'watch.change',
+  AGENT_RUN_EVENT: 'agents.run.event',
+  AGENT_TOOL_INVOKE: 'agents.tool.invoke',
+  DEBUG_TEST: 'debug.test',
+  SCHEDULE_FIRE: 'schedule.fire',
+  WINDOW_CAMERA_SHORTCUT: 'window.cameraShortcut',
+}