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

package/src/bridge/pureRender/adapters.ts

@@ -0,0 +1,175 @@
+import { escapeHtml } from '../printDocument.js'
+import type { PureRenderRequest, PureRenderTheme } from './types.js'
+
+export interface WriterPureRenderAdapterOptions {
+  contentHtml: string
+  title?: string
+  theme?: PureRenderTheme
+}
+
+export interface BookPureRenderChapter {
+  title: string
+  html: string
+  matter?: 'frontmatter' | 'body' | 'backmatter'
+  role?: string
+  partTitle?: string
+}
+
+export interface BookPureRenderAdapterOptions {
+  title: string
+  author?: string
+  chapters: readonly BookPureRenderChapter[]
+  theme?: PureRenderTheme
+}
+
+export function buildWriterPureRenderRequest(
+  options: WriterPureRenderAdapterOptions,
+): PureRenderRequest {
+  const contentHtml = unwrapSingleArticle(options.contentHtml)
+  const title = options.title?.trim() || titleFromLeadingH1(contentHtml)
+  return {
+    profile: 'writer',
+    html: stripLeadingH1(contentHtml),
+    theme: options.theme,
+    metadata: title ? { title } : undefined,
+  }
+}
+
+export function buildBookPureRenderRequest(
+  options: BookPureRenderAdapterOptions,
+): PureRenderRequest {
+  const ids = new Map<BookPureRenderChapter, string>()
+  const used = new Set<string>()
+  options.chapters.forEach(chapter => {
+    ids.set(chapter, uniqueSlug(chapter.title, used))
+  })
+  const frontMatter = options.chapters.filter(
+    chapter => chapter.matter === 'frontmatter',
+  )
+  const rest = options.chapters.filter(
+    chapter => chapter.matter !== 'frontmatter',
+  )
+  const hasToc = options.chapters.some(chapter => chapter.role === 'toc')
+  const toc = hasToc ? '' : renderBookToc(rest, ids)
+  const html = [...frontMatter, ...rest]
+    .map(
+      (chapter, index) =>
+        `${
+          index === frontMatter.length && toc ? `${toc}\n` : ''
+        }${renderBookChapter(chapter, ids.get(chapter))}`,
+    )
+    .join('\n')
+  return {
+    profile: 'book',
+    html,
+    theme: options.theme,
+    metadata: {
+      title: options.title,
+      authorsText: options.author,
+    },
+  }
+}
+
+function renderBookToc(
+  chapters: readonly BookPureRenderChapter[],
+  ids: Map<BookPureRenderChapter, string>,
+): string {
+  const links = chapters
+    .filter(
+      chapter => chapter.matter !== 'backmatter' && chapter.role !== 'toc',
+    )
+    .map(chapter => {
+      const id = ids.get(chapter)
+      return id
+        ? `<li><a href="#${escapeHtml(id)}">${escapeHtml(
+            chapter.title,
+          )}</a></li>`
+        : ''
+    })
+    .filter(Boolean)
+    .join('\n')
+  if (!links) return ''
+  return `<section data-type="toc">
+  <h2>Contents</h2>
+  <ol>
+${links}
+  </ol>
+</section>`
+}
+
+function renderBookChapter(
+  chapter: BookPureRenderChapter,
+  headingId?: string,
+): string {
+  const dataType =
+    chapter.role === 'toc'
+      ? 'toc'
+      : chapter.role === 'appendix'
+      ? 'appendix'
+      : chapter.role === 'bibliography' || chapter.role === 'references'
+      ? 'references'
+      : chapter.role === 'acknowledgments'
+      ? 'acknowledgments'
+      : chapter.matter === 'frontmatter'
+      ? 'frontmatter'
+      : chapter.matter === 'backmatter'
+      ? 'backmatter'
+      : chapter.role === 'part'
+      ? 'part'
+      : 'chapter'
+  const roleAttr = chapter.role
+    ? ` data-role="${escapeHtml(chapter.role)}"`
+    : ''
+  const partAttr = chapter.partTitle
+    ? ` data-part="${escapeHtml(chapter.partTitle)}"`
+    : ''
+  const headingIdAttr = headingId ? ` id="${escapeHtml(headingId)}"` : ''
+  return `<section data-type="${dataType}"${roleAttr}${partAttr}>
+  <h2${headingIdAttr}>${escapeHtml(chapter.title)}</h2>
+  ${stripLeadingH1(chapter.html, chapter.title)}
+</section>`
+}
+
+function uniqueSlug(title: string, used: Set<string>): string {
+  const base =
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '') || 'chapter'
+  let slug = base
+  let index = 2
+  while (used.has(slug)) {
+    slug = `${base}-${index}`
+    index += 1
+  }
+  used.add(slug)
+  return slug
+}
+
+function titleFromLeadingH1(html: string): string | undefined {
+  const match = /^\s*<h1\b[^>]*>([\s\S]*?)<\/h1>/i.exec(html)
+  if (!match) return undefined
+  const title = match[1]
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return title || undefined
+}
+
+function stripLeadingH1(html: string, expectedTitle?: string): string {
+  const match = /^\s*<h1\b[^>]*>([\s\S]*?)<\/h1>/i.exec(html)
+  if (!match) return html
+  if (!expectedTitle) return html.slice(match[0].length)
+  const heading = match[1]
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return heading.toLowerCase() === expectedTitle.trim().toLowerCase()
+    ? html.slice(match[0].length)
+    : html
+}
+
+function unwrapSingleArticle(html: string): string {
+  const match = /^\s*<article\b[^>]*>([\s\S]*)<\/article>\s*$/i.exec(html)
+  return match ? match[1] : html
+}

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

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_PURE_RENDER_THEME } from './theme.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+describe('Pure Render stylesheet assets', () => {
+  it('ships the layered CSS and default token handoff files', () => {
+    for (const file of [
+      'reset.css',
+      'tokens/default.json',
+      'tokens/default.css',
+      'base.css',
+      'profiles/manuscript.css',
+      'profiles/writer.css',
+      'profiles/book.css',
+      'flow.css',
+    ]) {
+      expect(existsSync(join(here, file)), file).toBe(true)
+    }
+  })
+
+  it('keeps the default token asset aligned with the runtime default theme', () => {
+    const raw = readFileSync(join(here, 'tokens/default.json'), 'utf8')
+    const tokens = JSON.parse(raw) as {
+      color: { ink: string; accent: string }
+      type: { scaleRatio: number; fonts: { display: string; serif: string } }
+    }
+
+    expect(tokens.color.ink).toBe(DEFAULT_PURE_RENDER_THEME.color.ink)
+    expect(tokens.color.accent).toBe(DEFAULT_PURE_RENDER_THEME.color.accent)
+    expect(tokens.type.scaleRatio).toBe(
+      DEFAULT_PURE_RENDER_THEME.type.scaleRatio,
+    )
+    expect(tokens.type.fonts.display).toBe(
+      DEFAULT_PURE_RENDER_THEME.type.fonts.display,
+    )
+    expect(tokens.type.fonts.serif).toBe(
+      DEFAULT_PURE_RENDER_THEME.type.fonts.serif,
+    )
+  })
+})

