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

package/src/bridge/methods.mjs

@@ -0,0 +1,132 @@
+/** Plugin ↔ shell bridge method names. Single source for shell + app SDK. */
+export const PLATFORM_BRIDGE_METHODS = {
+  PING: 'ping',
+
+  RUNTIME_VERSION: 'runtime.version',
+  RUNTIME_PLATFORM: 'runtime.platform',
+
+  CATALOG_MANIFEST: 'catalog.manifest',
+  CATALOG_MATCH_APPS: 'catalog.matchApps',
+  CATALOG_OPEN: 'catalog.open',
+  WORKSPACE_OPEN_APP: 'workspace.openApp',
+  WORKSPACE_OPEN_PALETTE: 'workspace.openPalette',
+  SCHEDULER_REGISTER: 'scheduler.register',
+  SCHEDULER_UNREGISTER: 'scheduler.unregister',
+  CATALOG_CONSUME_PENDING_OPEN: 'catalog.consumePendingOpen',
+
+  THEME_SET_SURFACE_PALETTE: 'theme.setSurfacePalette',
+
+  WINDOW_START_SCREEN_CAPTURE: 'window.startScreenCapture',
+
+  SETTINGS_PREFS_GET: 'settings.prefs.get',
+  SETTINGS_PREFS_SET: 'settings.prefs.set',
+  SETTINGS_APP_GET: 'settings.app.get',
+  SETTINGS_APP_UPDATE: 'settings.app.update',
+
+  STORAGE_READ_JSON: 'storage.readJson',
+  STORAGE_WRITE_JSON: 'storage.writeJson',
+
+  FS_LIST: 'fs.list',
+  FS_READ_PREVIEW: 'fs.readPreview',
+  FS_READ_BINARY: 'fs.readBinary',
+  FS_PREVIEW_URL: 'fs.previewUrl',
+  FS_CREATE_FOLDER: 'fs.createFolder',
+  FS_RENAME: 'fs.rename',
+  FS_DELETE: 'fs.delete',
+  FS_READ: 'fs.read',
+  FS_WRITE: 'fs.write',
+  FS_WRITE_BINARY: 'fs.writeBinary',
+
+  DIALOG_OPEN_FOLDER: 'dialog.openFolder',
+  DIALOG_SAVE_FOLDER: 'dialog.saveFolder',
+  DIALOG_OPEN_IMAGE: 'dialog.openImage',
+  DIALOG_OPEN_FILE: 'dialog.openFile',
+
+  OS_REVEAL: 'os.reveal',
+  OS_OPEN_PATH: 'os.openPath',
+  OS_TRASH: 'os.trash',
+
+  RENDER_PRINT_HTML: 'render.printHtml',
+  RENDER_PREPARE_PAGED_PREVIEW: 'render.preparePagedPreview',
+  RENDER_CAPTURE_PAGED_SNAPSHOT: 'render.capturePagedSnapshot',
+  RENDER_GET_PRINT_STYLESHEET: 'render.getPrintStylesheet',
+  RENDER_CANCEL: 'render.cancel',
+
+  WATCH_START: 'watch.start',
+  WATCH_STOP: 'watch.stop',
+
+  ASSETS_LIST: 'assets.list',
+  ASSETS_LIST_SCOPED: 'assets.listScoped',
+  ASSETS_DELETE: 'assets.delete',
+  ASSETS_UPDATE: 'assets.update',
+  ASSETS_UPDATE_SOURCE: 'assets.updateSource',
+  ASSETS_UPDATE_SOURCE_SCOPED: 'assets.updateSourceScoped',
+  ASSETS_GET_SELECTED: 'assets.getSelected',
+  ASSETS_SET_SELECTED: 'assets.setSelected',
+  ASSETS_CREATE_VERSION: 'assets.createVersion',
+  ASSETS_SWAP_REFERENCES: 'assets.swapReferences',
+  ASSETS_SWAP_REFERENCES_SCOPED: 'assets.swapReferencesScoped',
+  ASSETS_TRANSFORM: 'assets.transform',
+  ASSETS_GET_CONTEXT: 'assets.getContext',
+
+  NETWORK_FETCH: 'network.fetch',
+  OAUTH_LOOPBACK_AUTHORIZE: 'oauth.loopbackAuthorize',
+  SECRETS_GET: 'secrets.get',
+  SECRETS_SET: 'secrets.set',
+  SECRETS_DELETE: 'secrets.delete',
+  SECRETS_STATUS: 'secrets.status',
+
+  DEBUG_EMIT_EVENT: 'debug.emitEvent',
+
+  PLUGINS_INSTALL: 'plugins.install',
+  CONTEXT_PUBLISH: 'context.publish',
+  PEOPLE_SUGGEST: 'people.suggest',
+  PEOPLE_RESEARCH: 'people.research',
+
+  CREDENTIALS_STORAGE_STATUS: 'credentials.storageStatus',
+  CREDENTIALS_LIST: 'credentials.list',
+  CREDENTIALS_SET: 'credentials.set',
+  CREDENTIALS_DELETE: 'credentials.delete',
+
+  AGENTS_SESSIONS_CREATE: 'agents.sessions.create',
+  AGENTS_SESSIONS_LIST: 'agents.sessions.list',
+  AGENTS_SESSIONS_READ: 'agents.sessions.read',
+  AGENTS_SESSIONS_UPDATE: 'agents.sessions.update',
+  AGENTS_SESSIONS_DELETE: 'agents.sessions.delete',
+
+  AGENTS_SESSION_SEND_MESSAGE: 'agents.session.sendMessage',
+  AGENTS_SESSION_APPROVE_TOOLS: 'agents.session.approveTools',
+  AGENTS_SESSION_REJECT_TOOLS: 'agents.session.rejectTools',
+  AGENTS_SESSION_ADVANCE_PENDING: 'agents.session.advancePending',
+  AGENTS_SESSION_INTERRUPT: 'agents.session.interrupt',
+
+  AGENTS_RUN_START: 'agents.run.start',
+  AGENTS_RUN_SEND: 'agents.run.send',
+  AGENTS_RUN_CALL_MODEL: 'agents.run.callModel',
+  AGENTS_RUN_RESOLVE_TOOL_CALLS: 'agents.run.resolveToolCalls',
+  AGENTS_RUN_READ_CONTEXT: 'agents.run.readContext',
+  AGENTS_LLM_MENU_OPTIONS: 'agents.llm.menuOptions',
+  AGENTS_LOCAL_MODELS_STATUS: 'agents.localModels.status',
+  AGENTS_TOOLS_REGISTER: 'agents.tools.register',
+  AGENTS_TOOLS_COMPLETE: 'agents.tools.complete',
+}
+
+export const PLATFORM_BRIDGE_METHOD_PREFIXES = {
+  RUNTIME: 'runtime.',
+  THEME: 'theme.',
+  WINDOW: 'window.',
+  SETTINGS: 'settings.',
+  STORAGE: 'storage.',
+  FS: 'fs.',
+  DIALOG: 'dialog.',
+  OS: 'os.',
+  RENDER: 'render.',
+  WATCH: 'watch.',
+  ASSETS: 'assets.',
+  NETWORK: 'network.',
+  OAUTH: 'oauth.',
+  SECRETS: 'secrets.',
+  AGENTS: 'agents.',
+  PEOPLE: 'people.',
+  DEBUG: 'debug.',
+}

