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

package/src/bridge/types.ts

@@ -0,0 +1,439 @@
+export type PlatformBridgeEventName =
+  import('./events.mjs').PlatformBridgeEventName
+
+import type { PlatformThemeMode } from '../theme/tokens.js'
+
+/** Shell prefs exposed via `settings.prefs.get` / `settings.prefs.set`. */
+export type PlatformThemePreference = PlatformThemeMode
+
+export interface PlatformShellPreferences {
+  workingDirectory: string
+  theme: PlatformThemePreference
+  appSettings?: Record<string, Record<string, unknown>>
+  /** Local agent models enabled in the shell model menu. */
+  enabledLocalLlmModelIds?: string[]
+  /** Low / high agent model tiers from shell settings. */
+  agentModelTiers?: {
+    lowLevelModelId: string
+    highLevelModelId: string
+  }
+  /** Defaults for new agent sessions per scope. */
+  agentSessionDefaults?: {
+    global?: Record<string, unknown>
+    apps?: Record<string, Record<string, unknown>>
+  }
+  /** Explicit opt-in switches for unfinished capabilities. */
+  betaFeatures?: {
+    /** Enables model-backed Pure Render reference-image extraction in app panels. */
+    pureRenderVisionExtraction?: boolean
+  }
+  /**
+   * Host-only workspace tab session (phase 4). Plugin apps should ignore this field.
+   */
+  platformWorkspace?: Record<string, unknown>
+}
+
+export interface PlatformAppSettingsUpdateRequest {
+  appSlug: string
+  patch: Record<string, unknown>
+}
+
+export interface PlatformThemeBridgePayload {
+  mode: PlatformThemeMode
+  /** Active surface palette id, omitted when platform default. */
+  surfacePaletteId?: string | null
+  css: string
+}
+
+export type PlatformFileKind =
+  | 'folder'
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'pdf'
+  | 'code'
+  | 'html'
+  | 'markdown'
+  | 'spreadsheet'
+  | 'data'
+  | 'text'
+  | 'other'
+
+/** Mirrors `PlatformAppManifest` from the shell contracts. */
+export interface PlatformAppManifest {
+  id: string
+  slug: string
+  name: string
+  navigationLabel?: string
+  productName: string
+  kind: string
+  description: string
+  peopleProviders?: Array<{
+    id: string
+    label: string
+    storage: {
+      fileName: string
+      contactPaths: Array<{
+        path: string
+        nameField?: string
+        emailField?: string
+      }>
+    }
+  }>
+  icon?: string
+  source?: 'builtin' | 'plugin'
+  pluginId?: string
+  pluginRoot?: string
+}
+
+export interface PlatformPeopleSuggestRequest {
+  query: string
+  limit?: number
+}
+
+export interface PlatformPeopleSuggestion {
+  name: string
+  email?: string
+  sourceAppSlug: string
+  sourceLabel: string
+  providerId: string
+}
+
+/** Mirrors `PlatformShellManifest` from the shell contracts. */
+export interface PlatformShellManifest {
+  apps: PlatformAppManifest[]
+}
+
+/**
+ * Binds one plugin iframe to a shell workspace tab (phase 4+).
+ * `resource` is the document/file this tab owns; `null` for app-only tabs.
+ */
+export interface PlatformBridgeViewportBinding {
+  tabId: string
+  resource: ResourceOpenEvent | null
+}
+
+export interface PlatformBridgeReadyMeta {
+  version: number
+  pluginId: string
+  appSlug: string
+  methods: string[]
+  theme?: PlatformThemeBridgePayload
+  /** Per-tab open intent — apps should prefer this over global consume queues. */
+  viewport?: PlatformBridgeViewportBinding
+}
+
+export interface ResourceOpenEvent {
+  path: string
+  name?: string
+  kind?: PlatformFileKind
+  sourceAppSlug?: string
+}
+
+export type RenderProgressPhase =
+  | 'loading'
+  | 'paginating'
+  | 'printing'
+  | 'done'
+  | 'error'
+
+export interface RenderProgress {
+  phase: RenderProgressPhase
+  pct?: number
+  message?: string
+  outputPath?: string
+  hint?: string
+  sourcePath?: string
+}
+
+export interface RenderPrintHtmlRequest {
+  htmlPath: string
+  outputPath: string
+  basePath?: string
+  pageSize?: string
+  margins?: string
+  loadingMessage?: string
+}
+
+export interface RenderPagedPreviewRequest {
+  htmlPath: string
+  basePath?: string
+  loadingMessage?: string
+}
+
+export interface RenderPagedSnapshotRequest {
+  htmlPath: string
+  outputPath: string
+  basePath?: string
+  page?: number
+  loadingMessage?: string
+}
+
+export interface RenderPagedSnapshotResult {
+  imagePath: string
+  page: number
+  pageCount: number
+  metrics?: RenderPagedSnapshotMetrics
+}
+
+export interface RenderPagedSnapshotMetrics {
+  topGapRatio: number
+  bottomGapRatio: number
+  usedHeightRatio: number
+  pageCount?: number
+  problemPage?: number
+  figurePage?: number
+  imagePage?: number
+  captionPage?: number
+  headingPage?: number
+  blankBeforeFigurePx?: number
+  blankBeforeFigureRatio?: number
+  blankPageCount?: number
+  imageVisible?: boolean
+  captionVisible?: boolean
+  captionOrphaned?: boolean
+  strandedHeading?: boolean | null
+}
+
+export interface RenderPagedPreviewResult {
+  htmlPath: string
+  html: string
+  pageCount: number
+}
+
+/** Built-in trade-book page sizes (`render.getPrintStylesheet`). */
+export type PrintPageSize = 'A4' | 'A5' | '6x9'
+
+export type FileWatchChangeType = 'add' | 'change' | 'unlink'
+
+export interface FileWatchChange {
+  path: string
+  relativePath: string
+  type: FileWatchChangeType
+}
+
+/** Plugin bridge `watch.change` payload. */
+export interface WatchChangeEvent extends FileWatchChange {
+  rootPath: string
+}
+
+/**
+ * Result of `catalog.consumePendingOpen` — open intent for **this viewport tab only**.
+ * Prefer `PlatformBridgeReadyMeta.viewport.resource` on boot when available.
+ */
+export interface PlatformCatalogConsumePendingOpenResult {
+  resource: ResourceOpenEvent | null
+}
+
+export interface PlatformPluginInstallRequest {
+  path: string
+}
+
+export interface PlatformPluginInstallSummary {
+  id: string
+  name: string
+  rootDir: string
+}
+
+export interface PlatformPluginInstallResult {
+  installed: boolean
+  sourcePath: string
+  targetPath: string
+  plugin: PlatformPluginInstallSummary
+}
+
+/** Minimal manifest fields for install / create gating in plugin apps. */
+export interface PlatformAppInstallState {
+  pluginRoot?: string
+}
+
+export interface PlatformFileReadPreviewResult {
+  path: string
+  content: string | null
+  truncated: boolean
+  encoding: 'utf-8'
+}
+
+export interface PlatformFileReadBinaryResult {
+  path: string
+  mimeType: string
+  base64: string
+  truncated: boolean
+  byteLength: number
+}
+
+export interface PlatformFilePreviewUrlResult {
+  path: string
+  url: string
+  mimeType: string
+  byteLength: number
+}
+
+/** Minimal file entry fields required for inline preview in plugin iframes. */
+export interface PlatformFilePreviewEntry {
+  path: string
+  name: string
+  extension: string
+  kind: PlatformFileKind
+  isDirectory: boolean
+}
+
+/** Collection asset index — shell `assets.*`; apps pass `collectionPath`. */
+export type PlatformAssetKind =
+  | 'image'
+  | 'vector'
+  | 'mermaid'
+  | 'table'
+  | 'math'
+  | 'other'
+
+export type PlatformAssetOrigin =
+  | 'uploaded'
+  | 'imported'
+  | 'generated'
+  | 'derived'
+
+export type PlatformAssetSourceType =
+  | 'file'
+  | 'inline-mermaid'
+  | 'inline-table'
+  | 'inline-math'
+
+export interface PlatformAssetUsage {
+  documentPath: string
+  title: string
+}
+
+export interface PlatformAssetSummary {
+  id: string
+  collectionPath: string
+  relativePath: string
+  absolutePath: string
+  fileName: string
+  label: string
+  caption?: string
+  description?: string
+  kind: PlatformAssetKind
+  mimeType: string
+  byteLength: number
+  modifiedAt: string
+  usedIn: PlatformAssetUsage[]
+  lineageId: string
+  versionNumber: number
+  parentRelativePath?: string
+  origin?: PlatformAssetOrigin
+  transformationPrompt?: string
+  createdBy?: string
+  sourceType?: PlatformAssetSourceType
+  sourceCode?: string
+  sourceDocumentPath?: string
+  sourceAppSlug?: string
+  sourceNodeId?: string
+}
+
+export interface PlatformAssetContext {
+  asset: PlatformAssetSummary
+  versions: PlatformAssetSummary[]
+  isLatestVersion: boolean
+  latestVersionRelativePath: string
+  totalVersions: number
+}
+
+export interface PlatformAssetListScopedRequest {
+  collectionPath: string
+  /** Relative paths under `collectionPath` — supplied by the active app. */
+  documentFiles: string[]
+}
+
+export interface PlatformAssetDeleteRequest {
+  collectionPath: string
+  relativePath: string
+}
+
+export interface PlatformAssetUpdateRequest {
+  collectionPath: string
+  relativePath: string
+  label?: string
+  caption?: string
+  description?: string
+  sourceDocumentPath?: string
+  sourceAppSlug?: string
+}
+
+export interface PlatformAssetSourceUpdateRequest
+  extends PlatformAssetUpdateRequest {
+  assetId: string
+  kind: 'mermaid' | 'table' | 'math'
+  sourceCode: string
+}
+
+export interface PlatformAssetSourceUpdateScopedRequest
+  extends PlatformAssetSourceUpdateRequest {
+  /** Relative paths under `collectionPath` — supplied by the active app. */
+  documentFiles: string[]
+}
+
+export interface PlatformAssetSelection {
+  collectionPath: string
+  relativePath: string
+}
+
+export interface PlatformAssetVersionCreateRequest {
+  collectionPath: string
+  sourceRelativePath: string
+  sourcePath: string
+  label?: string
+  caption?: string
+  description?: string
+  transformationPrompt?: string
+  createdBy?: string
+}
+
+export interface PlatformAssetReferenceSwapRequest {
+  collectionPath: string
+  fromRelativePath: string
+  toRelativePath: string
+  scope: 'document' | 'collection'
+  documentFile?: string
+}
+
+export interface PlatformAssetReferenceSwapScopedRequest
+  extends PlatformAssetReferenceSwapRequest {
+  /** Relative paths under `collectionPath` — supplied by the active app. */
+  documentFiles: string[]
+}
+
+export interface PlatformAssetReferenceSwapResult {
+  updatedDocuments: number
+  updatedReferences: number
+}
+
+export interface PlatformAssetTransformRequest {
+  collectionPath?: string
+  sourceRelativePath?: string
+  prompt: string
+  label?: string
+  createdBy?: string
+}
+
+export interface PlatformAssetGetContextRequest {
+  collectionPath: string
+  relativePath: string
+}
+
+export type PlatformBridgeEventHandler = (payload: unknown) => void
+
+export interface PlatformBridgeClient {
+  waitForReady(): Promise<PlatformBridgeReadyMeta>
+  call<T = unknown>(method: string, args?: unknown[]): Promise<T>
+  onEvent(
+    name: PlatformBridgeEventName | string,
+    handler: PlatformBridgeEventHandler,
+  ): () => void
+  offEvent(
+    name: PlatformBridgeEventName | string,
+    handler: PlatformBridgeEventHandler,
+  ): void
+  getMethods(): string[]
+  ping(): Promise<unknown>
+}