package/src/bridge/pureRender/base.css

@@ -0,0 +1,76 @@
+html{ font-size:12pt; }
+body{
+  color:var(--ink); background:var(--paper);
+  font:var(--body)/var(--lead) var(--serif);
+  font-variant-numeric:oldstyle-nums proportional-nums;
+  -webkit-font-smoothing:antialiased;
+  hyphens:var(--hyphenate);
+  counter-reset:sec fig tbl ref eq;
+}
+.doc-title{ font:700 var(--t-title)/1.1 var(--display); margin:0 0 var(--rhythm); max-width:30rem; string-set:doctitle content(text); }
+.authors{ font:500 11.5pt/1.4 var(--sans); margin:0 0 .4rem; }
+.affil{ font:400 9pt/1.4 var(--sans); color:var(--muted); margin:0 0 calc(var(--rhythm)*1.2); }
+.affil sup,.authors sup{ font-size:.7em; }
+section[data-type="abstract"]{
+  border-top:2px solid var(--accent); border-bottom:1px solid var(--rule);
+  padding:calc(var(--rhythm)*.75) 0; margin:0 0 calc(var(--rhythm)*1.3); max-width:var(--measure);
+}
+section[data-type="abstract"] > h2{ all:unset; display:block; font:600 8pt/1 var(--sans); letter-spacing:.12em; text-transform:uppercase; color:var(--accent); margin:0 0 .5rem; counter-increment:none; }
+section[data-type="abstract"] > h2::before{ content:none; }
+section[data-type="abstract"] p{ margin:0; font-size:9.8pt; text-indent:0; }
+.keywords{ font:400 8.6pt/1.4 var(--sans); color:var(--muted); margin:.6rem 0 var(--rhythm); }
+.keywords b{ color:var(--ink-soft); font-weight:600; }
+section,p,ul,ol,blockquote{ max-width:var(--measure); }
+h2,h3,h4{ font-family:var(--display); color:var(--ink); break-after:avoid-page; }
+h2{ font-size:var(--t-h2); font-weight:700; line-height:1.15; margin:calc(var(--rhythm)*1.5) 0 calc(var(--rhythm)*.4); string-set:sectitle content(text); }
+section:not([data-type="abstract"]):not([data-type="frontmatter"]):not([data-type="backmatter"]):not([data-type="toc"]):not([data-type="references"]):not([data-type="endnotes"]):not([data-type="acknowledgments"]):not([data-type="part"]){ counter-increment:sec; counter-reset:sub; }
+h2::before{ content:counter(sec) "\00a0\00a0"; color:var(--accent); }
+section[data-type="abstract"] > h2::before,
+section[data-type="frontmatter"] > h2::before,
+section[data-type="backmatter"] > h2::before,
+section[data-type="toc"] > h2::before,
+section[data-type="references"] > h2::before,
+section[data-type="endnotes"] > h2::before,
+section[data-type="acknowledgments"] > h2::before,
+section[data-type="part"] > h2::before{ content:none; }
+h3{ counter-increment:sub; font-size:var(--t-h3); font-weight:600; margin:calc(var(--rhythm)*1) 0 calc(var(--rhythm)*.25); }
+h3::before{ content:counter(sec) "." counter(sub) "\00a0\00a0"; color:var(--accent); font-weight:500; }
+h4{ font-size:calc(var(--t-h3)*.88); font-weight:600; margin:calc(var(--rhythm)*.8) 0 calc(var(--rhythm)*.2); color:var(--ink-soft); }
+p{ margin:0; text-align:var(--text-align); orphans:3; widows:3; }
+p + p{ text-indent:1.25em; }
+h2 + p,h3 + p,section[data-type="abstract"] + p,figure + p{ text-indent:0; }
+a{ color:var(--accent-ink); text-decoration:none; }
+cite.ps-citation{ font-style:normal; white-space:nowrap; color:var(--accent-ink); }
+ul,ol{ margin:var(--rhythm) 0; padding-left:1.4rem; }
+li{ margin:.15rem 0; }
+figure{ counter-increment:fig; break-inside:avoid; margin:calc(var(--rhythm)*1.2) 0; }
+figcaption{ font:400 8.8pt/1.4 var(--serif); color:var(--ink-soft); margin-top:.55rem; max-width:var(--measure); }
+figcaption::before{ content:"Figure " attr(data-label) ".\00a0"; font-family:var(--sans); font-weight:var(--caption-label-weight); text-transform:var(--caption-label-transform); color:var(--ink); }
+.table-wrap{ counter-increment:tbl; break-inside:avoid; margin:calc(var(--rhythm)*1.2) 0; }
+.table-wrap > .tcaption{ font:400 8.8pt/1.4 var(--serif); color:var(--ink-soft); margin:0 0 .45rem; }
+.table-wrap > .tcaption::before{ content:"Table " attr(data-label) ".\00a0"; font-family:var(--sans); font-weight:var(--caption-label-weight); text-transform:var(--caption-label-transform); color:var(--ink); }
+table{ width:100%; font:400 9pt/1.35 var(--serif); }
+thead th{ font-family:var(--sans); font-weight:600; font-size:8.4pt; text-transform:var(--table-header-transform); letter-spacing:var(--table-header-letter-spacing); text-align:left; padding:var(--table-cell-padding-y) var(--table-cell-padding-x); color:var(--table-header-ink); background:var(--table-header-bg); border-bottom:var(--table-rule-width) solid var(--table-header-rule-color); }
+tbody td{ padding:var(--table-cell-padding-y) var(--table-cell-padding-x); border-bottom:var(--table-row-rule-width) solid var(--table-row-rule-color); }
+tbody tr:last-child td{ border-bottom:var(--table-rule-width) solid var(--rule); }
+.num{ text-align:right; font-variant-numeric:tabular-nums; }
+.equation{ counter-increment:eq; display:flex; align-items:center; gap:1rem; justify-content:center; margin:calc(var(--rhythm)*1) 0; break-inside:avoid; }
+.equation .eq-body{ font:italic 400 12pt/1 var(--serif); }
+.equation .eq-num{ margin-left:auto; }
+.equation .eq-num::before{ content:"(" attr(data-label) ")"; font:400 10pt var(--serif); color:var(--muted); }
+blockquote{ margin:var(--rhythm) 0; padding-left:1rem; border-left:2px solid var(--accent); font-style:italic; color:var(--ink-soft); }
+mark{ background:color-mix(in srgb, var(--accent) 14%, transparent); color:inherit; padding:0 .08em; }
+hr{ border:0; border-top:1px solid var(--rule-soft); margin:calc(var(--rhythm)*1.1) 0; max-width:var(--measure); }
+code,pre{ font-family:var(--mono); font-size:8.8pt; }
+pre{ background:#F5F6F8; border:1px solid var(--rule-soft); padding:.7rem .9rem; break-inside:avoid; white-space:pre-wrap; line-height:1.45; }
+a.xref-fig::after,a.xref-tbl::after,a.xref-eq::after{ content:none; }
+a.xref-sec::after{ content:target-counter(attr(href), sec); }
+section[data-type="references"]{ margin-top:calc(var(--rhythm)*1.5); }
+section[data-type="references"] > h2{ string-set:sectitle "References"; }
+section[data-type="references"] ol{ list-style:none; padding:0; margin:0; max-width:var(--measure); }
+section[data-type="references"] li{ counter-increment:ref; font-size:9pt; line-height:1.4; padding-left:2.2rem; text-indent:-2.2rem; margin:.3rem 0; break-inside:avoid; }
+section[data-type="references"] li::before{ content:"[" counter(ref) "]"; font-family:var(--sans); font-weight:600; display:inline-block; width:2.2rem; text-indent:0; }
+section[data-type="endnotes"]{ break-before:page; margin-top:calc(var(--rhythm)*1.5); }
+section[data-type="endnotes"] > h2{ string-set:sectitle "Notes"; }
+section[data-type="endnotes"] ol{ padding-left:1.4rem; max-width:var(--measure); }
+section[data-type="endnotes"] li{ font-size:9pt; line-height:1.45; margin:.35rem 0; break-inside:avoid; }

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

@@ -0,0 +1,279 @@
+import { describe, expect, it } from 'vitest'
+import { compilePrintTheme } from './compiler.js'
+import type { PrintStyleProfile } from './types.js'
+
+function profile(
+  overrides: Partial<PrintStyleProfile> = {},
+): PrintStyleProfile {
+  return {
+    schema_version: '1.0',
+    exemplar_quality: {
+      usable: true,
+      reason: 'clean page',
+      confidence: 0.9,
+    },
+    observations: {
+      palette: [
+        {
+          role: 'surface',
+          approx_hex: '#FFFFFF',
+          confidence: 0.9,
+        },
+        {
+          role: 'ink',
+          approx_hex: '#DDDDDD',
+          confidence: 0.9,
+        },
+        {
+          role: 'accent',
+          approx_hex: '#7A1F2B',
+          confidence: 0.9,
+        },
+      ],
+      type: [
+        {
+          role: 'display',
+          class: 'serif',
+          serif_detail: 'hairline',
+          confidence: 0.9,
+        },
+        {
+          role: 'body',
+          class: 'serif',
+          serif_detail: 'bracketed',
+          confidence: 0.9,
+        },
+        { role: 'caption', class: 'sans', confidence: 0.9 },
+      ],
+      type_pairing: { size_contrast: 'dramatic', confidence: 0.9 },
+      text_setting: {
+        alignment: 'flush-left',
+        hyphenation: 'absent',
+        measure_cpl: 58,
+        leading_feel: 'airy',
+        confidence: 0.9,
+      },
+      page_model: {
+        columns: 2,
+        margin_asymmetry: 'inner<outer',
+        confidence: 0.4,
+      },
+    },
+    rules: [
+      { rule: 'keep accent sparse', confidence: 0.9 },
+      { rule: 'ignore weak rule', confidence: 0.3 },
+    ],
+    derived: null,
+    ...overrides,
+  }
+}
+
+describe('compilePrintTheme', () => {
+  it('repairs weak ink contrast and maps display/body fonts separately', () => {
+    const result = compilePrintTheme(profile())
+
+    expect(result.theme?.color.ink).not.toBe('#DDDDDD')
+    expect(result.decisions.map(([type]) => type)).toContain('repair')
+    expect(result.theme?.type.fonts.display).toContain('Newsreader')
+    expect(result.theme?.type.fonts.serif).toContain('Source Serif 4')
+    expect(result.theme?.type.fonts.sans).toContain('Archivo')
+  })
+
+  it('derives measure, leading, ratio, and rules with confidence gates', () => {
+    const result = compilePrintTheme(profile())
+
+    expect(result.theme?.type.measure).toBe('29.0rem')
+    expect(result.theme?.type.lead).toBe(1.65)
+    expect(result.theme?.type.scaleRatio).toBe(1.414)
+    expect(result.theme?.setting).toEqual({
+      align: 'flush-left',
+      hyphenate: false,
+    })
+    expect(result.theme?.page?.columns).toBe(1)
+    expect(result.rules).toEqual(['keep accent sparse'])
+  })
+
+  it('keeps manuscript-like paper white unless surface evidence is strong', () => {
+    const result = compilePrintTheme(
+      profile({
+        observations: {
+          ...profile().observations,
+          palette: [
+            { role: 'surface', approx_hex: '#F5F5F0', confidence: 0.82 },
+            { role: 'ink', approx_hex: '#222222', confidence: 0.9 },
+          ],
+          finish: { register: 'scholarly', confidence: 0.8 },
+        },
+      }),
+    )
+
+    expect(result.theme?.color.paper).toBe('#FFFFFF')
+    expect(result.decisions).toContainEqual([
+      'fallback',
+      'manuscript surface #F5F5F0 confidence 0.82 < 0.95 -> white paper',
+    ])
+  })
+
+  it('allows manuscript-like paper tint when surface evidence is strong', () => {
+    const result = compilePrintTheme(
+      profile({
+        observations: {
+          ...profile().observations,
+          palette: [
+            { role: 'surface', approx_hex: '#F5F5F0', confidence: 0.98 },
+            { role: 'ink', approx_hex: '#222222', confidence: 0.9 },
+          ],
+          finish: { register: 'scholarly', confidence: 0.8 },
+        },
+      }),
+    )
+
+    expect(result.theme?.color.paper).toBe('#F5F5F0')
+  })
+
+  it('rejects unusable exemplars', () => {
+    const result = compilePrintTheme(
+      profile({
+        exemplar_quality: {
+          usable: false,
+          reason: 'mixed unrelated styles',
+          confidence: 0.9,
+        },
+      }),
+    )
+
+    expect(result.theme).toBeNull()
+    expect(result.decisions[0]).toEqual([
+      'reject',
+      'exemplar flagged unusable: mixed unrelated styles',
+    ])
+  })
+
+  it('compiles reference-page furniture into structured profile rules', () => {
+    const base = profile()
+    const result = compilePrintTheme({
+      ...base,
+      observations: {
+        ...base.observations,
+        type_scale: {
+          body_pt: 11.2,
+          title_scale: 2.4,
+          section_scale: 1.35,
+          confidence: 0.82,
+        },
+        running_heads: {
+          presence: 'present',
+          position: 'top outside',
+          transform: 'uppercase',
+          rule: 'none',
+          font_role: 'caption',
+          confidence: 0.84,
+        },
+        folio: {
+          position: 'bottom center',
+          style: 'plain',
+          suppress_on: ['opener'],
+          confidence: 0.78,
+        },
+        opener: {
+          spacing: 'generous',
+          recto_start: true,
+          ornament: 'rule',
+          drop_cap: false,
+          confidence: 0.8,
+        },
+        ornaments: {
+          kind: 'rule',
+          weight: 'hairline',
+          placement: 'above chapter title',
+          confidence: 0.76,
+        },
+        table_treatment: {
+          rule_weight: 'hairline',
+          header_treatment: 'small caps',
+          density: 'balanced',
+          confidence: 0.88,
+        },
+        caption_treatment: {
+          position: 'below',
+          label_style: 'bold',
+          alignment: 'left',
+          confidence: 0.9,
+        },
+      },
+    })
+
+    expect(result.theme?.type.body).toBe('11.2pt')
+    expect(result.theme?.profile_rules).toMatchObject({
+      running_heads: {
+        presence: 'present',
+        position: 'top outside',
+        transform: 'uppercase',
+      },
+      folio: { position: 'bottom center' },
+      opener: { spacing: 'generous', recto_start: true, ornament: 'rule' },
+      ornaments: { kind: 'rule', weight: 'hairline' },
+      table: { rule_weight: 'hairline', density: 'balanced' },
+      caption: { position: 'below', label_style: 'bold' },
+    })
+    expect(result.theme?.enforced_rules).toContain(
+      'Reference page furniture: running heads present at top outside.',
+    )
+    expect(result.theme?.enforced_rules).toContain(
+      'Reference tables: hairline rules, balanced density.',
+    )
+    expect(result.decisions).toContainEqual([
+      'apply',
+      'running heads present top outside',
+    ])
+    expect(result.decisions).toContainEqual([
+      'warn',
+      'font matching uses licensed substitutes; exact font identity is not guaranteed.',
+    ])
+    expect(result.decisions).toContainEqual([
+      'warn',
+      'point sizes are approximate; reference pages provide scale and contrast, not exact measurements.',
+    ])
+    expect(result.decisions).toContainEqual([
+      'warn',
+      'page geometry is approximate; margins and trim are applied only when confidence clears the compiler threshold.',
+    ])
+    expect(result.decisions).toContainEqual([
+      'warn',
+      'ornaments are mapped to supported rules/dividers; arbitrary custom ornament replication is unsupported.',
+    ])
+    expect(
+      result.theme?.enforced_rules?.some(rule => rule.includes('exact')),
+    ).toBe(false)
+  })
+
+  it('drops low-confidence page furniture to profile defaults', () => {
+    const base = profile()
+    const result = compilePrintTheme({
+      ...base,
+      observations: {
+        ...base.observations,
+        running_heads: {
+          presence: 'present',
+          position: 'top outside',
+          confidence: 0.4,
+        },
+        ornaments: {
+          kind: 'fleuron',
+          confidence: 0.2,
+        },
+      },
+    })
+
+    expect(result.theme?.profile_rules).toBeUndefined()
+    expect(result.theme?.enforced_rules).toEqual(['keep accent sparse'])
+    expect(result.decisions).toContainEqual([
+      'fallback',
+      'running_heads confidence 0.4 < 0.6 -> profile default',
+    ])
+    expect(result.decisions).toContainEqual([
+      'fallback',
+      'ornaments confidence 0.2 < 0.6 -> none/default',
+    ])
+  })
+})