package/src/bridge/os.d.mts

@@ -0,0 +1,11 @@
+export declare function revealPlatformPath(
+  targetPath: string,
+): Promise<{ ok: true }>
+
+export declare function openPlatformPath(
+  targetPath: string,
+): Promise<{ ok: true }>
+
+export declare function trashPlatformPath(
+  targetPath: string,
+): Promise<{ ok: true }>

package/src/bridge/os.mjs

@@ -0,0 +1,26 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * @param {string} targetPath Absolute file or folder path to reveal in the OS file manager.
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function revealPlatformPath(targetPath) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.OS_REVEAL, [targetPath])
+}
+
+/**
+ * @param {string} targetPath Absolute file or folder path to open with the OS default handler.
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function openPlatformPath(targetPath) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.OS_OPEN_PATH, [targetPath])
+}
+
+/**
+ * @param {string} targetPath Absolute file or folder path to move to the OS trash.
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function trashPlatformPath(targetPath) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.OS_TRASH, [targetPath])
+}

package/src/bridge/plugins.d.mts

@@ -0,0 +1,9 @@
+import type { PlatformPluginInstallResult } from './types.js'
+
+export function installPluginPackage(
+  packagePath: string,
+): Promise<PlatformPluginInstallResult>
+
+export function openPluginInstallFolderDialog(): Promise<string | null>
+
+export function pickAndInstallPluginPackage(): Promise<PlatformPluginInstallResult | null>

package/src/bridge/plugins.mjs

@@ -0,0 +1,31 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * @param {string} packagePath
+ * @returns {Promise<import('./types.ts').PlatformPluginInstallResult>}
+ */
+export async function installPluginPackage(packagePath) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.PLUGINS_INSTALL, [
+    { path: packagePath },
+  ])
+}
+
+/**
+ * @returns {Promise<string | null>}
+ */
+export async function openPluginInstallFolderDialog() {
+  const result = await bridge.call(PLATFORM_BRIDGE_METHODS.DIALOG_OPEN_FOLDER)
+  return result?.path ?? null
+}
+
+/**
+ * Pick a plugin folder (dev tree or `.pure.app` package) and install via shell.
+ *
+ * @returns {Promise<import('./types.ts').PlatformPluginInstallResult | null>}
+ */
+export async function pickAndInstallPluginPackage() {
+  const picked = await openPluginInstallFolderDialog()
+  if (!picked) return null
+  return installPluginPackage(picked)
+}