package/src/bridge/watch.d.mts

@@ -0,0 +1,9 @@
+import type { WatchChangeEvent } from './types.js'
+
+export function watchStart(rootPath: string): Promise<void>
+
+export function watchStop(rootPath: string): Promise<void>
+
+export function onWatchChange(
+  listener: (payload: WatchChangeEvent) => void,
+): () => void

package/src/bridge/watch.mjs

@@ -0,0 +1,34 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from './events.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * Start watching a directory for debounced filesystem events.
+ * Requires `filesystem` permission.
+ *
+ * @param {string} rootPath Absolute path to watch
+ * @returns {Promise<void>}
+ */
+export async function watchStart(rootPath) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.WATCH_START, [rootPath])
+}
+
+/**
+ * Stop watching a directory for this plugin tab.
+ *
+ * @param {string} rootPath Same absolute path passed to watchStart
+ * @returns {Promise<void>}
+ */
+export async function watchStop(rootPath) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.WATCH_STOP, [rootPath])
+}
+
+/**
+ * Subscribe to watch.change events for paths this tab is watching.
+ *
+ * @param {(payload: import('./types.js').WatchChangeEvent) => void} listener
+ * @returns {() => void} unsubscribe
+ */
+export function onWatchChange(listener) {
+  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.WATCH_CHANGE, listener)
+}

