@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.9

package/src/context/htmlToContextMarkdown.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest'
+
+import { htmlToContextMarkdown } from './htmlToContextMarkdown.js'
+
+describe('htmlToContextMarkdown', () => {
+  it('converts headings and paragraphs', () => {
+    expect(
+      htmlToContextMarkdown('<h1>Title</h1><p>Hello <strong>world</strong>.</p>'),
+    ).toBe('# Title\n\nHello **world**.\n')
+  })
+
+  it('keeps inline marks in headings', () => {
+    expect(htmlToContextMarkdown('<h2>My <em>Title</em></h2>')).toBe(
+      '## My *Title*\n',
+    )
+  })
+
+  it('converts links', () => {
+    expect(
+      htmlToContextMarkdown('<p>See <a href="https://x.test/a">the paper</a>.</p>'),
+    ).toBe('See [the paper](https://x.test/a).\n')
+  })
+
+  it('prefers the durable collection asset src for images', () => {
+    expect(
+      htmlToContextMarkdown(
+        '<p><img src="blob:ephemeral" data-collection-asset-src="assets/fig-01.png" alt="Figure 1"></p>',
+      ),
+    ).toBe('![Figure 1](assets/fig-01.png)\n')
+  })
+
+  it('drops data: image payloads', () => {
+    expect(
+      htmlToContextMarkdown('<p><img src="data:image/png;base64,AAAA" alt="P"></p>'),
+    ).toBe('![P]()\n')
+  })
+
+  it('converts unordered and ordered lists', () => {
+    expect(
+      htmlToContextMarkdown(
+        '<ul><li><p>One</p></li><li><p>Two</p></li></ul>',
+      ),
+    ).toBe('- One\n- Two\n')
+    expect(
+      htmlToContextMarkdown('<ol><li><p>First</p></li><li><p>Second</p></li></ol>'),
+    ).toBe('1. First\n2. Second\n')
+  })
+
+  it('nests lists with indentation', () => {
+    expect(
+      htmlToContextMarkdown('<ul><li>A<ul><li>B</li></ul></li></ul>'),
+    ).toBe('- A\n  - B\n')
+  })
+
+  it('converts blockquotes', () => {
+    expect(
+      htmlToContextMarkdown('<blockquote><p>Quoted</p></blockquote>'),
+    ).toBe('> Quoted\n')
+  })
+
+  it('converts pre/code with language to fenced blocks', () => {
+    expect(
+      htmlToContextMarkdown(
+        '<pre><code class="language-js">const a = 1;\n</code></pre>',
+      ),
+    ).toBe('```js\nconst a = 1;\n```\n')
+  })
+
+  it('converts inline code', () => {
+    expect(htmlToContextMarkdown('<p>Run <code>npm test</code>.</p>')).toBe(
+      'Run `npm test`.\n',
+    )
+  })
+
+  it('converts mermaid figures to mermaid fences', () => {
+    expect(
+      htmlToContextMarkdown(
+        '<figure data-type="mermaid"><code class="language-mermaid">graph TD</code></figure>',
+      ),
+    ).toBe('```mermaid\ngraph TD\n```\n')
+  })
+
+  it('converts block math via data-latex', () => {
+    expect(
+      htmlToContextMarkdown(
+        '<span data-type="block-math" data-latex="E=mc^2"></span>',
+      ),
+    ).toBe('$$E=mc^2$$\n')
+  })
+
+  it('converts tables to GFM', () => {
+    expect(
+      htmlToContextMarkdown(
+        '<table><tr><th>A</th><th>B</th></tr><tr><td>1</td><td>2</td></tr></table>',
+      ),
+    ).toBe('| A | B |\n| --- | --- |\n| 1 | 2 |\n')
+  })
+
+  it('decodes entities', () => {
+    expect(htmlToContextMarkdown('<p>a &amp; b &lt;c&gt; &#8212;</p>')).toBe(
+      'a & b <c> —\n',
+    )
+  })
+
+  it('skips script and style content', () => {
+    expect(
+      htmlToContextMarkdown('<p>Hi</p><script>ignored()</script><p>Bye</p>'),
+    ).toBe('Hi\n\nBye\n')
+  })
+
+  it('renders figcaptions as emphasis', () => {
+    expect(
+      htmlToContextMarkdown(
+        '<figure><img data-collection-asset-src="assets/a.png" alt="A"><figcaption>Caption text</figcaption></figure>',
+      ),
+    ).toBe('![A](assets/a.png)\n\n*Caption text*\n')
+  })
+
+  it('converts hard breaks inside paragraphs', () => {
+    expect(htmlToContextMarkdown('<p>Line one<br>Line two</p>')).toBe(
+      'Line one\nLine two\n',
+    )
+  })
+
+  it('converts horizontal rules', () => {
+    expect(htmlToContextMarkdown('<p>Above</p><hr><p>Below</p>')).toBe(
+      'Above\n\n---\n\nBelow\n',
+    )
+  })
+
+  it('ignores inter-tag whitespace', () => {
+    expect(htmlToContextMarkdown('<p>A</p>\n  <p>B</p>')).toBe('A\n\nB\n')
+  })
+})