package/src/bridge/plugins.ts

@@ -0,0 +1,5 @@
+export {
+  installPluginPackage,
+  openPluginInstallFolderDialog,
+  pickAndInstallPluginPackage,
+} from './plugins.mjs'

package/src/bridge/preferences.d.mts

@@ -0,0 +1,7 @@
+import type { PlatformShellPreferences } from './types.js'
+
+export function getPlatformPreferences(): Promise<PlatformShellPreferences>
+
+export function patchPlatformPreferences(
+  patch: Partial<PlatformShellPreferences>,
+): Promise<PlatformShellPreferences>

package/src/bridge/preferences.mjs

@@ -0,0 +1,17 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * @returns {Promise<import('./types.ts').PlatformShellPreferences>}
+ */
+export async function getPlatformPreferences() {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.SETTINGS_PREFS_GET)
+}
+
+/**
+ * @param {Partial<import('./types.ts').PlatformShellPreferences>} patch
+ * @returns {Promise<import('./types.ts').PlatformShellPreferences>}
+ */
+export async function patchPlatformPreferences(patch) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.SETTINGS_PREFS_SET, [patch])
+}

package/src/bridge/preferences.ts

@@ -0,0 +1,13 @@
+export {
+  getPlatformPreferences,
+  patchPlatformPreferences,
+} from './preferences.mjs'
+export {
+  AGENT_AUTO_MODEL_ID,
+  AGENT_AUTO_MODEL_LABEL,
+  DEFAULT_AGENT_HIGH_LEVEL_MODEL_ID,
+  DEFAULT_AGENT_LOW_LEVEL_MODEL_ID,
+  isAgentAutoModelId,
+  resolveAgentModelTiersFromPrefs,
+  type PlatformAgentModelTiers,
+} from './agentModelTiers.js'

