@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.9

package/src/components/print-design/index.ts

@@ -6,4 +6,6 @@ export {
   type PrintDesignPanelProps,
   type PrintDesignThemePreset,
   type PrintDesignPopoverProps,
+  type PrintDesignPreviewDocument,
 } from './PrintDesignPanel.js'
+export { printPreviewDocumentFromHtml } from './previewContent.js'

package/src/components/print-design/previewContent.test.ts

@@ -0,0 +1,32 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from 'vitest'
+import { printPreviewDocumentFromHtml } from './previewContent.js'
+
+describe('printPreviewDocumentFromHtml', () => {
+  it('extracts the heading and running paragraphs, skipping stubs', () => {
+    const result = printPreviewDocumentFromHtml(
+      '<h1>Designing for Emergent Workflow Cultures</h1>' +
+        '<p>Short.</p>' +
+        '<p>Scholarly publishing is evolving, and there is a need to understand and design the new emergent workflows.</p>' +
+        '<p>This article documents an ongoing collaboration to develop technology to meet emergent workflows in scholarly publishing.</p>',
+    )
+    expect(result.title).toBe('Designing for Emergent Workflow Cultures')
+    expect(result.paragraphs).toHaveLength(2)
+    expect(result.paragraphs?.[0]).toContain('Scholarly publishing is evolving')
+  })
+
+  it('prefers a supplied title/byline and caps paragraphs at four', () => {
+    const paragraphs = Array.from(
+      { length: 6 },
+      (_, index) =>
+        `<p>Paragraph number ${index} padded well past the forty character minimum length.</p>`,
+    ).join('')
+    const result = printPreviewDocumentFromHtml(`<h1>Ignored</h1>${paragraphs}`, {
+      title: 'Chosen Title',
+      byline: 'A. Author',
+    })
+    expect(result.title).toBe('Chosen Title')
+    expect(result.byline).toBe('A. Author')
+    expect(result.paragraphs).toHaveLength(4)
+  })
+})

package/src/components/print-design/previewContent.ts

@@ -0,0 +1,31 @@
+import type { PrintDesignPreviewDocument } from './PrintDesignPanel.js'
+
+/**
+ * Derive the live-preview excerpt from a host document's HTML: the first
+ * heading as title (unless the host supplies one) and the first few real
+ * paragraphs. Keeps the PDF Typesetter preview showing the USER'S content
+ * instead of sample copy.
+ */
+export function printPreviewDocumentFromHtml(
+  html: string,
+  options: { title?: string; byline?: string } = {},
+): PrintDesignPreviewDocument {
+  const doc = new DOMParser().parseFromString(html || '', 'text/html')
+  const title =
+    options.title?.trim() ||
+    doc.body.querySelector('h1, h2')?.textContent?.replace(/\s+/g, ' ').trim() ||
+    undefined
+  const paragraphs: string[] = []
+  for (const paragraph of Array.from(doc.body.querySelectorAll('p'))) {
+    const text = paragraph.textContent?.replace(/\s+/g, ' ').trim() ?? ''
+    // Skip stubs/captions; the preview wants running text.
+    if (text.length < 40) continue
+    paragraphs.push(text)
+    if (paragraphs.length >= 4) break
+  }
+  return {
+    ...(title ? { title } : {}),
+    ...(options.byline?.trim() ? { byline: options.byline.trim() } : {}),
+    paragraphs,
+  }
+}

package/src/context/buildContextDocument.test.ts