package/src/context/htmlToContextMarkdown.ts

@@ -0,0 +1,369 @@
+/**
+ * Deterministic HTML → markdown conversion for context documents.
+ *
+ * Converts the well-formed HTML that suite apps persist (TipTap-style output)
+ * into readable markdown. Intentionally DOM-free (regex tokenizer + stack) so
+ * it runs identically in app iframes and in a headless shell process.
+ *
+ * Not a general-purpose sanitizer: input is trusted app-generated HTML.
+ * Binary/image references keep their durable relative paths
+ * (`data-collection-asset-src` wins over `src`); `data:` URLs are dropped —
+ * context files link binaries, never embed them.
+ */
+
+const VOID_TAGS = new Set(['br', 'hr', 'img', 'input', 'meta', 'link', 'source', 'wbr', 'col', 'embed', 'area', 'base', 'track'])
+const SKIP_TAGS = new Set(['script', 'style', 'head', 'title', 'meta', 'link', 'template'])
+const TRANSPARENT_TAGS = new Set(['div', 'span', 'section', 'article', 'main', 'header', 'footer', 'aside', 'nav', 'body', 'html', 'u', 'mark', 'small', 'sub', 'sup', 'font', 'colgroup', 'col', 'tbody', 'thead', 'tfoot'])
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  mdash: '—',
+  ndash: '–',
+  hellip: '…',
+  rsquo: '’',
+  lsquo: '‘',
+  rdquo: '”',
+  ldquo: '“',
+}
+
+interface ListFrame {
+  type: 'ul' | 'ol'
+  index: number
+  itemBlockEmitted: boolean
+}
+
+interface TableState {
+  rows: string[][]
+  headerRows: number
+  currentRow: string[] | null
+  inHeader: boolean
+}
+
+interface Converter {
+  out: string[]
+  inline: string
+  linkHrefs: string[]
+  quoteDepth: number
+  lists: ListFrame[]
+  table: TableState | null
+  pre: { lang: string; text: string } | null
+  codeFence: { lang: string; text: string } | null
+  skipDepth: number
+}
+
+function decodeEntities(text: string): string {
+  return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, entity: string) => {
+    if (entity.startsWith('#x') || entity.startsWith('#X')) {
+      const code = Number.parseInt(entity.slice(2), 16)
+      return Number.isNaN(code) ? whole : String.fromCodePoint(code)
+    }
+    if (entity.startsWith('#')) {
+      const code = Number.parseInt(entity.slice(1), 10)
+      return Number.isNaN(code) ? whole : String.fromCodePoint(code)
+    }
+    return NAMED_ENTITIES[entity] ?? whole
+  })
+}
+
+function readAttributes(tag: string): Record<string, string> {
+  const attrs: Record<string, string> = {}
+  const pattern = /([a-zA-Z][-\w:]*)\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+))/g
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(tag)) !== null) {
+    attrs[match[1].toLowerCase()] = decodeEntities(match[3] ?? match[4] ?? match[5] ?? '')
+  }
+  return attrs
+}
+
+function currentList(state: Converter): ListFrame | null {
+  return state.lists.length > 0 ? state.lists[state.lists.length - 1] : null
+}
+
+/** Push finished block lines through list + blockquote prefixing into out. */
+function emitBlock(state: Converter, lines: string[]): void {
+  if (lines.length === 0) return
+  let prefixed = lines
+  const list = currentList(state)
+  if (list) {
+    const indent = '  '.repeat(state.lists.length - 1)
+    const marker = list.type === 'ol' ? `${list.index}. ` : '- '
+    const continuation = ' '.repeat(marker.length)
+    prefixed = prefixed.map((line, index) => {
+      if (!list.itemBlockEmitted && index === 0) return `${indent}${marker}${line}`
+      return `${indent}${continuation}${line}`
+    })
+    list.itemBlockEmitted = true
+  }
+  if (state.quoteDepth > 0) {
+    const quote = '> '.repeat(state.quoteDepth)
+    prefixed = prefixed.map(line => `${quote}${line}`.trimEnd())
+  }
+  if (state.out.length > 0) {
+    const separator = list ? null : ''
+    if (separator !== null) state.out.push(separator)
+  }
+  state.out.push(...prefixed)
+}
+
+function flushInline(state: Converter, headingLevel?: number): void {
+  const text = state.inline.replace(/[ \t]+/g, ' ').trim()
+  state.inline = ''
+  if (!text) return
+  if (state.table?.currentRow) {
+    state.table.currentRow.push(text.replace(/\|/g, '\\|'))
+    return
+  }
+  if (headingLevel) {
+    emitBlock(state, [`${'#'.repeat(headingLevel)} ${text}`])
+    return
+  }
+  emitBlock(state, text.split('\n').map(line => line.trim()).filter(Boolean))
+}
+
+function flushTableCell(state: Converter): void {
+  if (!state.table) return
+  const text = state.inline.replace(/[ \t\n]+/g, ' ').trim()
+  state.inline = ''
+  state.table.currentRow?.push(text.replace(/\|/g, '\\|'))
+}
+
+function emitTable(state: Converter): void {
+  const table = state.table
+  state.table = null
+  if (!table || table.rows.length === 0) return
+  const width = Math.max(...table.rows.map(row => row.length))
+  const pad = (row: string[]): string[] => {
+    const cells = [...row]
+    while (cells.length < width) cells.push('')
+    return cells
+  }
+  const [first, ...rest] = table.rows
+  const lines = [
+    `| ${pad(first).join(' | ')} |`,
+    `| ${Array.from({ length: width }, () => '---').join(' | ')} |`,
+    ...rest.map(row => `| ${pad(row).join(' | ')} |`),
+  ]
+  emitBlock(state, lines)
+}
+
+function emitFence(state: Converter, lang: string, text: string): void {
+  const clean = text.replace(/^\n+/, '').replace(/\s+$/, '')
+  emitBlock(state, [`\`\`\`${lang}`, ...clean.split('\n'), '```'])
+}
+
+const HEADING_TAG = /^h([1-6])$/
+
+/** Convert app-persisted HTML into context markdown. */
+export function htmlToContextMarkdown(html: string): string {
+  const state: Converter = {
+    out: [],
+    inline: '',
+    linkHrefs: [],
+    quoteDepth: 0,
+    lists: [],
+    table: null,
+    pre: null,
+    codeFence: null,
+    skipDepth: 0,
+  }
+  const source = html.replace(/<!--[\s\S]*?-->/g, '')
+  const tokens = source.match(/<[^>]+>|[^<]+/g) ?? []
+  const openHeadings: number[] = []
+
+  for (const token of tokens) {
+    if (!token.startsWith('<')) {
+      if (state.skipDepth > 0) continue
+      const text = decodeEntities(token)
+      if (state.pre) state.pre.text += text
+      else if (state.codeFence) state.codeFence.text += text
+      else state.inline += text.replace(/\s+/g, ' ')
+      continue
+    }
+
+    const tagMatch = /^<\s*(\/)?\s*([a-zA-Z][-\w]*)/.exec(token)
+    if (!tagMatch) continue
+    const closing = Boolean(tagMatch[1])
+    const name = tagMatch[2].toLowerCase()
+
+    if (SKIP_TAGS.has(name)) {
+      if (VOID_TAGS.has(name)) continue
+      state.skipDepth = Math.max(0, state.skipDepth + (closing ? -1 : 1))
+      continue
+    }
+    if (state.skipDepth > 0) continue
+
+    if (state.pre) {
+      if (closing && name === 'pre') {
+        const pre = state.pre
+        state.pre = null
+        emitFence(state, pre.lang, pre.text)
+      } else if (!closing && name === 'code') {
+        const lang = /language-([-\w]+)/.exec(readAttributes(token).class ?? '')
+        if (lang) state.pre.lang = lang[1]
+      }
+      continue
+    }
+    if (state.codeFence) {
+      if (closing && name === 'code') {
+        const fence = state.codeFence
+        state.codeFence = null
+        emitFence(state, fence.lang, fence.text)
+      }
+      continue
+    }
+
+    const attrs = closing ? {} : readAttributes(token)
+    const headingMatch = HEADING_TAG.exec(name)
+
+    if (headingMatch) {
+      if (closing) {
+        flushInline(state, openHeadings.pop())
+      } else {
+        flushInline(state)
+        openHeadings.push(Number(headingMatch[1]))
+      }
+      continue
+    }
+
+    switch (name) {
+      case 'p':
+        flushInline(state)
+        break
+      case 'br':
+        state.inline += '\n'
+        break
+      case 'hr':
+        flushInline(state)
+        emitBlock(state, ['---'])
+        break
+      case 'strong':
+      case 'b':
+        state.inline += '**'
+        break
+      case 'em':
+      case 'i':
+        state.inline += '*'
+        break
+      case 's':
+      case 'del':
+      case 'strike':
+        state.inline += '~~'
+        break
+      case 'code':
+        if (!closing) {
+          const lang = /language-([-\w]+)/.exec(attrs.class ?? '')
+          if (lang) {
+            flushInline(state)
+            state.codeFence = { lang: lang[1], text: '' }
+          } else {
+            state.inline += '`'
+          }
+        } else {
+          state.inline += '`'
+        }
+        break
+      case 'pre':
+        if (!closing) {
+          flushInline(state)
+          state.pre = { lang: '', text: '' }
+        }
+        break
+      case 'a':
+        if (!closing) {
+          state.linkHrefs.push(attrs.href ?? '')
+          state.inline += '['
+        } else {
+          const href = state.linkHrefs.pop() ?? ''
+          state.inline += `](${href})`
+        }
+        break
+      case 'img': {
+        const src = attrs['data-collection-asset-src'] ?? attrs.src ?? ''
+        const target = src.startsWith('data:') ? '' : src
+        state.inline += `![${attrs.alt ?? ''}](${target})`
+        break
+      }
+      case 'figure':
+        flushInline(state)
+        break
+      case 'figcaption':
+        if (!closing) flushInline(state)
+        else {
+          const caption = state.inline.replace(/[ \t]+/g, ' ').trim()
+          state.inline = ''
+          if (caption) emitBlock(state, [`*${caption}*`])
+        }
+        break
+      case 'blockquote':
+        flushInline(state)
+        state.quoteDepth = Math.max(0, state.quoteDepth + (closing ? -1 : 1))
+        break
+      case 'ul':
+      case 'ol':
+        flushInline(state)
+        if (!closing) {
+          state.lists.push({ type: name, index: 0, itemBlockEmitted: true })
+        } else {
+          state.lists.pop()
+        }
+        break
+      case 'li': {
+        flushInline(state)
+        const list = currentList(state)
+        if (list && !closing) {
+          list.index += 1
+          list.itemBlockEmitted = false
+        }
+        break
+      }
+      case 'table':
+        flushInline(state)
+        if (!closing) {
+          state.table = { rows: [], headerRows: 0, currentRow: null, inHeader: false }
+        } else {
+          emitTable(state)
+        }
+        break
+      case 'tr':
+        if (!state.table) break
+        if (!closing) state.table.currentRow = []
+        else {
+          if (state.table.currentRow) state.table.rows.push(state.table.currentRow)
+          state.table.currentRow = null
+        }
+        break
+      case 'td':
+      case 'th':
+        if (!state.table) break
+        if (closing) flushTableCell(state)
+        else state.inline = ''
+        break
+      default: {
+        const latex = attrs['data-latex']
+        if (!closing && typeof latex === 'string' && latex.length > 0) {
+          if ((attrs['data-type'] ?? '').includes('block')) {
+            flushInline(state)
+            emitBlock(state, [`$$${latex}$$`])
+          } else {
+            state.inline += `$${latex}$`
+          }
+          break
+        }
+        if (!TRANSPARENT_TAGS.has(name)) {
+          // Unknown elements are transparent: keep their text content.
+        }
+        break
+      }
+    }
+  }
+
+  flushInline(state)
+  if (state.pre) emitFence(state, state.pre.lang, state.pre.text)
+  emitTable(state)
+  return `${state.out.join('\n').replace(/\n{3,}/g, '\n\n').trim()}\n`
+}