package/src/bridge/printDocument.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildPrintHtmlDocument,
+  escapeHtml,
+  fileBaseHref,
+  pdfExportPath,
+  printHtmlExportPath,
+  slugifyPrintTitle,
+} from './printDocument.js'
+
+describe('printDocument', () => {
+  it('builds export paths under the collection root', () => {
+    expect(printHtmlExportPath('/tmp/ws')).toBe('/tmp/ws/print/export.html')
+    expect(pdfExportPath('/tmp/ws', 'My Draft')).toBe(
+      '/tmp/ws/dist/my-draft.pdf',
+    )
+    expect(slugifyPrintTitle('Hello, World!')).toBe('hello-world')
+  })
+
+  it('escapes HTML in document titles', () => {
+    const html = buildPrintHtmlDocument({
+      rootPath: '/tmp/ws',
+      title: 'A & B <script>',
+      bodyHtml: '<main>x</main>',
+      stylesheet: '@page { size: A5; }',
+    })
+    expect(html).toContain('<title>A &amp; B &lt;script&gt;</title>')
+    expect(html).not.toContain('<script>')
+  })
+
+  it('sets base href for print asset resolution', () => {
+    expect(fileBaseHref('/tmp/ws')).toBe('file:///tmp/ws/')
+    const html = buildPrintHtmlDocument({
+      rootPath: '/tmp/ws',
+      title: 'T',
+      bodyHtml: '<p>Hi</p>',
+      stylesheet: 'body {}',
+      bodyClass: 'writer-document',
+    })
+    expect(html).toContain('<base href="file:///tmp/ws/">')
+    expect(html).toContain('class="writer-document"')
+  })
+
+  it('escapeHtml leaves normal text unchanged', () => {
+    expect(escapeHtml('plain')).toBe('plain')
+  })
+})

package/src/bridge/printDocument.ts