@@ -0,0 +1,240 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  buildContextDocument,
+  metadataMarkdown,
+  type PlatformContextBuildIo,
+} from './buildContextDocument.js'
+import { parseContextDocument } from './contextDocument.js'
+import type { PlatformAppContextManifest } from './contextConfig.js'
+
+function fakeIo(files: Record<string, string>, dirs: Record<string, string[]> = {}): PlatformContextBuildIo {
+  return {
+    async readTextFile(path) {
+      const content = files[path]
+      if (content === undefined) throw new Error(`ENOENT: ${path}`)
+      return content
+    },
+    async listFiles(dirPath) {
+      return dirs[dirPath] ?? []
+    },
+  }
+}
+
+const MANUSCRIPT_CONFIG: PlatformAppContextManifest = {
+  kind: 'manuscript',
+  packageSuffix: '.manuscript',
+  manifestFile: 'manuscript.json',
+  content: [{ file: 'manuscript.html', section: 'Body' }],
+  assetsDir: 'assets',
+  titlePath: 'title',
+}
+
+const BOOK_CONFIG: PlatformAppContextManifest = {
+  kind: 'book',
+  packageSuffix: '.book',
+  manifestFile: 'book.yaml',
+  content: [
+    { fromManifestList: 'frontMatter', baseDir: 'chapters' },
+    { fromManifestList: 'chapters', baseDir: 'chapters' },
+  ],
+  assetsDir: 'assets',
+  titlePath: 'title',
+  idPath: 'id',
+}
+
+describe('buildContextDocument (manuscript-shaped package)', () => {
+  const packagePath = '/work/MyPaper.manuscript'
+  const io = fakeIo(
+    {
+      '/work/MyPaper.manuscript/manuscript.json': JSON.stringify({
+        title: 'Effects of X on Y',
+        authors: [{ name: 'A. Author' }],
+        abstract: 'Short abstract.',
+        keywords: ['x', 'y'],
+      }),
+      '/work/MyPaper.manuscript/manuscript.html':
+        '<h2>Introduction</h2><p>Hello <strong>world</strong>.</p>',
+    },
+    {
+      '/work/MyPaper.manuscript/assets': ['fig-01.png', 'diagrams/flow.svg'],
+    },
+  )
+
+  it('produces a parseable document with full content and metadata', async () => {
+    const result = await buildContextDocument(
+      {
+        appSlug: 'manuscript',
+        packagePath,
+        config: MANUSCRIPT_CONFIG,
+        generator: 'on-access',
+        generatedAt: '2026-07-02T10:00:00.000Z',
+        sourceHash: 'sha256:abc',
+      },
+      io,
+    )
+    expect(result.fileName).toBe('MyPaper.manuscript.md')
+    const parsed = parseContextDocument(result.raw)
+    expect(parsed.envelope.title).toBe('Effects of X on Y')
+    expect(parsed.envelope.appSlug).toBe('manuscript')
+    expect(parsed.envelope.objectId).toBe('MyPaper')
+    expect(parsed.envelope.source.contentFiles).toEqual(['manuscript.html'])
+    expect(parsed.body).toContain('# Effects of X on Y')
+    expect(parsed.body).toContain('- **abstract:** Short abstract.')
+    expect(parsed.body).toContain('## Body')
+    expect(parsed.body).toContain('Hello **world**.')
+    // Content headings nest inside the section wrapper (h2 -> ###).
+    expect(parsed.body).toContain('### Introduction')
+    expect(parsed.body).not.toContain('\n## Introduction')
+  })
+
+  it('links assets with durable relative paths and kinds', async () => {
+    const result = await buildContextDocument(
+      {
+        appSlug: 'manuscript',
+        packagePath,
+        config: MANUSCRIPT_CONFIG,
+        generator: 'on-access',
+        generatedAt: '2026-07-02T10:00:00.000Z',
+      },
+      io,
+    )
+    expect(result.document.envelope.links).toEqual([
+      { relativePath: 'assets/diagrams/flow.svg', kind: 'vector' },
+      { relativePath: 'assets/fig-01.png', kind: 'image' },
+    ])
+    expect(result.document.body).toContain(
+      '- [fig-01.png](assets/fig-01.png) (image)',
+    )
+  })
+
+  it('is deterministic for a fixed timestamp', async () => {
+    const request = {
+      appSlug: 'manuscript',
+      packagePath,
+      config: MANUSCRIPT_CONFIG,
+      generator: 'on-access' as const,
+      generatedAt: '2026-07-02T10:00:00.000Z',
+    }
+    const first = await buildContextDocument(request, io)
+    const second = await buildContextDocument(request, io)
+    expect(first.raw).toBe(second.raw)
+  })
+
+  it('indexes sections including per-chapter headings', async () => {
+    const result = await buildContextDocument(
+      {
+        appSlug: 'manuscript',
+        packagePath,
+        config: MANUSCRIPT_CONFIG,
+        generator: 'on-access',
+        generatedAt: '2026-07-02T10:00:00.000Z',
+      },
+      io,
+    )
+    const ids = result.document.envelope.sections.map(section => section.id)
+    expect(ids).toContain('metadata')
+    expect(ids).toContain('body')
+    expect(ids).toContain('assets')
+  })
+
+  it('marks missing content files instead of failing', async () => {
+    const brokenIo = fakeIo({
+      '/work/MyPaper.manuscript/manuscript.json': JSON.stringify({ title: 'T' }),
+    })
+    const result = await buildContextDocument(
+      {
+        appSlug: 'manuscript',
+        packagePath,
+        config: MANUSCRIPT_CONFIG,
+        generator: 'on-access',
+        generatedAt: '2026-07-02T10:00:00.000Z',
+      },
+      brokenIo,
+    )
+    expect(result.document.body).toContain(
+      '*Missing content file: manuscript.html*',
+    )
+  })
+
+  it('throws when the package manifest is unreadable', async () => {
+    await expect(
+      buildContextDocument(
+        {
+          appSlug: 'manuscript',
+          packagePath: '/work/Nope.manuscript',
+          config: MANUSCRIPT_CONFIG,
+          generator: 'on-access',
+          generatedAt: '2026-07-02T10:00:00.000Z',
+        },
+        io,
+      ),
+    ).rejects.toThrow(/ENOENT/)
+  })
+})
+
+describe('buildContextDocument (book-shaped package with manifest lists)', () => {
+  const packagePath = '/work/MyBook.book'
+  const io = fakeIo(
+    {
+      '/work/MyBook.book/book.yaml': [
+        'schema: 1',
+        'id: book-42',
+        'title: My Book',
+        'author: A. Writer',
+        'frontMatter:',
+        '  - file: preface.html',
+        '    title: Preface',
+        'chapters:',
+        '  - file: ch1.html',
+        '    title: Chapter One',
+        '  - file: ch2.html',
+        'render:',
+        '  pageSize: A5',
+        '  margins: normal',
+      ].join('\n'),
+      '/work/MyBook.book/chapters/preface.html': '<p>Preface text.</p>',
+      '/work/MyBook.book/chapters/ch1.html': '<p>One.</p>',
+      '/work/MyBook.book/chapters/ch2.html': '<p>Two.</p>',
+    },
+  )
+
+  it('orders chapters from the manifest lists and titles sections', async () => {
+    const result = await buildContextDocument(
+      {
+        appSlug: 'book',
+        packagePath,
+        config: BOOK_CONFIG,
+        generator: 'on-access',
+        generatedAt: '2026-07-02T10:00:00.000Z',
+      },
+      io,
+    )
+    expect(result.contentFiles).toEqual([
+      'chapters/preface.html',
+      'chapters/ch1.html',
+      'chapters/ch2.html',
+    ])
+    expect(result.document.envelope.objectId).toBe('book-42')
+    const body = result.document.body
+    expect(body.indexOf('## Preface')).toBeGreaterThan(-1)
+    expect(body.indexOf('## Chapter One')).toBeGreaterThan(
+      body.indexOf('## Preface'),
+    )
+    expect(body).toContain('## ch2')
+  })
+})
+
+describe('metadataMarkdown', () => {
+  it('renders nested records and arrays', () => {
+    const lines = metadataMarkdown({
+      title: 'T',
+      authors: [{ name: 'A' }],
+      keywords: ['x', 'y'],
+    })
+    expect(lines).toContain('- **title:** T')
+    expect(lines).toContain('- **authors:**')
+    expect(lines).toContain('    - **name:** A')
+    expect(lines).toContain('  - x')
+  })
+})

