@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.9

package/src/bridge/pureRender/base.css

@@ -16,6 +16,46 @@ body {
   max-width: 30rem;
   string-set: doctitle content(text);
 }
+/* Metadata eyebrow above the title — driven purely by theme tokens. */
+.doc-title::before {
+  content: var(--eyebrow-text, '');
+  display: var(--eyebrow-display, none);
+  font: 600 8pt / 1.3 var(--sans);
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin: 0 0 calc(var(--rhythm) * 0.6);
+}
+/* Drop cap on the opening paragraph — inert unless the theme enables it.
+   THREE separate rules on purpose: Paged.js crashes on comma-lists of
+   ::first-letter selectors ("item doesn't belong to list"). */
+.doc-title + p::first-letter {
+  float: var(--drop-cap-float, none);
+  font-family: var(--drop-cap-font, inherit);
+  font-size: var(--drop-cap-size, 1em);
+  line-height: var(--drop-cap-lh, inherit);
+  font-weight: var(--drop-cap-weight, inherit);
+  padding: var(--drop-cap-pad, 0);
+  color: var(--drop-cap-ink, inherit);
+}
+.doc-title + section > p:first-child::first-letter {
+  float: var(--drop-cap-float, none);
+  font-family: var(--drop-cap-font, inherit);
+  font-size: var(--drop-cap-size, 1em);
+  line-height: var(--drop-cap-lh, inherit);
+  font-weight: var(--drop-cap-weight, inherit);
+  padding: var(--drop-cap-pad, 0);
+  color: var(--drop-cap-ink, inherit);
+}
+section:first-of-type > p:first-child::first-letter {
+  float: var(--drop-cap-float, none);
+  font-family: var(--drop-cap-font, inherit);
+  font-size: var(--drop-cap-size, 1em);
+  line-height: var(--drop-cap-lh, inherit);
+  font-weight: var(--drop-cap-weight, inherit);
+  padding: var(--drop-cap-pad, 0);
+  color: var(--drop-cap-ink, inherit);
+}
 .authors {
   font: 500 11.5pt/1.4 var(--sans);
   margin: 0 0 0.4rem;
@@ -83,6 +123,10 @@ h2 {
   line-height: 1.15;
   margin: calc(var(--rhythm) * 1.5) 0 calc(var(--rhythm) * 0.4);
   string-set: sectitle content(text);
+  /* Optional accent rule beneath section headings (theme token). */
+  border-bottom: var(--heading-rule-width, 0) solid var(--accent);
+  padding-bottom: var(--heading-rule-pad, 0);
+  max-width: var(--measure);
 }
 section:not([data-type='abstract']):not([data-type='frontmatter']):not(
     [data-type='backmatter']

package/src/bridge/pureRender/document.ts

@@ -1,5 +1,10 @@
 import { buildPrintHtmlDocument } from '../printDocument.js'
-import { normalizePureRenderHtml } from './normalize.js'
+import {
+  injectCoverSection,
+  injectGeneratedToc,
+  normalizePureRenderHtml,
+  wrapLooseBodyRun,
+} from './normalize.js'
 import { buildPureRenderStylesheet } from './styles.js'
 import type { PureRenderRequest } from './types.js'
 
@@ -22,6 +27,28 @@ export function buildPureRenderHtmlDocument(options: {
     )
   }
 
+  // Theme-driven structure: cover first (title block onto its own named
+  // page), then a generated table of contents from the normalized
+  // article's sections (ids are assigned during normalization).
+  const setting = options.request.theme?.setting
+  let bodyHtml = normalized.html
+  if (setting?.coverPage) {
+    bodyHtml = injectCoverSection(bodyHtml, {
+      author: setting.coverAuthor,
+      date: setting.coverDate,
+    })
+  }
+  // Contents implies a cover: without one, a toc page before the title
+  // reads as clutter rather than structure.
+  if (setting?.coverPage && setting?.toc) {
+    bodyHtml = injectGeneratedToc(bodyHtml)
+  }
+  if (options.request.theme?.page?.columns === 2) {
+    // Columns attach to body sections; unsectioned (writer) articles need
+    // their loose body run wrapped so there is a section to columnize.
+    bodyHtml = wrapLooseBodyRun(bodyHtml)
+  }
+
   return buildPrintHtmlDocument({
     rootPath: options.rootPath,
     title: options.title ?? normalized.title,
@@ -30,6 +57,6 @@ export function buildPureRenderHtmlDocument(options: {
       theme: options.request.theme,
     }),
     bodyClass: `pure-render pure-render-${options.request.profile}`,
-    bodyHtml: normalized.html,
+    bodyHtml,
   })
 }

package/src/bridge/pureRender/index.ts

@@ -1,4 +1,5 @@
 export { compilePrintTheme } from './compiler.js'
+export { sanitizeBodyForPureRenderExport } from './sanitizeExportBody.js'
 export {
   buildBookPureRenderRequest,
   buildWriterPureRenderRequest,
@@ -46,7 +47,9 @@ export {
 } from './samples.js'
 export {
   inspectPureRenderVisualLayout,
+  relevantPagedSnapshotPages,
   visualIssuesForMetrics,
+  type PureRenderSnapshotRole,
   type PureRenderVisualCandidate,
   type PureRenderVisualDecision,
   type PureRenderVisualInspection,

package/src/bridge/pureRender/normalize.ts

@@ -149,6 +149,173 @@ function parseHtml(html: string): Document {
   return new DOMParser().parseFromString(html || '', 'text/html')
 }
 
+const TOC_EXCLUDED_TYPES = new Set([
+  'abstract',
+  'toc',
+  'cover',
+  'references',
+  'endnotes',
+  'acknowledgments',
+  'frontmatter',
+  'backmatter',
+  'part',
+])
+
+/**
+ * Insert a structural cover section (its own named page via CSS) BEFORE
+ * the title block. The cover shows a CLONE of the title plus optional
+ * author/date lines — the document keeps its own title afterwards.
+ * Idempotent.
+ */
+export function injectCoverSection(
+  articleHtml: string,
+  options: { author?: string; date?: string } = {},
+): string {
+  const doc = parseHtml(articleHtml)
+  const article = doc.body.querySelector('article')
+  if (!article) return articleHtml
+  if (article.querySelector('section[data-type="cover"]')) return articleHtml
+  const title = article.querySelector('.doc-title')
+  if (!title) return articleHtml
+
+  const cover = doc.createElement('section')
+  cover.setAttribute('data-type', 'cover')
+  const coverTitle = doc.createElement('p')
+  coverTitle.setAttribute('class', 'cover-title')
+  coverTitle.textContent = title.textContent?.replace(/\s+/g, ' ').trim() ?? ''
+  cover.appendChild(coverTitle)
+  const author = options.author?.trim()
+  if (author) {
+    const line = doc.createElement('p')
+    line.setAttribute('class', 'cover-author')
+    line.textContent = author
+    cover.appendChild(line)
+  }
+  const date = options.date?.trim()
+  if (date) {
+    const line = doc.createElement('p')
+    line.setAttribute('class', 'cover-date')
+    line.textContent = date
+    cover.appendChild(line)
+  }
+  // The article opens with the cover; the title block stays in the flow.
+  article.insertBefore(cover, article.firstChild)
+  return article.outerHTML
+}
+
+/**
+ * Generate a table of contents from the article's top-level sections and
+ * insert it before the first body section. Idempotent (an existing toc
+ * section wins); a no-op when there is nothing to list.
+ */
+export function injectGeneratedToc(articleHtml: string): string {
+  const doc = parseHtml(articleHtml)
+  const article = doc.body.querySelector('article')
+  if (!article) return articleHtml
+  if (article.querySelector('section[data-type="toc"]')) return articleHtml
+
+  const entries: { id: string; title: string }[] = []
+  let anchor: Element | null = null
+  // Child traversal instead of :scope selectors (not supported everywhere).
+  // Writer articles keep h2s as LOOSE children (no section wrappers), so
+  // both shapes are handled.
+  for (const child of Array.from(article.children)) {
+    if (child.tagName === 'SECTION') {
+      const type = child.getAttribute('data-type')
+      if (type && TOC_EXCLUDED_TYPES.has(type)) continue
+      const heading = Array.from(child.children).find(
+        node => node.tagName === 'H2',
+      )
+      const id = child.getAttribute('id') ?? heading?.getAttribute('id') ?? ''
+      const title = heading?.textContent?.replace(/\s+/g, ' ').trim() ?? ''
+      if (!anchor) anchor = child
+      if (id && title) entries.push({ id, title })
+    } else if (child.tagName === 'H2') {
+      const id = child.getAttribute('id') ?? ''
+      const title = child.textContent?.replace(/\s+/g, ' ').trim() ?? ''
+      if (!anchor) anchor = child
+      if (id && title) entries.push({ id, title })
+    }
+  }
+  if (entries.length === 0 || !anchor) return articleHtml
+
+  const toc = doc.createElement('section')
+  toc.setAttribute('data-type', 'toc')
+  const heading = doc.createElement('h2')
+  heading.textContent = 'Contents'
+  const list = doc.createElement('ol')
+  for (const entry of entries) {
+    const item = doc.createElement('li')
+    const link = doc.createElement('a')
+    link.setAttribute('href', `#${entry.id}`)
+    // Label + flex dotted leader; the page number is the link's ::after
+    // (target-counter). CSS leader() is NOT implemented by Paged.js.
+    const label = doc.createElement('span')
+    label.setAttribute('class', 'toc-label')
+    label.textContent = entry.title
+    const leader = doc.createElement('span')
+    leader.setAttribute('class', 'toc-leader')
+    link.appendChild(label)
+    link.appendChild(leader)
+    item.appendChild(link)
+    list.appendChild(item)
+  }
+  toc.appendChild(heading)
+  toc.appendChild(list)
+  // Contents sits IMMEDIATELY after the cover when there is one; only
+  // coverless documents fall back to before-the-first-heading.
+  const cover = article.querySelector('section[data-type="cover"]')
+  if (cover) {
+    cover.after(toc)
+  } else {
+    anchor.before(toc)
+  }
+  return article.outerHTML
+}
+
+const BODY_RUN_PRELUDE_CLASSES = new Set([
+  'doc-title',
+  'authors',
+  'affil',
+  'keywords',
+])
+
+/**
+ * Writer articles keep body content as LOOSE children (no sections), so
+ * per-section styling (columns) has nothing to attach to. Wrap the loose
+ * body run — everything after the title block / cover / toc — into one
+ * untyped section. Bails when the article is already sectioned.
+ */
+export function wrapLooseBodyRun(articleHtml: string): string {
+  const doc = parseHtml(articleHtml)
+  const article = doc.body.querySelector('article')
+  if (!article) return articleHtml
+
+  const children = Array.from(article.children)
+  const bodyStart = children.findIndex(child => {
+    if (child.tagName === 'H1') return false
+    const cls = child.getAttribute('class') ?? ''
+    if (cls.split(/\s+/).some(name => BODY_RUN_PRELUDE_CLASSES.has(name))) {
+      return false
+    }
+    if (child.tagName === 'SECTION') {
+      const type = child.getAttribute('data-type')
+      // Front-matter sections stay outside the run.
+      return !(type && TOC_EXCLUDED_TYPES.has(type))
+    }
+    return true
+  })
+  if (bodyStart === -1) return articleHtml
+  const run = children.slice(bodyStart)
+  // Already sectioned (manuscript/book shapes) — nothing to do.
+  if (run.some(child => child.tagName === 'SECTION')) return articleHtml
+
+  const wrapper = doc.createElement('section')
+  run[0].before(wrapper)
+  for (const child of run) wrapper.appendChild(child)
+  return article.outerHTML
+}
+
 function collectHardErrors(
   doc: Document,
   errors: PureRenderValidationError[],

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

@@ -0,0 +1,51 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from 'vitest'
+import { sanitizeBodyForPureRenderExport } from './sanitizeExportBody.js'
+import { buildPureRenderHtmlDocument } from './document.js'
+
+describe('sanitizeBodyForPureRenderExport', () => {
+  it('converts inline SVG (mermaid) to a data-URI image', () => {
+    // Note: happy-dom's text/html parser drops SVG children, so the
+    // style-content preservation inside the data URI can only be exercised in
+    // a real browser; here we pin the structural conversion.
+    const out = sanitizeBodyForPureRenderExport(
+      '<p>Before</p><svg aria-label="Flow chart"><style>.a{fill:red}</style><g style="stroke:blue"><rect/></g></svg><p>After</p>',
+    )
+    expect(out).not.toContain('<svg')
+    expect(out).not.toContain('<style')
+    expect(out).toContain('<img')
+    expect(out).toContain('data:image/svg+xml')
+    expect(out).toContain('alt="Flow chart"')
+  })
+
+  it('demotes body h1s to h2 with content and attributes preserved', () => {
+    expect(
+      sanitizeBodyForPureRenderExport('<h1 id="x">Mid <em>doc</em></h1>'),
+    ).toBe('<h2 id="x">Mid <em>doc</em></h2>')
+  })
+
+  it('strips inline style attributes and unwraps center', () => {
+    const out = sanitizeBodyForPureRenderExport(
+      '<p style="text-align: center">Centered</p><center><p>Old-school</p></center><script>x()</script>',
+    )
+    expect(out).toBe('<p>Centered</p><p>Old-school</p>')
+  })
+
+  it('sanitized ordinary-document body passes Pure Render hard validation', () => {
+    // Each of these previously made buildPureRenderHtmlDocument THROW and the
+    // export fail outright: a user-typed H1, a centered paragraph, a mermaid
+    // SVG with an embedded <style> element.
+    const body = sanitizeBodyForPureRenderExport(
+      '<h2>Intro</h2><h1>User heading</h1>' +
+        '<p style="text-align: center">Centered</p>' +
+        '<svg><style>.x{}</style><rect style="fill:red"/></svg>',
+    )
+    expect(() =>
+      buildPureRenderHtmlDocument({
+        rootPath: '/tmp/ws',
+        title: 'Doc',
+        request: { html: body, profile: 'writer' },
+      }),
+    ).not.toThrow()
+  })
+})

package/src/bridge/pureRender/sanitizeExportBody.ts

@@ -0,0 +1,61 @@
+/**
+ * Make editor-produced body HTML acceptable to Pure Render's hard content
+ * validation (`collectHardErrors` in normalize.ts): any `[style]` attribute,
+ * any `<script|style|link|font|center>` element, and any body `<h1>` makes
+ * `buildPureRenderHtmlDocument` THROW — which turned "Export PDF" into a hard
+ * failure for perfectly ordinary documents (a user-typed H1, one centered
+ * paragraph, or a mermaid diagram whose rendered SVG carries a `<style>`
+ * element and inline styles).
+ *
+ * Apps call this on body content just before building the print document.
+ * Rules applied, in order:
+ *
+ * 1. Inline `<svg>` (mermaid renders) is converted to an `<img>` with a
+ *    `data:image/svg+xml` URI. The SVG's internal styles are REQUIRED for it
+ *    to draw correctly; inside a data URI they still render but are invisible
+ *    to DOM validation.
+ * 2. Body `<h1>`s are demoted to `<h2>` — content preserved; the document
+ *    title is rendered by the front matter, never body prose.
+ * 3. Inline `style` attributes are dropped (Pure Render owns presentation).
+ * 4. `<script|style|link|font>` are removed; `<center>` is unwrapped so its
+ *    content survives.
+ */
+export function sanitizeBodyForPureRenderExport(html: string): string {
+  const doc = new DOMParser().parseFromString(html || '', 'text/html')
+
+  doc.body.querySelectorAll('svg').forEach(svg => {
+    const serialized = new XMLSerializer().serializeToString(svg)
+    const img = doc.createElement('img')
+    img.setAttribute(
+      'src',
+      `data:image/svg+xml;charset=utf-8,${encodeURIComponent(serialized)}`,
+    )
+    img.setAttribute('alt', svg.getAttribute('aria-label') || 'Diagram')
+    svg.replaceWith(img)
+  })
+
+  doc.body.querySelectorAll('h1').forEach(heading => {
+    const demoted = doc.createElement('h2')
+    for (const attr of Array.from(heading.attributes)) {
+      demoted.setAttribute(attr.name, attr.value)
+    }
+    while (heading.firstChild) demoted.appendChild(heading.firstChild)
+    heading.replaceWith(demoted)
+  })
+
+  doc.body
+    .querySelectorAll('[style]')
+    .forEach(element => element.removeAttribute('style'))
+
+  doc.body
+    .querySelectorAll('script, style, link, font')
+    .forEach(element => element.remove())
+  doc.body.querySelectorAll('center').forEach(element => {
+    const parent = element.parentNode
+    if (!parent) return
+    while (element.firstChild) parent.insertBefore(element.firstChild, element)
+    element.remove()
+  })
+
+  return doc.body.innerHTML
+}

package/src/bridge/pureRender/styles.ts

@@ -19,7 +19,23 @@ body{
   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); }
+.doc-title{ font:700 var(--t-title)/1.1 var(--display); margin:0 0 var(--rhythm); max-width:min(var(--measure),100%); }
+/* string-set MUST live in its own rule (Paged.js drops it otherwise). */
+.doc-title{ string-set:doctitle content(text); }
+/* Cover: a structural section on its own named page — the ONLY reliable
+   way to page-break out of a (possibly multicol) flow under Paged.js. */
+section[data-type="cover"]{ page: cover; break-after:page; text-align:center; padding-top:34%; max-width:none; }
+section[data-type="cover"] .cover-title{ font:700 var(--t-title)/1.08 var(--display); margin:0 auto calc(var(--rhythm)*1.2); max-width:none; text-align:center; }
+section[data-type="cover"] .cover-author{ font:500 11.5pt/1.5 var(--sans); margin:0; max-width:none; text-align:center; }
+section[data-type="cover"] .cover-date{ font:400 9.5pt/1.6 var(--sans); color:var(--muted); margin:.35rem 0 0; max-width:none; text-align:center; }
+.doc-title::before{ content:var(--eyebrow-text,""); display:var(--eyebrow-display,none); font:600 8pt/1.3 var(--sans); letter-spacing:.14em; text-transform:uppercase; color:var(--accent); margin:0 0 calc(var(--rhythm)*.6); }
+/* Drop cap: THREE separate rules on purpose — Paged.js' stylesheet
+   transformer crashes ("item doesn't belong to list", a css-tree List
+   error) on a comma-separated selector list where several selectors carry
+   a ::first-letter pseudo-element. Do NOT merge these. */
+.doc-title + p::first-letter{ float:var(--drop-cap-float,none); font-family:var(--drop-cap-font,inherit); font-size:var(--drop-cap-size,1em); line-height:var(--drop-cap-lh,inherit); font-weight:var(--drop-cap-weight,inherit); padding:var(--drop-cap-pad,0); color:var(--drop-cap-ink,inherit); }
+.doc-title + section > p:first-child::first-letter{ float:var(--drop-cap-float,none); font-family:var(--drop-cap-font,inherit); font-size:var(--drop-cap-size,1em); line-height:var(--drop-cap-lh,inherit); font-weight:var(--drop-cap-weight,inherit); padding:var(--drop-cap-pad,0); color:var(--drop-cap-ink,inherit); }
+section:first-of-type > p:first-child::first-letter{ float:var(--drop-cap-float,none); font-family:var(--drop-cap-font,inherit); font-size:var(--drop-cap-size,1em); line-height:var(--drop-cap-lh,inherit); font-weight:var(--drop-cap-weight,inherit); padding:var(--drop-cap-pad,0); color:var(--drop-cap-ink,inherit); }
 .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; }
@@ -32,9 +48,22 @@ 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); }
+section,p,ul,ol,blockquote{ max-width:min(var(--measure),100%); }
+/* Centre the text column on the page: the measure is narrower than the
+   page content box, and hugging the left margin leaves a lopsided right
+   margin. Two columns widen the article to two measures plus the gap. */
+article{ max-width:min(calc((var(--measure) * var(--body-columns,1)) + (7mm * (var(--body-columns,1) - 1))), 100%); margin-inline:auto; }
+/* Columns per BODY section (not on the article): title, cover, toc and
+   typed front/backmatter stay single-column, and page breaks from cover/
+   toc are real page breaks instead of column breaks. The wrapper spans
+   the full (two-measure) article; inner blocks cap at one measure per
+   column. */
+article > section:not([data-type]){ column-count:var(--body-columns,1); column-gap:7mm; column-fill:auto; max-width:none; }
 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); }