@@ -0,0 +1,75 @@
+export const PRINT_EXPORT_DIR = 'print'
+export const PRINT_EXPORT_FILE = 'export.html'
+export const PDF_DIST_DIR = 'dist'
+
+/** Filesystem-safe slug for PDF output file names. */
+export function slugifyPrintTitle(
+  title: string,
+  fallback = 'document',
+): string {
+  return (
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '') || fallback
+  )
+}
+
+export function printHtmlExportPath(rootPath: string): string {
+  const root = rootPath.replace(/\/+$/, '')
+  return `${root}/${PRINT_EXPORT_DIR}/${PRINT_EXPORT_FILE}`
+}
+
+export function pdfExportPath(
+  rootPath: string,
+  title: string,
+  fallback = 'document',
+): string {
+  const root = rootPath.replace(/\/+$/, '')
+  return `${root}/${PDF_DIST_DIR}/${slugifyPrintTitle(title, fallback)}.pdf`
+}
+
+/** Base href for relative asset URLs in a print HTML document on disk. */
+export function fileBaseHref(rootPath: string): string {
+  const normalized = rootPath.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (/^[A-Za-z]:[/\\]/.test(normalized)) {
+    return `file:///${normalized.replace(/\\/g, '/')}/`
+  }
+  if (normalized.startsWith('/')) return `file://${normalized}/`
+  return `file:///${normalized}/`
+}
+
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+/** Complete HTML document for `render.printHtml` (shell injects Paged.js when missing). */
+export function buildPrintHtmlDocument(options: {
+  rootPath: string
+  title: string
+  bodyHtml: string
+  stylesheet: string
+  bodyClass?: string
+}): string {
+  const rootPath = options.rootPath.replace(/\/+$/, '')
+  const title = options.title.trim() || 'Document'
+  const bodyClass = options.bodyClass?.trim()
+  const bodyAttr = bodyClass ? ` class="${escapeHtml(bodyClass)}"` : ''
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>${escapeHtml(title)}</title>
+  <base href="${escapeHtml(fileBaseHref(rootPath))}">
+  <style>${options.stylesheet.trim()}</style>
+</head>
+<body${bodyAttr}>
+${options.bodyHtml}
+</body>
+</html>`
+}

package/src/bridge/pureRender/adapters.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildBookPureRenderRequest,
+  buildWriterPureRenderRequest,
+} from './adapters.js'
+
+describe('Pure Render app adapters', () => {
+  it('maps writer HTML into a writer Pure Render request', () => {
+    const request = buildWriterPureRenderRequest({
+      contentHtml: '<h1>Draft Title</h1><p>Body</p>',
+    })
+
+    expect(request.profile).toBe('writer')
+    expect(request.metadata?.title).toBe('Draft Title')
+    expect(request.html).toBe('<p>Body</p>')
+  })
+
+  it('treats a leading Writer h1 as editor title furniture when app metadata differs', () => {
+    const request = buildWriterPureRenderRequest({
+      contentHtml: '<h1>Editor Title</h1><p>Body</p>',
+      title: 'Workspace Title',
+    })
+
+    expect(request.metadata?.title).toBe('Workspace Title')
+    expect(request.html).toBe('<p>Body</p>')
+  })
+
+  it('unwraps the Writer editor article before Pure Render validation', () => {
+    const request = buildWriterPureRenderRequest({
+      contentHtml:
+        '<article class="ps-writer-document"><h1>Untitled</h1><p>Body</p></article>',
+    })
+
+    expect(request.metadata?.title).toBe('Untitled')
+    expect(request.html).toBe('<p>Body</p>')
+  })
+
+  it('maps book chapters into chapter sections with a generated TOC', () => {
+    const request = buildBookPureRenderRequest({
+      title: 'The Book',
+      author: 'A. Writer',
+      chapters: [
+        { title: 'One', html: '<h1>One</h1><p>Body</p>', matter: 'body' },
+        { title: 'Two', html: '<p>More</p>', matter: 'body' },
+      ],
+    })
+
+    expect(request.profile).toBe('book')
+    expect(request.metadata).toMatchObject({
+      title: 'The Book',
+      authorsText: 'A. Writer',
+    })
+    expect(request.html).toContain('data-type="toc"')
+    expect(request.html).toContain('<a href="#one">One</a>')
+    expect(request.html).toContain('<a href="#two">Two</a>')
+    expect(request.html).toContain('data-type="chapter"')
+    expect(request.html).toContain('<h2 id="one">One</h2>')
+    expect(request.html).toContain('<h2 id="two">Two</h2>')
+    expect(request.html).toContain('<p>Body</p>')
+  })
+
+  it('does not generate a duplicate TOC when book content already includes one', () => {
+    const request = buildBookPureRenderRequest({
+      title: 'The Book',
+      chapters: [
+        {
+          title: 'Contents',
+          html: '<ol><li>Existing</li></ol>',
+          matter: 'frontmatter',
+          role: 'toc',
+        },
+        { title: 'One', html: '<p>Body</p>', matter: 'body' },
+      ],
+    })
+
+    expect(request.html.match(/data-type="toc"/g)).toHaveLength(1)
+    expect(request.html).not.toContain('<a href="#one">One</a>')
+  })
+
+  it('maps book references role into references backmatter', () => {
+    const request = buildBookPureRenderRequest({
+      title: 'The Book',
+      chapters: [
+        { title: 'One', html: '<p>Body</p>', matter: 'body' },
+        {
+          title: 'References',
+          html: '<ol><li>Reference one.</li></ol>',
+          matter: 'backmatter',
+          role: 'references',
+        },
+      ],
+    })
+
+    expect(request.html).toContain(
+      '<section data-type="references" data-role="references">',
+    )
+    expect(request.html).toContain('<h2 id="references">References</h2>')
+    expect(request.html).toContain('<li>Reference one.</li>')
+    expect(request.html).not.toContain('<a href="#references">References</a>')
+  })
+
+  it('maps acknowledgments role into canonical acknowledgments matter', () => {
+    const request = buildBookPureRenderRequest({
+      title: 'The Book',
+      chapters: [
+        {
+          title: 'Acknowledgments',
+          html: '<p>Thanks.</p>',
+          matter: 'backmatter',
+          role: 'acknowledgments',
+        },
+      ],
+    })
+
+    expect(request.html).toContain(
+      '<section data-type="acknowledgments" data-role="acknowledgments">',
+    )
+    expect(request.html).toContain('<p>Thanks.</p>')
+  })
+
+  it('maps appendix role into canonical appendix backmatter outside the generated TOC', () => {
+    const request = buildBookPureRenderRequest({
+      title: 'The Book',
+      chapters: [
+        { title: 'One', html: '<p>Body</p>', matter: 'body' },
+        {
+          title: 'Appendix: Data',
+          html: '<p>Supplemental.</p>',
+          matter: 'backmatter',
+          role: 'appendix',
+        },
+      ],
+    })
+
+    expect(request.html).toContain(
+      '<section data-type="appendix" data-role="appendix">',
+    )
+    expect(request.html).toContain('<h2 id="appendix-data">Appendix: Data</h2>')
+    expect(request.html).toContain('<p>Supplemental.</p>')
+    expect(request.html).not.toContain(
+      '<a href="#appendix-data">Appendix: Data</a>',
+    )
+  })
+})