package/src/context/buildContextDocument.ts

@@ -0,0 +1,309 @@
+/**
+ * Generic, config-driven context document builder.
+ *
+ * One implementation with injectable IO so the shell can generate headless
+ * (node fs) and apps can generate on save (bridge fs) with byte-identical
+ * output. App schema comes declaratively from the `app.context` manifest
+ * block — no app-specific logic lives here or in the shell.
+ */
+
+import { parse as parseYaml } from 'yaml'
+
+import {
+  serializeContextDocument,
+  type PlatformContextDocument,
+  type PlatformContextGenerator,
+  type PlatformContextLink,
+  PLATFORM_CONTEXT_SCHEMA_VERSION,
+  contextFileName,
+} from './contextDocument.js'
+import { buildContextSections } from './contextSections.js'
+import {
+  contextLinkKindForFile,
+  manifestStringAt,
+  type PlatformAppContextManifest,
+} from './contextConfig.js'
+import { htmlToContextMarkdown } from './htmlToContextMarkdown.js'
+
+/** IO surface the builder needs — node fs in the shell, bridge fs in apps. */
+export interface PlatformContextBuildIo {
+  readTextFile(path: string): Promise<string>
+  /** Recursive relative file listing of a directory; [] when missing. */
+  listFiles(dirPath: string): Promise<string[]>
+}
+
+export interface PlatformContextBuildRequest {
+  appSlug: string
+  /** Absolute path of the package folder (the assets collectionPath). */
+  packagePath: string
+  config: PlatformAppContextManifest
+  generator: PlatformContextGenerator
+  /** Injected ISO timestamp — callers stamp so output stays deterministic. */
+  generatedAt: string
+  /** Hash of manifest + content files, computed by the caller. */
+  sourceHash?: string
+}
+
+export interface PlatformContextBuildResult {
+  document: PlatformContextDocument
+  /** Serialized on-disk form. */
+  raw: string
+  /** Canonical context file name, `<packageBase>.<kind>.md`. */
+  fileName: string
+  /** Content file paths (relative to the package) the body derived from. */
+  contentFiles: string[]
+}
+
+interface ResolvedContentEntry {
+  relativePath: string
+  sectionTitle: string
+}
+
+function baseName(path: string): string {
+  const trimmed = path.replace(/[\\/]+$/, '')
+  const separator = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'))
+  return separator >= 0 ? trimmed.slice(separator + 1) : trimmed
+}
+
+function packageBaseName(packagePath: string, packageSuffix: string): string {
+  const name = baseName(packagePath)
+  return name.endsWith(packageSuffix)
+    ? name.slice(0, -packageSuffix.length)
+    : name
+}
+
+function joinPath(...parts: string[]): string {
+  return parts
+    .filter(part => part.length > 0)
+    .join('/')
+    .replace(/\/{2,}/g, '/')
+}
+
+function parseManifestText(fileName: string, text: string): unknown {
+  if (/\.ya?ml$/i.test(fileName)) return parseYaml(text)
+  return JSON.parse(text)
+}
+
+function titleForFile(relativePath: string): string {
+  const name = baseName(relativePath)
+  return name.replace(/\.[^.]+$/, '').replace(/\.(doc|report|research)$/, '')
+}
+
+/** Render parsed manifest data as a readable markdown list. */
+export function metadataMarkdown(value: unknown, depth = 0): string[] {
+  const indent = '  '.repeat(depth)
+  if (Array.isArray(value)) {
+    return value.flatMap(entry => {
+      if (entry !== null && typeof entry === 'object') {
+        const nested = metadataMarkdown(entry, depth + 1)
+        return [`${indent}-`, ...nested]
+      }
+      return [`${indent}- ${formatScalar(entry)}`]
+    })
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.entries(value as Record<string, unknown>).flatMap(
+      ([key, entry]) => {
+        if (entry === null || entry === undefined) return []
+        if (typeof entry === 'object') {
+          const nested = metadataMarkdown(entry, depth + 1)
+          if (nested.length === 0) return []
+          return [`${indent}- **${key}:**`, ...nested]
+        }
+        return [`${indent}- **${key}:** ${formatScalar(entry)}`]
+      },
+    )
+  }
+  return [`${indent}- ${formatScalar(value)}`]
+}
+
+function formatScalar(value: unknown): string {
+  if (typeof value === 'string') return value.replace(/\s+/g, ' ').trim()
+  return String(value)
+}
+
+function resolveContentEntries(
+  config: PlatformAppContextManifest,
+  manifest: unknown,
+): ResolvedContentEntry[] {
+  const entries: ResolvedContentEntry[] = []
+  for (const source of config.content) {
+    if (source.file) {
+      entries.push({
+        relativePath: source.file,
+        sectionTitle: source.section ?? titleForFile(source.file),
+      })
+      continue
+    }
+    if (!source.fromManifestList) continue
+    const listValue =
+      manifest && typeof manifest === 'object'
+        ? (manifest as Record<string, unknown>)[source.fromManifestList]
+        : undefined
+    if (!Array.isArray(listValue)) continue
+    const pathKey = source.pathKey ?? 'file'
+    const titleKey = source.titleKey ?? 'title'
+    for (const item of listValue) {
+      if (item === null || typeof item !== 'object') continue
+      const record = item as Record<string, unknown>
+      const file = record[pathKey]
+      if (typeof file !== 'string' || file.trim().length === 0) continue
+      const relativePath = source.baseDir
+        ? joinPath(source.baseDir, file.trim())
+        : file.trim()
+      const title = record[titleKey]
+      entries.push({
+        relativePath,
+        sectionTitle:
+          typeof title === 'string' && title.trim().length > 0
+            ? title.trim()
+            : titleForFile(relativePath),
+      })
+    }
+  }
+  return entries
+}
+
+/**
+ * Demote markdown headings so converted content nests *inside* its `##`
+ * section wrapper (minimum content heading level becomes 3). Without this a
+ * content `<h2>` would terminate the wrapper section and break segmented
+ * reads. Fenced code blocks are left untouched.
+ */
+export function nestContentHeadings(markdown: string): string {
+  const lines = markdown.split('\n')
+  let fence: string | null = null
+  let minLevel = Number.POSITIVE_INFINITY
+  const levels: (number | null)[] = lines.map(line => {
+    const fenceMatch = /^(```|~~~)/.exec(line.trimStart())
+    if (fenceMatch) {
+      if (fence === null) fence = fenceMatch[1]
+      else if (line.trimStart().startsWith(fence)) fence = null
+      return null
+    }
+    if (fence !== null) return null
+    const match = /^(#{1,6})\s/.exec(line)
+    if (!match) return null
+    minLevel = Math.min(minLevel, match[1].length)
+    return match[1].length
+  })
+  if (!Number.isFinite(minLevel) || minLevel >= 3) return markdown
+  const shift = 3 - minLevel
+  return lines
+    .map((line, index) => {
+      const level = levels[index]
+      if (level === null) return line
+      const next = Math.min(6, level + shift)
+      return `${'#'.repeat(next)}${line.slice(level)}`
+    })
+    .join('\n')
+}
+
+async function contentSectionMarkdown(
+  entry: ResolvedContentEntry,
+  packagePath: string,
+  io: PlatformContextBuildIo,
+): Promise<string[]> {
+  let text: string
+  try {
+    text = await io.readTextFile(joinPath(packagePath, entry.relativePath))
+  } catch {
+    return [`## ${entry.sectionTitle}`, '', `*Missing content file: ${entry.relativePath}*`]
+  }
+  const lower = entry.relativePath.toLowerCase()
+  if (lower.endsWith('.html') || lower.endsWith('.htm')) {
+    return [
+      `## ${entry.sectionTitle}`,
+      '',
+      nestContentHeadings(htmlToContextMarkdown(text).trimEnd()),
+    ]
+  }
+  if (lower.endsWith('.md') || lower.endsWith('.markdown') || lower.endsWith('.txt')) {
+    return [`## ${entry.sectionTitle}`, '', nestContentHeadings(text.trim())]
+  }
+  const fence = lower.endsWith('.json')
+    ? 'json'
+    : /\.ya?ml$/.test(lower)
+      ? 'yaml'
+      : ''
+  return [`## ${entry.sectionTitle}`, '', `\`\`\`${fence}`, text.trim(), '```']
+}
+
+/**
+ * Build the full context document for one package object.
+ * Throws when the package manifest cannot be read or parsed.
+ */
+export async function buildContextDocument(
+  request: PlatformContextBuildRequest,
+  io: PlatformContextBuildIo,
+): Promise<PlatformContextBuildResult> {
+  const { config, packagePath } = request
+  const manifestText = await io.readTextFile(
+    joinPath(packagePath, config.manifestFile),
+  )
+  const manifest = parseManifestText(config.manifestFile, manifestText)
+  const base = packageBaseName(packagePath, config.packageSuffix)
+  const title = manifestStringAt(manifest, config.titlePath ?? 'title') ?? base
+  const objectId = manifestStringAt(manifest, config.idPath) ?? base
+
+  const contentEntries = resolveContentEntries(config, manifest)
+  const bodyParts: string[] = [`# ${title}`, '']
+
+  const metadataLines = metadataMarkdown(manifest)
+  if (metadataLines.length > 0) {
+    bodyParts.push('## Metadata', '', ...metadataLines, '')
+  }
+
+  for (const entry of contentEntries) {
+    bodyParts.push(...(await contentSectionMarkdown(entry, packagePath, io)), '')
+  }
+
+  const links: PlatformContextLink[] = []
+  if (config.assetsDir) {
+    const assetFiles = await io.listFiles(joinPath(packagePath, config.assetsDir))
+    for (const file of [...assetFiles].sort()) {
+      links.push({
+        relativePath: joinPath(config.assetsDir, file),
+        kind: contextLinkKindForFile(file),
+      })
+    }
+  }
+  if (links.length > 0) {
+    bodyParts.push(
+      '## Assets',
+      '',
+      ...links.map(
+        link => `- [${baseName(link.relativePath)}](${link.relativePath}) (${link.kind})`,
+      ),
+      '',
+    )
+  }
+
+  const body = `${bodyParts.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`
+  const document: PlatformContextDocument = {
+    envelope: {
+      schemaVersion: PLATFORM_CONTEXT_SCHEMA_VERSION,
+      kind: config.kind,
+      appSlug: request.appSlug,
+      objectId,
+      title,
+      source: {
+        path: packagePath,
+        manifestFile: config.manifestFile,
+        contentFiles: contentEntries.map(entry => entry.relativePath),
+      },
+      ...(request.sourceHash ? { sourceHash: request.sourceHash } : {}),
+      generatedAt: request.generatedAt,
+      generator: request.generator,
+      links,
+      sections: buildContextSections(body),
+    },
+    body,
+  }
+  return {
+    document,
+    raw: serializeContextDocument(document),
+    fileName: contextFileName(base, config.kind),
+    contentFiles: contentEntries.map(entry => entry.relativePath),
+  }
+}

package/src/context/contextAccess.ts

@@ -0,0 +1,66 @@
+/**
+ * Request/result contracts for the `context.*` bridge namespace
+ * (`context.resolve`, `context.read`, `context.search`).
+ *
+ * One backing implementation serves both the human context picker and the
+ * built-in agent tool — human-picked and agent-picked context are identical.
+ */
+
+import type { PlatformContextEnvelope } from './contextDocument.js'
+
+/**
+ * Reference to one context object. Provide `path` (any path on or inside the
+ * package folder) or `appSlug` + `objectId`.
+ */
+export interface PlatformContextRef {
+  path?: string
+  appSlug?: string
+  objectId?: string
+}
+
+export interface PlatformContextResolveResult {
+  appSlug: string
+  kind: string
+  objectId: string
+  title: string
+  /** Absolute package folder path (the assets collectionPath). */
+  packagePath: string
+  /** Absolute path of the `<name>.<kind>.md` context file. */
+  contextPath: string
+  envelope: PlatformContextEnvelope
+  /** True when this call generated or refreshed the file. */
+  regenerated: boolean
+}
+
+export interface PlatformContextReadRequest extends PlatformContextRef {
+  /** Durable section id for a segmented read (see envelope.sections). */
+  section?: string
+}
+
+export interface PlatformContextReadResult extends PlatformContextResolveResult {
+  /** Full document markdown, or just the requested section's markdown. */
+  markdown: string
+  /** Echoes the section id when a segmented read was served. */
+  section?: string
+}
+
+export interface PlatformContextSearchRequest {
+  query: string
+  /** Restrict to object kinds, e.g. ['manuscript', 'book']. */
+  kinds?: string[]
+  /** Restrict to one app's objects. */
+  appSlug?: string
+  /** Max hits (default 12). */
+  limit?: number
+}
+
+export interface PlatformContextSearchHit {
+  appSlug: string
+  kind: string
+  title: string
+  packagePath: string
+  /** Canonical context file path (may not exist yet — resolve generates). */
+  contextPath: string
+  /** True when the context file already exists on disk. */
+  hasContext: boolean
+}