+h2{ font-size:var(--t-h2); font-weight:700; line-height:1.15; margin:calc(var(--rhythm)*1.5) 0 calc(var(--rhythm)*.4); border-bottom:var(--heading-rule-width,0) solid var(--accent); padding-bottom:var(--heading-rule-pad,0); max-width:min(var(--measure),100%); }
+/* string-set MUST live in its own rule: Paged.js drops it when the same
+   declaration list continues with var()/min() declarations after it. */
+h2{ 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,
@@ -61,7 +90,9 @@ figcaption::before{ content:"Figure " attr(data-label) ".\\00a0"; font-family:va
 .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); }
+table{ width:100%; font:400 9pt/1.35 var(--serif); border:var(--table-grid-width,0) solid var(--rule); }
+td,th{ border-left:var(--table-grid-width,0) solid var(--table-row-rule-color); }
+td:first-child,th:first-child{ border-left:0; }
 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); }
@@ -77,6 +108,17 @@ 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); }
+/* Contents: its OWN page between cover and body. Dotted leader is a flex
+   filler element — Paged.js does not implement CSS leader(). */
+section[data-type="toc"]{ break-before:page; break-after:page; max-width:var(--measure); }
+section[data-type="toc"] > h2{ counter-increment:none; }
+section[data-type="toc"] > h2::before{ content:none; }
+section[data-type="toc"] ol{ list-style:none; padding:0; margin:calc(var(--rhythm)*.6) 0 0; }
+section[data-type="toc"] li{ margin:.5rem 0; }
+section[data-type="toc"] a{ display:flex; align-items:baseline; gap:.5rem; color:var(--ink); }
+section[data-type="toc"] .toc-label{ flex:0 1 auto; }
+section[data-type="toc"] .toc-leader{ flex:1 1 auto; min-width:1.5rem; border-bottom:1px dotted var(--rule); transform:translateY(-.22em); }
+section[data-type="toc"] a::after{ content:target-counter(attr(href), page); font-variant-numeric:tabular-nums; color:var(--muted); }
 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); }
