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

package/src/bridge/pureRender/flow.css

@@ -0,0 +1,3 @@
+.doc-title,.authors,.affil,section[data-type="abstract"]{ break-after:avoid; }
+.fn{ float:footnote; font-size:8.4pt; line-height:1.3; }
+@page{ @footnote{ border-top:.5px solid var(--rule); padding-top:2pt; } }

package/src/bridge/pureRender/index.ts

@@ -0,0 +1,66 @@
+export { compilePrintTheme } from './compiler.js'
+export {
+  buildBookPureRenderRequest,
+  buildWriterPureRenderRequest,
+  type BookPureRenderAdapterOptions,
+  type BookPureRenderChapter,
+  type WriterPureRenderAdapterOptions,
+} from './adapters.js'
+export { buildPureRenderHtmlDocument } from './document.js'
+export {
+  PRINT_STYLE_PROFILE_SCHEMA,
+  PRINT_TOKEN_EXTRACTION_PROMPT,
+  buildBookPrintStyleProfileFromReference,
+  buildPrintStyleProfilePrompt,
+  buildWriterPrintStyleProfileFromReference,
+  isPrintStyleProfile,
+  parsePrintStyleProfileResponse,
+  reconcilePrintStyleProfiles,
+  samplePrintReferenceImageColors,
+  type PrintReferenceImageSample,
+  type PrintStyleProfilePromptInput,
+} from './extraction.js'
+export { normalizePureRenderHtml } from './normalize.js'
+export {
+  BASE_CSS,
+  FLOW_CSS,
+  PROFILE_CSS,
+  RESET_CSS,
+  buildPureRenderStylesheet,
+} from './styles.js'
+export {
+  DEFAULT_PURE_RENDER_THEME,
+  isPureRenderTheme,
+  parsePureRenderThemeJson,
+  themeToPureRenderTokenCss,
+} from './theme.js'
+export {
+  PURE_RENDER_THEME_PRESETS,
+  type PureRenderThemePreset,
+} from './presets.js'
+export {
+  PURE_RENDER_BOOK_CHAPTER_SAMPLE_HTML,
+  PURE_RENDER_BOOK_SECOND_CHAPTER_SAMPLE_HTML,
+  PURE_RENDER_MANUSCRIPT_SAMPLE_HTML,
+  PURE_RENDER_WRITER_SAMPLE_HTML,
+} from './samples.js'
+export {
+  inspectPureRenderVisualLayout,
+  visualIssuesForMetrics,
+  type PureRenderVisualCandidate,
+  type PureRenderVisualDecision,
+  type PureRenderVisualInspection,
+  type PureRenderVisualIssue,
+  type PureRenderVisualLayoutMetrics,
+} from './visualLayoutInspection.js'
+export type {
+  CompilePrintThemeResult,
+  PrintStyleProfile,
+  PureRenderMetadata,
+  PureRenderNormalizeResult,
+  PureRenderOptions,
+  PureRenderProfile,
+  PureRenderRequest,
+  PureRenderTheme,
+  PureRenderValidationError,
+} from './types.js'

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