package/src/ics/generateIcs.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest'
+import {
+  escapeIcsText,
+  foldIcsLine,
+  generateIcsCalendar,
+  generateIcsEventExport,
+  generateIcsReply,
+} from './generateIcs.js'
+
+const BASE = {
+  uid: 'uid-123@pure.science',
+  timestamp: '2026-07-04T10:00:00.000Z',
+  title: 'Project kickoff',
+  startsAt: '2026-07-10T09:00:00.000Z',
+  endsAt: '2026-07-10T10:00:00.000Z',
+}
+
+describe('generateIcsCalendar', () => {
+  it('emits a valid REQUEST with organizer and attendees', () => {
+    const ics = generateIcsCalendar({
+      ...BASE,
+      method: 'REQUEST',
+      sequence: 1,
+      description: 'Agenda:\n- intro; goals, scope',
+      location: 'Room 4',
+      organizer: { email: 'adam@pure.science', name: 'Adam' },
+      attendees: [
+        { email: 'boss@pure.science', name: 'Boss', rsvp: true, partstat: 'NEEDS-ACTION' },
+      ],
+    })
+
+    expect(ics).toContain('BEGIN:VCALENDAR')
+    expect(ics).toContain('METHOD:REQUEST')
+    expect(ics).toContain('UID:uid-123@pure.science')
+    expect(ics).toContain('SEQUENCE:1')
+    expect(ics).toContain('DTSTART:20260710T090000Z')
+    expect(ics).toContain('DTEND:20260710T100000Z')
+    expect(ics).toContain('DTSTAMP:20260704T100000Z')
+    expect(ics).toContain('SUMMARY:Project kickoff')
+    expect(ics).toContain('DESCRIPTION:Agenda:\\n- intro\\; goals\\, scope')
+    expect(ics).toContain('ORGANIZER;CN=Adam:mailto:adam@pure.science')
+    expect(ics).toContain(
+      'ATTENDEE;CN=Boss;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:mailto:boss@pure.science',
+    )
+    expect(ics.endsWith('END:VCALENDAR\r\n')).toBe(true)
+    // CRLF line endings throughout.
+    expect(ics.includes('\n')).toBe(true)
+    expect(ics.split('\r\n').some(line => line.includes('\n'))).toBe(false)
+  })
+
+  it('emits DATE values for all-day events', () => {
+    const ics = generateIcsCalendar({
+      ...BASE,
+      method: 'REQUEST',
+      allDay: true,
+      startsAt: '2026-07-10',
+      endsAt: '2026-07-11',
+    })
+    expect(ics).toContain('DTSTART;VALUE=DATE:20260710')
+    expect(ics).toContain('DTEND;VALUE=DATE:20260711')
+  })
+
+  it('defaults CANCEL to STATUS:CANCELLED', () => {
+    const ics = generateIcsCalendar({ ...BASE, method: 'CANCEL', sequence: 3 })
+    expect(ics).toContain('METHOD:CANCEL')
+    expect(ics).toContain('STATUS:CANCELLED')
+    expect(ics).toContain('SEQUENCE:3')
+  })
+
+  it('includes RRULE when provided', () => {
+    const ics = generateIcsCalendar({
+      ...BASE,
+      method: 'REQUEST',
+      rrule: 'FREQ=WEEKLY;INTERVAL=2;COUNT=5',
+    })
+    expect(ics).toContain('RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=5')
+  })
+
+  it('rejects invalid dates', () => {
+    expect(() =>
+      generateIcsCalendar({ ...BASE, method: 'REQUEST', startsAt: 'garbage' }),
+    ).toThrow(/Invalid ICS date-time/)
+  })
+
+  it('omits METHOD and forces no STATUS for a plain export (no method)', () => {
+    const ics = generateIcsCalendar({ ...BASE })
+    expect(ics).toContain('BEGIN:VCALENDAR')
+    expect(ics).toContain('END:VCALENDAR')
+    expect(ics).toContain('BEGIN:VEVENT')
+    expect(ics).toContain('END:VEVENT')
+    expect(ics).toContain('SUMMARY:Project kickoff')
+    expect(ics).toContain('DTSTART:20260710T090000Z')
+    expect(ics).toContain('DTEND:20260710T100000Z')
+    expect(ics).not.toContain('METHOD:')
+    expect(ics).not.toContain('STATUS:')
+  })
+})
+
+describe('generateIcsEventExport', () => {
+  it('produces a plain VCALENDAR with the event and no METHOD', () => {
+    const ics = generateIcsEventExport({
+      ...BASE,
+      description: 'Agenda',
+      location: 'Room 4',
+    })
+    expect(ics).toContain('BEGIN:VEVENT')
+    expect(ics).toContain('SUMMARY:Project kickoff')
+    expect(ics).toContain('DTSTART:20260710T090000Z')
+    expect(ics).toContain('LOCATION:Room 4')
+    expect(ics).not.toContain('METHOD:')
+  })
+})
+
+describe('generateIcsReply', () => {
+  it('answers an invite with the attendee partstat and echoed sequence', () => {
+    const ics = generateIcsReply({
+      uid: 'uid-123@pure.science',
+      sequence: 2,
+      timestamp: '2026-07-04T10:00:00.000Z',
+      title: 'Project kickoff',
+      startsAt: '2026-07-10T09:00:00.000Z',
+      endsAt: '2026-07-10T10:00:00.000Z',
+      organizer: { email: 'boss@pure.science' },
+      attendee: { email: 'adam@pure.science', name: 'Adam' },
+      response: 'accepted',
+    })
+    expect(ics).toContain('METHOD:REPLY')
+    expect(ics).toContain('SEQUENCE:2')
+    expect(ics).toContain(
+      'ATTENDEE;CN=Adam;PARTSTAT=ACCEPTED:mailto:adam@pure.science',
+    )
+    expect(ics).toContain('ORGANIZER:mailto:boss@pure.science')
+  })
+})
+
+describe('formatting helpers', () => {
+  it('escapes TEXT values per RFC 5545', () => {
+    expect(escapeIcsText('a,b;c\\d\ne')).toBe('a\\,b\\;c\\\\d\\ne')
+  })
+
+  it('folds long lines with leading-space continuations', () => {
+    const folded = foldIcsLine(`SUMMARY:${'x'.repeat(200)}`)
+    const lines = folded.split('\r\n')
+    expect(lines.length).toBeGreaterThan(2)
+    expect(lines[0]?.length).toBe(75)
+    for (const continuation of lines.slice(1)) {
+      expect(continuation.startsWith(' ')).toBe(true)
+      expect(continuation.length).toBeLessThanOrEqual(75)
+    }
+    // Unfolding restores the original.
+    expect(folded.replace(/\r\n /g, '')).toBe(`SUMMARY:${'x'.repeat(200)}`)
+  })
+})