package/src/bridge/watch.ts

@@ -0,0 +1 @@
+export { onWatchChange, watchStart, watchStop } from './watch.mjs'

package/src/bridge/window.d.mts

@@ -0,0 +1,44 @@
+export type PlatformScreenCaptureMode = 'content' | 'ui'
+
+export interface PlatformScreenCaptureRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface PlatformScreenCaptureOptionChoice {
+  value: string
+  label: string
+}
+
+/** A contextual control the overlay renders (e.g. design scope: this/all). */
+export interface PlatformScreenCaptureOption {
+  id: string
+  label: string
+  type: 'toggle' | 'choice'
+  choices?: PlatformScreenCaptureOptionChoice[]
+  default?: string | boolean
+}
+
+export type PlatformScreenCaptureOptionValues = Record<string, string | boolean>
+
+export interface PlatformScreenCaptureResult {
+  /** PNG data URL of the cropped region with the drawn marks composited in. */
+  imageDataUrl: string
+  /** Selection rect — app-local px in content mode, window px in vibe mode. */
+  rect: PlatformScreenCaptureRect
+  note: string
+  mode: PlatformScreenCaptureMode
+  /** True when the user drew pen marks — the agent should focus on them. */
+  hasMarks: boolean
+  /** Selected values for the contextual option controls, keyed by option id. */
+  optionValues: PlatformScreenCaptureOptionValues
+}
+
+export declare function startScreenCapture(options?: {
+  label?: string
+  options?: PlatformScreenCaptureOption[]
+}): Promise<PlatformScreenCaptureResult | null>
+
+export declare function onScreenCaptureShortcut(listener: () => void): () => void