@@ -109,7 +151,7 @@ export const PROFILE_CSS: Record<PureRenderProfile, string> = {
 [data-variant="two-column"] figure[data-span="page"],[data-variant="two-column"] .table-wrap[data-span="page"]{ column-span:all; }
 `,
   writer: `
-@page{ size:A4; margin:25mm; @bottom-center{ content:counter(page); font:500 8.4pt var(--mono); color:var(--muted); } }
+@page{ size:A4; margin:20mm 18mm; @bottom-center{ content:counter(page); font:500 8.4pt var(--mono); color:var(--muted); } }
 @page:first{ @top-left{content:none} @top-right{content:none} }
 .pure-render-writer{ --text-align:var(--theme-text-align,left); --hyphenate:var(--theme-hyphenate,manual); }
 .pure-render-writer p + p{ text-indent:0; margin-top:calc(var(--rhythm)*.55); }
@@ -145,6 +187,82 @@ figcaption::before{ content:"Figure " attr(data-label) ".\\00a0"; }
 `,
 }
 
+/**
+ * Theme-conditional @page overrides (running header, folio, logo). These
+ * append AFTER the profile CSS so a later margin-box rule wins.
+ */
+export function themePageOverridesCss(theme?: PureRenderTheme): string {
+  if (!theme) return ''
+  const parts: string[] = []
+  // User-set page margins (theme.page.margin, e.g. "20mm 18mm") override
+  // the profile's @page margins. Only simple length lists are accepted.
+  const pageMargin = theme.page?.margin?.trim()
+  if (pageMargin && /^[0-9.]+(mm|cm|in|pt)(\s+[0-9.]+(mm|cm|in|pt)){0,3}$/.test(pageMargin)) {
+    parts.push(`@page{ margin:${pageMargin}; }`)
+  }
+  if (!theme.setting) return parts.join('\n')
+  const runningHeader = theme.setting.runningHeader ?? 'none'
+  const customHeaderText = theme.setting.runningHeaderText?.trim() ?? ''
+  if (runningHeader !== 'none' && (runningHeader !== 'custom' || customHeaderText)) {
+    const content =
+      runningHeader === 'custom'
+        ? JSON.stringify(customHeaderText)
+        : runningHeader === 'section'
+        ? 'string(sectitle)'
+        : 'string(doctitle)'
+    parts.push(
+      `@page{ @top-center{ content:${content}; font:600 8pt var(--sans); letter-spacing:.08em; text-transform:uppercase; color:var(--muted); } }`,
+      '@page:first{ @top-center{ content:none } }',
+    )
+  }
+  if (theme.setting.coverPage) {
+    const coverImage = theme.setting.coverImageDataUri?.trim()
+    const coverBackground = theme.setting.coverBackground?.trim() || 'var(--paper)'
+    const background =
+      coverImage && /^data:image\//.test(coverImage)
+        ? `url("${coverImage}") center / cover no-repeat, ${coverBackground}`
+        : coverBackground
+    // The cover's named page: full-bleed background, no page furniture.
+    parts.push(
+      `@page cover{ background:${background}; @top-left{ content:none } @top-center{ content:none } @top-right{ content:none } @bottom-left{ content:none } @bottom-center{ content:none } @bottom-right{ content:none } }`,
+    )
+  }
+  const folio = theme.setting.folio ?? 'page'
+  const folioSlot = theme.setting.folioSlot ?? 'bottom-center'
+  const folioStyle = theme.setting.folioStyle ?? 'plain'
+  if (folio === 'none') {
+    parts.push('@page{ @bottom-center{ content:none } }')
+  } else if (folioSlot !== 'bottom-center' || folioStyle !== 'plain') {
+    const folioContent =
+      folioStyle === 'of-total'
+        ? 'counter(page) " / " counter(pages)'
+        : 'counter(page)'
+    const folioColor = folioStyle === 'accent' ? 'var(--accent)' : 'var(--muted)'
+    const folioWeight = folioStyle === 'accent' ? '700' : '500'
+    if (folioSlot !== 'bottom-center') {
+      // Silence the profile's default folio before placing our own.
+      parts.push('@page{ @bottom-center{ content:none } }')
+    }
+    parts.push(
+      `@page{ @${folioSlot}{ content:${folioContent}; font:${folioWeight} 8.4pt var(--mono); letter-spacing:.04em; color:${folioColor}; } }`,
+    )
+  }
+  const logo = theme.setting.logoDataUri?.trim()
+  if (logo && /^data:image\//.test(logo)) {
+    const slot = theme.setting.logoSlot ?? 'top-right'
+    // Anchor to the slot's edge: Paged.js gives a lone occupied margin box
+    // a wide span, so a CENTERED background reads as page-centre.
+    const align = slot.endsWith('left') ? 'left' : 'right'
+    const box = `content:" "; background:url("${logo}") no-repeat ${align} center / contain;`
+    parts.push(
+      `@page{ @${slot}{ ${box} } }`,
+      // Profiles blank the top corners on page 1 — the logo stays.
+      `@page:first{ @${slot}{ ${box} } }`,
+    )
+  }
+  return parts.join('\n')
+}
+
 export function buildPureRenderStylesheet(options: {
   profile: PureRenderProfile
   theme?: PureRenderTheme
@@ -158,6 +276,8 @@ export function buildPureRenderStylesheet(options: {
     BASE_CSS,
     '/* pure-render: profile */',
     PROFILE_CSS[options.profile],
+    '/* pure-render: theme page overrides */',
+    themePageOverridesCss(options.theme),
     '/* pure-render: flow */',
     FLOW_CSS,
   ].join('\n')