@puredesktop/puredesktop-ui-bridge 2.1.6 → 2.1.8

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

@@ -22,6 +22,265 @@ describe('Pure Render themes', () => {
     )
   })
 
+  it('maps flourish settings into CSS variables', () => {
+    const css = themeToPureRenderTokenCss({
+      ...DEFAULT_PURE_RENDER_THEME,
+      setting: {
+        ...DEFAULT_PURE_RENDER_THEME.setting,
+        headingRule: 'underline',
+        eyebrowText: 'Essay · July 2026',
+        dropCap: true,
+      },
+    })
+
+    expect(css).toContain('--heading-rule-width:1.5px;')
+    expect(css).toContain('--eyebrow-display:block;')
+    expect(css).toContain('--eyebrow-text:"Essay · July 2026";')
+    expect(css).toContain('--drop-cap-float:left;')
+    expect(css).toContain('--drop-cap-ink:var(--accent);')
+  })
+
+  it('keeps flourish variables inert when settings are absent', () => {
+    const css = themeToPureRenderTokenCss(DEFAULT_PURE_RENDER_THEME)
+
+    expect(css).toContain('--heading-rule-width:0;')
+    expect(css).toContain('--eyebrow-display:none;')
+    expect(css).toContain('--drop-cap-float:none;')
+    expect(css).toContain('--drop-cap-ink:inherit;')
+  })
+
+  it('maps cover, custom header and folio settings', async () => {
+    const { themePageOverridesCss } = await import('./styles.js')
+    const themed = {
+      ...DEFAULT_PURE_RENDER_THEME,
+      setting: {
+        ...DEFAULT_PURE_RENDER_THEME.setting,
+        coverPage: true,
+        runningHeader: 'custom' as const,
+        runningHeaderText: 'Draft · Confidential',
+        folio: 'page' as const,
+        folioSlot: 'bottom-right' as const,
+        folioStyle: 'of-total' as const,
+      },
+    }
+    const pageCss = themePageOverridesCss(themed)
+    // Cover is structural: its named page appears in the overrides.
+    expect(pageCss).toContain('@page cover{')
+    expect(pageCss).toContain('content:"Draft · Confidential"')
+    // Styled folio replaces the profile default at its new slot.
+    expect(pageCss).toContain('@bottom-center{ content:none }')
+    expect(pageCss).toContain(
+      '@bottom-right{ content:counter(page) " / " counter(pages)',
+    )
+    // Custom header with EMPTY text emits nothing.
+    const empty = themePageOverridesCss({
+      ...DEFAULT_PURE_RENDER_THEME,
+      setting: {
+        ...DEFAULT_PURE_RENDER_THEME.setting,
+        runningHeader: 'custom' as const,
+      },
+    })
+    expect(empty).not.toContain('@top-center')
+  })
+
+  it('wraps the title block into a cover section with author/date', async () => {
+    const { injectCoverSection } = await import('./normalize.js')
+    const article =
+      '<article><h1 class="doc-title">T</h1><p class="authors">A. Hyde</p>' +
+      '<section id="sec-one"><h2>First</h2><p>x</p></section></article>'
+    const withCover = injectCoverSection(article, {
+      author: 'A. Hyde',
+      date: 'July 2026',
+    })
+    expect(withCover).toContain('data-type="cover"')
+    expect(withCover).toContain('class="cover-author"')
+    expect(withCover).toContain('class="cover-date"')
+    // Title moved INSIDE the cover, before the first body section.
+    expect(withCover.indexOf('data-type="cover"')).toBeLessThan(
+      withCover.indexOf('id="sec-one"'),
+    )
+    // Idempotent.
+    expect(injectCoverSection(withCover)).toBe(withCover)
+  })
+
+  it('emits the cover named page with background/image and no furniture', async () => {
+    const { themePageOverridesCss } = await import('./styles.js')
+    const css = themePageOverridesCss({
+      ...DEFAULT_PURE_RENDER_THEME,
+      setting: {
+        ...DEFAULT_PURE_RENDER_THEME.setting,
+        coverPage: true,
+        coverBackground: '#10241E',
+        coverImageDataUri: 'data:image/png;base64,BBBB',
+      },
+    })
+    expect(css).toContain(
+      '@page cover{ background:url("data:image/png;base64,BBBB") center / cover no-repeat, #10241E;',
+    )
+    expect(css).toContain('@bottom-center{ content:none }')
+  })
+
+  it('generates a table of contents from body sections', async () => {
+    const { injectGeneratedToc } = await import('./normalize.js')
+    const article =
+      '<article><h1 class="doc-title">T</h1>' +
+      '<section data-type="abstract"><h2>Abstract</h2><p>a</p></section>' +
+      '<section id="sec-one"><h2>First Part</h2><p>x</p></section>' +
+      '<section id="sec-two"><h2>Second Part</h2><p>y</p></section>' +
+      '<section data-type="references"><h2>References</h2></section></article>'
+    const withToc = injectGeneratedToc(article)
+    expect(withToc).toContain('data-type="toc"')
+    expect(withToc).toContain('href="#sec-one"')
+    expect(withToc).toContain('toc-label">First Part')
+    expect(withToc).toContain('toc-label">Second Part')
+    expect(withToc).toContain('class="toc-leader"')
+    expect(withToc).not.toContain('toc-label">References')
+    // The toc sits before the first body section.
+    expect(withToc.indexOf('data-type="toc"')).toBeLessThan(
+      withToc.indexOf('id="sec-one"'),
+    )
+    // Idempotent.
+    expect(injectGeneratedToc(withToc)).toBe(withToc)
+    // Nothing to list → unchanged.
+    expect(injectGeneratedToc('<article><p>solo</p></article>')).toBe(
+      '<article><p>solo</p></article>',
+    )
+    // Writer articles keep h2s as LOOSE children — no section wrappers.
+    const loose =
+      '<article><h1 class="doc-title">T</h1>' +
+      '<h2 id="alpha">Alpha</h2><p>x</p><h2 id="beta">Beta</h2><p>y</p></article>'
+    const looseToc = injectGeneratedToc(loose)
+    expect(looseToc).toContain('data-type="toc"')
+    expect(looseToc).toContain('href="#alpha"')
+    expect(looseToc).toContain('toc-label">Alpha')
+    expect(looseToc).toContain('toc-label">Beta')
+    // Inserted before the first heading, after the title block.
+    expect(looseToc.indexOf('doc-title')).toBeLessThan(
+      looseToc.indexOf('data-type="toc"'),
+    )
+    expect(looseToc.indexOf('data-type="toc"')).toBeLessThan(
+      looseToc.indexOf('id="alpha"'),
+    )
+    // With a cover, the toc sits IMMEDIATELY after it — before the title.
+    const covered =
+      '<article><section data-type="cover"><p class="cover-title">T</p></section>' +
+      '<h1 class="doc-title">T</h1><p>Intro para.</p>' +
+      '<h2 id="alpha">Alpha</h2><p>x</p></article>'
+    const coveredToc = injectGeneratedToc(covered)
+    expect(coveredToc.indexOf('data-type="cover"')).toBeLessThan(
+      coveredToc.indexOf('data-type="toc"'),
+    )
+    expect(coveredToc.indexOf('data-type="toc"')).toBeLessThan(
+      coveredToc.indexOf('doc-title'),
+    )
+  })
+
+  it('wraps loose writer body content so columns have a section', async () => {
+    const { wrapLooseBodyRun } = await import('./normalize.js')
+    const loose =
+      '<article><section data-type="cover"><p class="cover-title">T</p></section>' +
+      '<h1 class="doc-title">T</h1><section data-type="toc"><h2>Contents</h2></section>' +
+      '<h2 id="alpha">Alpha</h2><p>x</p><h2 id="beta">Beta</h2><p>y</p></article>'
+    const wrapped = wrapLooseBodyRun(loose)
+    // Body run in ONE untyped section; cover/title/toc left outside.
+    expect(wrapped).toMatch(/<section><h2 id="alpha">/)
+    expect(wrapped.indexOf('data-type="toc"')).toBeLessThan(
+      wrapped.indexOf('<section><h2 id="alpha">'),
+    )
+    // Already-sectioned articles are untouched.
+    const sectioned =
+      '<article><h1 class="doc-title">T</h1><section id="s"><h2>S</h2></section></article>'
+    expect(wrapLooseBodyRun(sectioned)).toBe(sectioned)
+  })
+
+  it('maps the table grid flag into a border token', () => {
+    const withGrid = themeToPureRenderTokenCss({
+      ...DEFAULT_PURE_RENDER_THEME,
+      profile_rules: { table: { rule_weight: 'light', grid: 'lines' } },
+    })
+    expect(withGrid).toContain('--table-grid-width:1px;')
+    const without = themeToPureRenderTokenCss({
+      ...DEFAULT_PURE_RENDER_THEME,
+      profile_rules: { table: { rule_weight: 'light' } },
+    })
+    expect(without).toContain('--table-grid-width:0;')
+    // Default (no profile rules) stays gridless.
+    expect(themeToPureRenderTokenCss(DEFAULT_PURE_RENDER_THEME)).toContain(
+      '--table-grid-width:0;',
+    )
+  })
+
+  it('overrides page margins from theme.page.margin (sanitized)', async () => {
+    const { themePageOverridesCss } = await import('./styles.js')
+    const withMargin = themePageOverridesCss({
+      ...DEFAULT_PURE_RENDER_THEME,
+      page: { ...DEFAULT_PURE_RENDER_THEME.page, margin: '14mm 12mm' },
+    })
+    expect(withMargin).toContain('@page{ margin:14mm 12mm; }')
+    // Junk values never reach the stylesheet.
+    const junk = themePageOverridesCss({
+      ...DEFAULT_PURE_RENDER_THEME,
+      page: { ...DEFAULT_PURE_RENDER_THEME.page, margin: '12mm } body{color:red' },
+    })
+    expect(junk).not.toContain('body{color:red')
+  })
+
+  it('maps page furniture settings into page override CSS', async () => {
+    const { themePageOverridesCss, buildPureRenderStylesheet } = await import(
+      './styles.js'
+    )
+    const themed = {
+      ...DEFAULT_PURE_RENDER_THEME,
+      page: { ...DEFAULT_PURE_RENDER_THEME.page, columns: 2 },
+      setting: {
+        ...DEFAULT_PURE_RENDER_THEME.setting,
+        runningHeader: 'section' as const,
+        folio: 'none' as const,
+        logoDataUri: 'data:image/png;base64,AAAA',
+        logoSlot: 'bottom-right' as const,
+      },
+    }
+    const pageCss = themePageOverridesCss(themed)
+    expect(pageCss).toContain('@top-center{ content:string(sectitle)')
+    expect(pageCss).toContain('@bottom-center{ content:none }')
+    expect(pageCss).toContain(
+      '@bottom-right{ content:" "; background:url("data:image/png;base64,AAAA") no-repeat right center / contain',
+    )
+    expect(themeToPureRenderTokenCss(themed)).toContain('--body-columns:2;')
+
+    // The full stylesheet includes flourish rules AND page overrides.
+    const sheet = buildPureRenderStylesheet({ profile: 'writer', theme: themed })
+    expect(sheet).toContain('--eyebrow-display')
+    expect(sheet).toContain('.doc-title::before')
+    expect(sheet).toContain('column-count:var(--body-columns,1)')
+    expect(sheet).toContain('@top-center{ content:string(sectitle)')
+
+    // Untouched settings emit no overrides.
+    expect(themePageOverridesCss(DEFAULT_PURE_RENDER_THEME)).toBe('')
+  })
+
+  it('never emits comma-lists of ::first-letter selectors (Paged.js crash)', async () => {
+    // Paged.js' stylesheet transformer throws "item doesn't belong to
+    // list" (css-tree List error) when a selector LIST contains multiple
+    // ::first-letter selectors. Single-selector rules are fine.
+    const { buildPureRenderStylesheet } = await import('./styles.js')
+    for (const profile of ['writer', 'manuscript', 'book'] as const) {
+      const sheet = buildPureRenderStylesheet({
+        profile,
+        theme: DEFAULT_PURE_RENDER_THEME,
+      }).replace(/\/\*[\s\S]*?\*\//g, '')
+      for (const rule of sheet.split('}')) {
+        const selector = rule.split('{')[0] ?? ''
+        const pseudoCount = selector.split('::first-letter').length - 1
+        if (pseudoCount > 1) {
+          throw new Error(
+            `selector list with ${pseudoCount} ::first-letter selectors: ${selector.trim()}`,
+          )
+        }
+      }
+    }
+  })
+
   it('maps safe profile rules into CSS variables', () => {
     const css = themeToPureRenderTokenCss({
       ...DEFAULT_PURE_RENDER_THEME,

package/src/bridge/pureRender/theme.ts

@@ -18,7 +18,7 @@ export const DEFAULT_PURE_RENDER_THEME: PureRenderTheme = {
   type: {
     body: '10.6pt',
     lead: 1.5,
-    measure: '34rem',
+    measure: '38rem',
     scaleRatio: 1.333,
     fonts: {
       display: '"Archivo", system-ui, sans-serif',
@@ -72,6 +72,22 @@ export function themeToPureRenderTokenCss(
   --theme-hyphenate:${theme.setting?.hyphenate === false ? 'manual' : 'auto'};
   --text-align:var(--theme-text-align);
   --hyphenate:var(--theme-hyphenate);
+  --heading-rule-width:${
+    theme.setting?.headingRule === 'underline' ? '1.5px' : '0'
+  };
+  --heading-rule-pad:${
+    theme.setting?.headingRule === 'underline' ? '.18em' : '0'
+  };
+  --eyebrow-display:${theme.setting?.eyebrowText?.trim() ? 'block' : 'none'};
+  --eyebrow-text:${JSON.stringify(theme.setting?.eyebrowText?.trim() ?? '')};
+  --drop-cap-float:${theme.setting?.dropCap ? 'left' : 'none'};
+  --drop-cap-size:${theme.setting?.dropCap ? '3.05em' : '1em'};
+  --drop-cap-lh:${theme.setting?.dropCap ? '.78' : 'inherit'};
+  --drop-cap-weight:${theme.setting?.dropCap ? '700' : 'inherit'};
+  --drop-cap-pad:${theme.setting?.dropCap ? '.06em .12em 0 0' : '0'};
+  --drop-cap-ink:${theme.setting?.dropCap ? 'var(--accent)' : 'inherit'};
+  --drop-cap-font:${theme.setting?.dropCap ? 'var(--display)' : 'inherit'};
+  --body-columns:${theme.page?.columns === 2 ? '2' : '1'};
 ${profileVars}
 }`
 }
@@ -131,6 +147,7 @@ function profileRuleCssVariables(theme: PureRenderTheme): string {
       '  --chapter-ornament-display:none;',
       '  --chapter-ornament-border:0;',
       '  --table-rule-width:1px;',
+      '  --table-grid-width:0;',
       '  --table-row-rule-width:.5px;',
       '  --table-header-bg:transparent;',
       '  --table-header-ink:var(--ink);',
@@ -173,6 +190,7 @@ function profileRuleCssVariables(theme: PureRenderTheme): string {
     };`,
     `  --chapter-ornament-border:${ornamentWidth};`,
     `  --table-rule-width:${tableRule};`,
+    `  --table-grid-width:${rules.table?.grid === 'lines' ? tableRule : '0'};`,
     `  --table-row-rule-width:${density.rowRuleWidth};`,
     `  --table-header-bg:${header.bg};`,
     `  --table-header-ink:${header.ink};`,

package/src/bridge/pureRender/types.ts

@@ -63,6 +63,37 @@ export interface PureRenderTheme {
   setting?: {
     align?: 'justified' | 'flush-left' | string
     hyphenate?: boolean
+    /** Accent rule beneath section headings. */
+    headingRule?: 'none' | 'underline'
+    /** Small metadata kicker above the document title; empty/absent = off. */
+    eyebrowText?: string
+    /** Oversized accent first letter on the opening paragraph. */
+    dropCap?: boolean
+    /** Running header content in the top margin (suppressed on page 1). */
+    runningHeader?: 'none' | 'title' | 'section' | 'custom'
+    /** Freeform running-header text when runningHeader is 'custom'. */
+    runningHeaderText?: string
+    /** Page-number footer; 'none' hides it. */
+    folio?: 'page' | 'none'
+    /** Where the page number sits. */
+    folioSlot?: 'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-right'
+    /** Page-number treatment. */
+    folioStyle?: 'plain' | 'accent' | 'of-total'
+    /** Standalone cover: the title block gets page 1 to itself. */
+    coverPage?: boolean
+    /** Cover page background (any CSS colour). */
+    coverBackground?: string
+    /** Full-bleed cover image (data URI); layered over the background. */
+    coverImageDataUri?: string
+    /** Author line on the cover. */
+    coverAuthor?: string
+    /** Date line on the cover. */
+    coverDate?: string
+    /** Generated table of contents after the title block. */
+    toc?: boolean
+    /** Logo image (data URI) placed in a page margin box. */
+    logoDataUri?: string
+    logoSlot?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
   }
   enforced_rules?: readonly string[]
   profile_rules?: PureRenderProfileRules
@@ -96,6 +127,8 @@ export interface PureRenderProfileRules {
     rule_weight?: 'hairline' | 'light' | 'medium' | string
     header_treatment?: string
     density?: 'airy' | 'balanced' | 'dense' | string
+    /** 'lines' draws vertical cell rules + an outer border (full grid). */
+    grid?: 'none' | 'lines' | string
   }
   caption?: {
     position?: 'above' | 'below' | string

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

@@ -42,6 +42,32 @@ describe('inspectPureRenderVisualLayout', () => {
     expect(result.candidate?.id).toBe('compact-figure')
   })
 
+  it('flags colliding blocks and proposes containment, escalating to vision', () => {
+    const result = inspectPureRenderVisualLayout({
+      usedHeightRatio: 0.9,
+      overlappingBlocks: 3,
+      overflowingBlocks: 1,
+    })
+
+    expect(result.issues).toContain('content-overlap')
+    expect(result.issues).toContain('content-overflow')
+    expect(result.decision).toBe('rerender-candidate')
+    // Deterministic containment first; vision look if geometry survives.
+    expect(result.candidate?.id).toBe('contain-overflow')
+    expect(result.candidate?.cssPatch).toContain('table-layout:fixed')
+    expect(result.requiresVisionReview).toBe(true)
+  })
+
+  it('stays quiet when geometry is clean', () => {
+    const result = inspectPureRenderVisualLayout({
+      usedHeightRatio: 0.9,
+      overlappingBlocks: 0,
+      overflowingBlocks: 0,
+    })
+    expect(result.issues).not.toContain('content-overlap')
+    expect(result.issues).not.toContain('content-overflow')
+  })
+
   it('rejects caption orphan candidates deterministically', () => {
     const result = inspectPureRenderVisualLayout({
       imagePage: 2,

package/src/bridge/pureRender/visualLayoutInspection.ts

@@ -5,6 +5,8 @@ export type PureRenderVisualIssue =
   | 'caption-orphan'
   | 'image-not-visible-on-risk-page'
   | 'blank-page'
+  | 'content-overlap'
+  | 'content-overflow'
 
 export type PureRenderVisualDecision =
   | 'observe'
@@ -31,6 +33,8 @@ export interface PureRenderVisualLayoutMetrics {
   topGapRatio?: number
   bottomGapRatio?: number
   usedHeightRatio?: number
+  overlappingBlocks?: number
+  overflowingBlocks?: number
 }
 
 export interface PureRenderVisualCandidate {
@@ -92,6 +96,32 @@ export function inspectPureRenderVisualLayout(
     }
   }
 
+  if (
+    issues.includes('content-overlap') ||
+    issues.includes('content-overflow')
+  ) {
+    // Geometry says blocks collide or escape their box (e.g. a wide table
+    // bleeding into the next column). Try deterministic containment first;
+    // if the collision survives, this page needs a vision look.
+    return {
+      decision: 'rerender-candidate',
+      recommendation:
+        'Blocks overlap or overflow their box on this page — try the containment candidate; if geometry still collides afterwards, escalate to vision review.',
+      requiresUserReview: true,
+      requiresVisionReview: true,
+      issues,
+      metrics: normalized,
+      candidate: {
+        id: 'contain-overflow',
+        label: 'Contain overflow candidate',
+        summary:
+          'Constrain tables, code blocks and media to their column so colliding blocks reflow.',
+        cssPatch:
+          'table{ table-layout:fixed; width:100%; } td,th{ overflow-wrap:break-word; word-break:break-word; } .table-wrap{ max-width:100%; } pre{ white-space:pre-wrap; overflow-wrap:anywhere; max-width:100%; } img,svg{ max-width:100%; height:auto; }',
+      },
+    }
+  }
+
   if (canTryCompactFigure) {
     return {
       decision: 'rerender-compact-figure-candidate',
@@ -123,6 +153,45 @@ export function inspectPureRenderVisualLayout(
   }
 }
 
+export type PureRenderSnapshotRole =
+  | 'problem'
+  | 'figure'
+  | 'image'
+  | 'caption'
+  | 'sample'
+  | 'candidate'
+
+/**
+ * Which pages of a paged render are worth snapshotting for inspection:
+ * the metric-flagged problem/heading/figure/image/caption pages, else page 1
+ * as a sample. Shared by the app-side vision typesetting loops.
+ */
+export function relevantPagedSnapshotPages(
+  metrics: PureRenderVisualLayoutMetrics | undefined,
+  pageCount: number,
+): Array<{ page: number; role: PureRenderSnapshotRole }> {
+  const pages: Array<{ page: number; role: PureRenderSnapshotRole }> = []
+  const add = (value: number | undefined, role: PureRenderSnapshotRole) => {
+    if (
+      typeof value !== 'number' ||
+      !Number.isFinite(value) ||
+      value < 1 ||
+      value > pageCount ||
+      pages.some(item => item.page === value)
+    ) {
+      return
+    }
+    pages.push({ page: value, role })
+  }
+  add(metrics?.problemPage, 'problem')
+  add(metrics?.headingPage, 'problem')
+  add(metrics?.figurePage, 'figure')
+  add(metrics?.imagePage, 'image')
+  add(metrics?.captionPage, 'caption')
+  if (pages.length === 0) add(1, 'sample')
+  return pages.sort((a, b) => a.page - b.page)
+}
+
 export function visualIssuesForMetrics(
   metrics: PureRenderVisualLayoutMetrics,
 ): PureRenderVisualIssue[] {
@@ -157,5 +226,11 @@ export function visualIssuesForMetrics(
   if (metrics.imageVisible === false) {
     issues.push('image-not-visible-on-risk-page')
   }
+  if ((metrics.overlappingBlocks ?? 0) > 0) {
+    issues.push('content-overlap')
+  }
+  if ((metrics.overflowingBlocks ?? 0) > 0) {
+    issues.push('content-overflow')
+  }
   return Array.from(new Set(issues))
 }

package/src/bridge/react/useDocumentHotkeys.ts

@@ -0,0 +1,41 @@
+import { useEffect } from 'react'
+
+export interface UseDocumentHotkeysOptions {
+  onSave?: () => void
+  onNew?: () => void
+  onOpen?: () => void
+  enabled?: boolean
+}
+
+/**
+ * Standard document shortcuts inside an app iframe: ⌘S (name-or-flash),
+ * ⌘N (new document), ⌘O (document switcher). Apps receive their own key
+ * events, so this binds within the app document only.
+ */
+export function useDocumentHotkeys({
+  onSave,
+  onNew,
+  onOpen,
+  enabled = true,
+}: UseDocumentHotkeysOptions): void {
+  useEffect(() => {
+    if (!enabled) return
+    const onKeyDown = (event: KeyboardEvent): void => {
+      const meta = event.metaKey || event.ctrlKey
+      if (!meta || event.altKey || event.shiftKey) return
+      const key = event.key.toLowerCase()
+      if (key === 's' && onSave) {
+        event.preventDefault()
+        onSave()
+      } else if (key === 'n' && onNew) {
+        event.preventDefault()
+        onNew()
+      } else if (key === 'o' && onOpen) {
+        event.preventDefault()
+        onOpen()
+      }
+    }
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [enabled, onNew, onOpen, onSave])
+}