package/src/bridge/window.mjs

@@ -0,0 +1,33 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from './events.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * Start the shell's chromeless screen-capture overlay. The user drags a region,
+ * draws marks, and adds a note; resolves with the cropped annotated image plus
+ * the selection rect (app-local px in content mode, window px in vibe mode), or
+ * null if cancelled. Requires `agents` permission.
+ *
+ * @param {{ label?: string, options?: import('./window.d.mts').PlatformScreenCaptureOption[] }} [options]
+ *   `label` states what the capture transforms (e.g. "book content", "page
+ *   design"); `options` are contextual controls rendered in the overlay.
+ * @returns {Promise<import('./window.d.mts').PlatformScreenCaptureResult | null>}
+ */
+export async function startScreenCapture(options = {}) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.WINDOW_START_SCREEN_CAPTURE, [
+    { label: options.label, options: options.options },
+  ])
+}
+
+/**
+ * Subscribe to the window-wide camera shortcut (Cmd/Ctrl+Shift+X), forwarded to
+ * the active app. Apps typically respond by opening their default capture.
+ *
+ * @param {() => void} listener
+ * @returns {() => void} unsubscribe
+ */
+export function onScreenCaptureShortcut(listener) {
+  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.WINDOW_CAMERA_SHORTCUT, () => {
+    listener()
+  })
+}