@@ -0,0 +1,442 @@
+import { describe, expect, it } from 'vitest'
+import { normalizePureRenderHtml } from './normalize.js'
+
+describe('normalizePureRenderHtml', () => {
+  it('accepts the documented Writer contract example', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'writer',
+      html: [
+        '<h1>Field Notes</h1>',
+        '<p>Plain prose from the shared editor.</p>',
+        '<figure data-asset-id="asset_fig_notes">',
+        '<img src="assets/figures/notes.png" alt="Notebook">',
+        '<figcaption>Notebook sketch.</figcaption>',
+        '</figure>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([
+      {
+        code: 'invalid-h1',
+        message: 'Only the canonical .doc-title may use h1',
+      },
+    ])
+    expect(result.title).toBe('Field Notes')
+    expect(result.html).toContain('<article lang="en">')
+    expect(result.html).toContain('<h2 id="field-notes">Field Notes</h2>')
+    expect(result.html).toContain('id="asset_fig_notes"')
+    expect(result.html).toContain('data-label="1" data-label-kind="figure"')
+  })
+
+  it('accepts the documented Manuscript contract example', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: [
+        '<section>',
+        '<h2>Results</h2>',
+        '<p>See <a data-xref-target="asset_table_results">Table 1</a>.</p>',
+        '<table data-asset-id="asset_table_results">',
+        '<caption>Measured values.</caption>',
+        '<tr><td>42</td></tr>',
+        '</table>',
+        '</section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain('id="results"')
+    expect(result.html).toContain(
+      '<div class="table-wrap" data-asset-id="asset_table_results" id="asset_table_results" data-label="1" data-label-kind="table">',
+    )
+    expect(result.html).toContain(
+      '<a data-xref-target="asset_table_results" href="#asset_table_results" class="xref-tbl">Table 1</a>',
+    )
+  })
+
+  it('accepts the documented Book contract example', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'book',
+      html: [
+        '<section data-type="chapter">',
+        '<h2>The White Page Contract</h2>',
+        '<p>Book chapters use the same blocks, with book-specific page treatment.</p>',
+        '</section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain('<section data-type="chapter">')
+    expect(result.html).toContain('id="the-white-page-contract"')
+  })
+
+  it('normalizes metadata into a canonical article', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: '<h1>Paper Title</h1><h2>Intro</h2><p>Hello</p>',
+      metadata: {
+        title: 'Paper Title',
+        authorsText: 'A. Author',
+        affiliationsText: 'Pure Lab',
+        abstractText: 'A short abstract.',
+        keywords: ['render', 'print'],
+      },
+    })
+
+    expect(result.errors).toEqual([
+      {
+        code: 'invalid-h1',
+        message: 'Only the canonical .doc-title may use h1',
+      },
+    ])
+    expect(result.html).toContain('<article lang="en">')
+    expect(result.html).toContain('<h1 class="doc-title">Paper Title</h1>')
+    expect(result.html).toContain('<p class="authors">A. Author</p>')
+    expect(result.html).toContain('data-type="abstract"')
+    expect(result.html).toContain('<p class="keywords">')
+  })
+
+  it('sanitizes rich metadata while preserving author and affiliation markers', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: '<p>Body</p>',
+      metadata: {
+        title: 'Safe Metadata',
+        authorsHtml: [
+          '<span data-author-id="a1" onclick="bad()">',
+          '<strong>Ada Author</strong><sup>1,*</sup>',
+          '<a href="https://orcid.org/0000-0000-0000-0001" style="color:red">ORCID</a>',
+          '<script>bad()</script>',
+          '<a href="javascript:bad()">bad</a>',
+          '</span>',
+        ].join(''),
+        affiliationsHtml: [
+          '<span data-affiliation-id="aff-1" style="color:red"><sup>1</sup> Pure Lab</span>',
+          '<br><span><sup>*</sup> Correspondence: ada@example.org</span>',
+        ].join(''),
+        abstractHtml:
+          '<p style="color:red">Safe <em>abstract</em><script>bad()</script><a href="javascript:bad()">link</a></p>',
+      },
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain('data-author-id="a1"')
+    expect(result.html).toContain('<strong>Ada Author</strong>')
+    expect(result.html).toContain('<sup>1,*</sup>')
+    expect(result.html).toContain(
+      'href="https://orcid.org/0000-0000-0000-0001"',
+    )
+    expect(result.html).toContain('data-affiliation-id="aff-1"')
+    expect(result.html).toContain('Correspondence: ada@example.org')
+    expect(result.html).toContain('<p>Safe <em>abstract</em><a>link</a></p>')
+    expect(result.html).not.toContain('<script')
+    expect(result.html).not.toContain('onclick')
+    expect(result.html).not.toContain('style=')
+    expect(result.html).not.toContain('javascript:')
+  })
+
+  it('preserves in-tree front matter, editor marks, and explicit language when request metadata is absent', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: [
+        '<article lang="fr">',
+        '<h1 class="doc-title">Titre</h1>',
+        '<p class="authors"><span data-author-id="a1"><strong>A. Auteur</strong></span></p>',
+        '<section data-type="abstract"><h2>Résumé</h2><p><em>Texte</em></p></section>',
+        '<p><span data-comment-id="c1">Corps</span><br><code>x</code> <mark>à revoir</mark> <cite class="ps-citation" data-ref-ids="ref-a,ref-b">[1,2]</cite></p>',
+        '<hr>',
+        '</article>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain('<article lang="fr">')
+    expect(result.html).toContain('<h1 class="doc-title">Titre</h1>')
+    expect(result.html).toContain('data-author-id="a1"')
+    expect(result.html).toContain('<em>Texte</em>')
+    expect(result.html).toContain('data-comment-id="c1"')
+    expect(result.html).toContain('<br>')
+    expect(result.html).toContain('<code>x</code>')
+    expect(result.html).toContain('<mark>à revoir</mark>')
+    expect(result.html).toContain(
+      '<cite class="ps-citation" data-ref-ids="ref-a,ref-b">[1,2]</cite>',
+    )
+    expect(result.html).toContain('<hr>')
+  })
+
+  it('links citation labels to matching references', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: [
+        '<p>See <cite data-ref-ids="ref-render">[1]</cite> and ',
+        '<cite data-ref-ids="ref-layout,ref-data">[2,3]</cite>.</p>',
+        '<section data-type="references"><h2>References</h2><ol>',
+        '<li id="ref-render">Render reference.</li>',
+        '<li id="ref-layout">Layout reference.</li>',
+        '<li id="ref-data">Data reference.</li>',
+        '</ol></section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain(
+      '<cite data-ref-ids="ref-render" class="ps-citation"><a href="#ref-render">[1]</a></cite>',
+    )
+    expect(result.html).toContain(
+      '<cite data-ref-ids="ref-layout,ref-data" class="ps-citation">[<a href="#ref-layout">2</a>, <a href="#ref-data">3</a>]</cite>',
+    )
+  })
+
+  it('links app bibliography citations to ref-entry targets', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: [
+        '<p>See <cite class="ps-citation" data-ref-ids="ref-methods">[1]</cite>.</p>',
+        '<section data-type="references"><h2>References</h2><ol>',
+        '<li id="ref-entry-ref-methods">Methods reference.</li>',
+        '</ol></section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain(
+      '<cite class="ps-citation" data-ref-ids="ref-methods"><a href="#ref-entry-ref-methods">[1]</a></cite>',
+    )
+  })
+
+  it('removes duplicate leading titles when request metadata supplies the canonical title', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'writer',
+      html: '<h1>Field Notes</h1><p>Body</p>',
+      metadata: { title: 'Field Notes' },
+    })
+
+    expect(result.errors).toEqual([
+      {
+        code: 'invalid-h1',
+        message: 'Only the canonical .doc-title may use h1',
+      },
+    ])
+    expect(result.html.match(/Field Notes/g)).toHaveLength(1)
+    expect(result.html).toContain('<h1 class="doc-title">Field Notes</h1>')
+    expect(result.html).toContain('<p>Body</p>')
+  })
+
+  it('rejects forbidden presentation and unresolved xrefs', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: '<p style="color:red">Bad</p><script></script><p>See <a class="xref-fig" href="#missing"></a> and <a class="xref-eq" href="#missing-eq"></a></p>',
+    })
+
+    expect(result.errors.map(error => error.code)).toEqual([
+      'forbidden-style-attribute',
+      'forbidden-element',
+      'unresolved-xref',
+      'unresolved-xref',
+    ])
+  })
+
+  it('wraps bare tables and assigns missing ids', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: '<section><h2>Findings</h2><table><caption>Data</caption><tr><td>1</td></tr></table></section>',
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain('id="findings"')
+    expect(result.html).toContain('class="table-wrap"')
+    expect(result.html).toContain(
+      '<div class="tcaption" data-label="1">Data</div>',
+    )
+  })
+
+  it('strips editor table sizing styles before validation', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'book',
+      html: [
+        '<section data-type="chapter">',
+        '<h2>Tables</h2>',
+        '<table style="min-width: 100px"><colgroup><col style="width: 40%"><col style="width: 60%"></colgroup>',
+        '<tr><th>Label</th><th>Value</th></tr><tr><td>A</td><td>1</td></tr>',
+        '</table>',
+        '</section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain('class="table-wrap"')
+    expect(result.html).toContain('<colgroup><col><col></colgroup>')
+    expect(result.html).not.toContain('style=')
+  })
+
+  it('normalizes shared TipTap asset xrefs into live Paged.js targets', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: [
+        '<p>See <a class="ps-xref" data-xref-target="asset_fig_a" href="#asset_fig_a">Figure 1</a>, ',
+        '<a class="ps-xref" data-xref-target="asset_table_b" href="#asset_table_b">Table 1</a>, and ',
+        '<a class="ps-xref" data-xref-target="asset_blockMath_c" href="#asset_blockMath_c">Equation 1</a>.</p>',
+        '<figure data-asset-id="asset_fig_a"><img src="x.png"><figcaption>Flow</figcaption></figure>',
+        '<table data-asset-id="asset_table_b"><caption>Data</caption><tr><td>1</td></tr></table>',
+        '<div data-type="block-math" data-asset-id="asset_blockMath_c">E = mc^2</div>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain('id="asset_fig_a"')
+    expect(result.html).toContain('data-label="1" data-label-kind="figure"')
+    expect(result.html).toContain(
+      'class="ps-xref xref-fig" data-xref-target="asset_fig_a" href="#asset_fig_a">Figure 1</a>',
+    )
+    expect(result.html).toContain(
+      '<div class="table-wrap" data-asset-id="asset_table_b" id="asset_table_b" data-label="1" data-label-kind="table">',
+    )
+    expect(result.html).toContain('class="ps-xref xref-tbl"')
+    expect(result.html).toContain('>Table 1</a>')
+    expect(result.html).toContain('data-type="block-math"')
+    expect(result.html).toContain('data-asset-id="asset_blockMath_c"')
+    expect(result.html).toContain('id="asset_blockMath_c"')
+    expect(result.html).toContain('class="equation"')
+    expect(result.html).toContain('data-label="1" data-label-kind="equation"')
+    expect(result.html).toContain('<span class="eq-body">E = mc^2</span>')
+    expect(result.html).toContain('<span class="eq-num" data-label="1"></span>')
+    expect(result.html).toContain('class="ps-xref xref-eq"')
+    expect(result.html).toContain('>Equation 1</a>')
+  })
+
+  it('materializes book asset labels by chapter before Paged.js runs', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'book',
+      html: [
+        '<section data-type="chapter"><h2>One</h2>',
+        '<p>See <a data-xref-target="asset_fig_a"></a>.</p>',
+        '<figure data-asset-id="asset_fig_a"><figcaption>Flow</figcaption></figure>',
+        '</section>',
+        '<section data-type="chapter"><h2>Two</h2>',
+        '<p>See <a data-xref-target="asset_fig_b"></a>.</p>',
+        '<figure data-asset-id="asset_fig_b"><figcaption>Flow</figcaption></figure>',
+        '</section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain(
+      'data-asset-id="asset_fig_a" id="asset_fig_a" data-label="1.1"',
+    )
+    expect(result.html).toContain('href="#asset_fig_a"')
+    expect(result.html).toContain('>Figure 1.1</a>')
+    expect(result.html).toContain(
+      'data-asset-id="asset_fig_b" id="asset_fig_b" data-label="2.1"',
+    )
+    expect(result.html).toContain('href="#asset_fig_b"')
+    expect(result.html).toContain('>Figure 2.1</a>')
+  })
+
+  it('normalizes footnote lists into inline Paged.js footnotes', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: [
+        '<p>Claim<sup id="fnref-proof"><a href="#fn-proof">1</a></sup>.</p>',
+        '<section class="footnotes"><ol>',
+        '<li id="fn-proof">Footnote text for the proof. <a href="#fnref-proof">return</a></li>',
+        '</ol></section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain(
+      '<span class="fn" id="fn-proof">Footnote text for the proof.</span>',
+    )
+    expect(result.html).not.toContain('class="fnref"')
+    expect(result.html).not.toContain('<sup')
+    expect(result.html).not.toContain('class="footnotes"')
+  })
+
+  it('removes source footnote markers when inline floating notes already exist', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'writer',
+      html: [
+        '<p>Existing inline note',
+        '<sup id="fnref-inline"><a href="#fn-inline" class="fnref">5</a></sup>',
+        '<span class="fn" id="fn-inline">Inline footnote text.</span>',
+        ' continues.</p>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain(
+      'Existing inline note<span class="fn" id="fn-inline">Inline footnote text.</span> continues.',
+    )
+    expect(result.html).not.toContain('class="fnref"')
+    expect(result.html).not.toContain('<sup')
+  })
+
+  it('normalizes many source footnotes including long notes', () => {
+    const longNote =
+      'A long footnote can preserve several sentences of scholarly context, including commas, semicolons, and a bracketed cue [long-note-proof]. It should stay attached to the inline marker after normalization.'
+    const result = normalizePureRenderHtml({
+      profile: 'manuscript',
+      html: [
+        '<p>Clustered notes',
+        '<sup id="fnref-many-1"><a href="#fn-many-1">1</a></sup>',
+        '<sup id="fnref-many-2"><a href="#fn-many-2">2</a></sup>',
+        '<sup id="fnref-many-3"><a href="#fn-many-3">3</a></sup>',
+        '<sup id="fnref-many-4"><a href="#fn-many-4">4</a></sup>',
+        '<sup id="fnref-many-long"><a href="#fn-many-long">5</a></sup>',
+        ' remain page notes.</p>',
+        '<section class="footnotes"><ol>',
+        '<li id="fn-many-1">First clustered footnote. <a href="#fnref-many-1">return</a></li>',
+        '<li id="fn-many-2">Second clustered footnote. <a href="#fnref-many-2">return</a></li>',
+        '<li id="fn-many-3">Third clustered footnote. <a href="#fnref-many-3">return</a></li>',
+        '<li id="fn-many-4">Fourth clustered footnote. <a href="#fnref-many-4">return</a></li>',
+        `<li id="fn-many-long">${longNote} <a href="#fnref-many-long">return</a></li>`,
+        '</ol></section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    for (const id of [
+      'fn-many-1',
+      'fn-many-2',
+      'fn-many-3',
+      'fn-many-4',
+      'fn-many-long',
+    ]) {
+      expect(result.html).toContain(`class="fn" id="${id}"`)
+    }
+    expect(result.html).not.toContain('class="fnref"')
+    expect(result.html).not.toContain('<sup')
+    expect(result.html).toContain(longNote)
+    expect(result.html).not.toContain('class="footnotes"')
+  })
+
+  it('preserves book endnotes as backmatter instead of page footnotes', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'book',
+      html: [
+        '<section data-type="chapter"><h2>Chapter</h2><p>Body<a href="#en-1">1</a>.</p></section>',
+        '<section data-type="endnotes"><h2>Notes</h2><ol>',
+        '<li id="en-1">Endnote text remains in book backmatter.</li>',
+        '</ol></section>',
+      ].join(''),
+    })
+
+    expect(result.errors).toEqual([])
+    expect(result.html).toContain('<section data-type="endnotes">')
+    expect(result.html).toContain('Endnote text remains in book backmatter.')
+    expect(result.html).not.toContain('class="fn"')
+  })
+
+  it('flags unknown section data types', () => {
+    const result = normalizePureRenderHtml({
+      profile: 'book',
+      html: '<section data-type="poster"><h2>Bad</h2></section>',
+    })
+
+    expect(result.errors).toEqual([
+      {
+        code: 'unknown-data-type',
+        message: 'Unknown section data-type "poster"',
+      },
+    ])
+  })
+})