package/src/chrome/index.ts

@@ -0,0 +1 @@
+export * from '../components/chrome/index.js'

package/src/components/accessibility/AccessibilityReviewDialog.test.tsx

@@ -0,0 +1,104 @@
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { AccessibilityReviewDialog } from './AccessibilityReviewDialog.js'
+
+function render(ui: React.ReactElement): {
+  container: HTMLDivElement
+  root: Root
+} {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  act(() => {
+    root.render(ui)
+  })
+  return { container, root }
+}
+
+function buttonNamed(name: string): HTMLButtonElement {
+  const buttons = Array.from(document.querySelectorAll('button'))
+  const button = buttons.find(item => item.textContent?.trim() === name)
+  if (!(button instanceof HTMLButtonElement)) {
+    throw new Error(`Button not found: ${name}`)
+  }
+  return button
+}
+
+function changeTextarea(value: string): void {
+  const textarea = document.querySelector('textarea')
+  if (!(textarea instanceof HTMLTextAreaElement)) {
+    throw new Error('Draft textarea not found')
+  }
+  const valueSetter = Object.getOwnPropertyDescriptor(
+    HTMLTextAreaElement.prototype,
+    'value',
+  )?.set
+  act(() => {
+    valueSetter?.call(textarea, value)
+    textarea.dispatchEvent(new InputEvent('input', { bubbles: true }))
+  })
+}
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('AccessibilityReviewDialog', () => {
+  it('lets a reviewer draft, edit, and apply an image alt text fix', () => {
+    const onChange = vi.fn()
+    const html =
+      '<figure><img src="revenue-chart.png"><figcaption>Revenue by quarter</figcaption></figure>'
+
+    render(
+      <AccessibilityReviewDialog
+        open
+        html={html}
+        onClose={() => undefined}
+        onChange={onChange}
+      />,
+    )
+
+    expect(document.body.textContent).toContain('1 findings')
+    expect(document.body.textContent).toContain('Image needs alt text')
+
+    act(() => {
+      buttonNamed('Draft fix').click()
+    })
+
+    const textarea = document.querySelector('textarea')
+    expect(textarea).toBeInstanceOf(HTMLTextAreaElement)
+    expect((textarea as HTMLTextAreaElement).value).toBe('Revenue by quarter')
+
+    changeTextarea('Quarterly revenue chart')
+
+    act(() => {
+      buttonNamed('Use alt text').click()
+    })
+
+    expect(onChange).toHaveBeenCalledWith(
+      expect.stringContaining('alt="Quarterly revenue chart"'),
+    )
+  })
+
+  it('applies safe mechanical fixes without opening a draft editor', () => {
+    const onChange = vi.fn()
+    const html = '<figure><img src="separator.png"></figure>'
+
+    render(
+      <AccessibilityReviewDialog
+        open
+        html={html}
+        onClose={() => undefined}
+        onChange={onChange}
+      />,
+    )
+
+    act(() => {
+      buttonNamed('Apply fix').click()
+    })
+
+    expect(onChange).toHaveBeenCalledWith(expect.stringContaining('alt=""'))
+    expect(document.querySelector('textarea')).toBeNull()
+  })
+})