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

package/src/bridge/pureRender/normalize.ts

@@ -1,682 +1,682 @@
-import { escapeHtml } from '../printDocument.js'
-import type {
-  PureRenderMetadata,
-  PureRenderNormalizeResult,
-  PureRenderOptions,
-  PureRenderProfile,
-  PureRenderValidationError,
-} from './types.js'
-
-const ALLOWED_DATA_TYPES = new Set([
-  'abstract',
-  'part',
-  'chapter',
-  'appendix',
-  'references',
-  'acknowledgments',
-  'toc',
-  'frontmatter',
-  'backmatter',
-  'footnotes',
-  'endnotes',
-])
-
-const XREF_SELECTORS = [
-  'a.xref-fig[href^="#"]',
-  'a.xref-tbl[href^="#"]',
-  'a.xref-eq[href^="#"]',
-  'a.xref-sec[href^="#"]',
-  'a.fnref[href^="#"]',
-]
-
-export function normalizePureRenderHtml(options: {
-  html: string
-  profile: PureRenderProfile
-  metadata?: PureRenderMetadata
-  options?: PureRenderOptions
-}): PureRenderNormalizeResult {
-  const doc = parseHtml(options.html)
-  const errors: PureRenderValidationError[] = []
-
-  stripEditorTablePresentation(doc)
-  collectHardErrors(doc, errors)
-  stripEmptyParagraphs(doc)
-  wrapBareTables(doc)
-  normalizeReferenceableBlocks(doc)
-  normalizeCrossReferenceLinks(doc)
-  normalizeFootnotes(doc)
-  normalizeInlineFootnoteMarkers(doc)
-  normalizeHeadings(doc)
-  normalizeSections(doc, errors)
-  assignMissingIds(doc)
-  materializeReferenceLabels(doc, options.profile)
-  normalizeCitationLinks(doc)
-  validateCrossReferences(doc, errors)
-
-  const article = buildCanonicalArticle(doc, options.metadata)
-  const lang = article.getAttribute('lang')?.trim() || 'en'
-  article.setAttribute('lang', lang)
-  if (options.options?.variant) {
-    article.setAttribute('data-variant', options.options.variant)
-  }
-
-  const title =
-    options.metadata?.title?.trim() ||
-    article.querySelector('.doc-title')?.textContent?.trim() ||
-    titleFromDocument(doc.body.innerHTML) ||
-    'Document'
-
-  return { html: article.outerHTML, title, errors }
-}
-
-function stripEditorTablePresentation(doc: Document): void {
-  doc.body.querySelectorAll('table,colgroup,col').forEach(element => {
-    element.removeAttribute('style')
-  })
-}
-
-function normalizeFootnotes(doc: Document): void {
-  const notes = new Map<string, string>()
-  doc.body
-    .querySelectorAll<HTMLElement>(
-      'section.footnotes, aside.footnotes, section[data-type="footnotes"]',
-    )
-    .forEach(container => {
-      container.querySelectorAll<HTMLElement>('li[id]').forEach(item => {
-        const id = item.id.trim()
-        if (!id) return
-        const clone = item.cloneNode(true) as HTMLElement
-        clone
-          .querySelectorAll<HTMLAnchorElement>(
-            'a[href^="#fnref"],a[rev="footnote"]',
-          )
-          .forEach(backlink => backlink.remove())
-        notes.set(id, clone.innerHTML.trim())
-      })
-      container.remove()
-    })
-
-  if (notes.size === 0) return
-
-  doc.body.querySelectorAll<HTMLAnchorElement>('a[href^="#"]').forEach(link => {
-    const targetId = link.getAttribute('href')?.slice(1)
-    const noteHtml = targetId ? notes.get(targetId) : undefined
-    if (!targetId || !noteHtml) return
-    link.classList.add('fnref')
-    if (!link.textContent?.trim()) {
-      link.textContent = String(noteIndexFromId(targetId) ?? notes.size)
-    }
-    if (doc.getElementById(targetId)) return
-    const note = doc.createElement('span')
-    note.className = 'fn'
-    note.id = targetId
-    note.innerHTML = noteHtml
-    const wrapper = link.closest('sup') ?? link
-    wrapper.replaceWith(note)
-  })
-}
-
-function normalizeInlineFootnoteMarkers(doc: Document): void {
-  doc.body.querySelectorAll<HTMLElement>('.fn[id]').forEach(note => {
-    const id = note.id.trim()
-    if (!id) return
-    doc.body
-      .querySelectorAll<HTMLAnchorElement>(
-        `a.fnref[href="#${cssEscape(id)}"],a[href="#${cssEscape(id)}"]`,
-      )
-      .forEach(link => {
-        const wrapper = link.closest('sup') ?? link
-        if (wrapper.nextElementSibling === note) {
-          wrapper.remove()
-        }
-      })
-  })
-}
-
-function cssEscape(value: string): string {
-  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
-    return CSS.escape(value)
-  }
-  return value.replace(/["\\]/g, '\\$&')
-}
-
-function noteIndexFromId(id: string): number | undefined {
-  const match = /(\d+)$/.exec(id)
-  return match ? Number.parseInt(match[1], 10) : undefined
-}
-
-function parseHtml(html: string): Document {
-  return new DOMParser().parseFromString(html || '', 'text/html')
-}
-
-function collectHardErrors(
-  doc: Document,
-  errors: PureRenderValidationError[],
-): void {
-  doc.body.querySelectorAll('[style]').forEach(element => {
-    errors.push({
-      code: 'forbidden-style-attribute',
-      message: `<${element.tagName.toLowerCase()}> includes a style attribute`,
-    })
-  })
-  doc.body
-    .querySelectorAll('script, style, link, font, center')
-    .forEach(element => {
-      errors.push({
-        code: 'forbidden-element',
-        message: `<${element.tagName.toLowerCase()}> is not allowed in print content`,
-      })
-    })
-  doc.body.querySelectorAll('h1').forEach(element => {
-    if (!element.classList.contains('doc-title')) {
-      errors.push({
-        code: 'invalid-h1',
-        message: 'Only the canonical .doc-title may use h1',
-      })
-    }
-  })
-}
-
-function stripEmptyParagraphs(doc: Document): void {
-  doc.body.querySelectorAll('p').forEach(paragraph => {
-    if (!paragraph.textContent?.trim() && paragraph.children.length === 0) {
-      paragraph.remove()
-    }
-  })
-}
-
-function wrapBareTables(doc: Document): void {
-  doc.body.querySelectorAll('table').forEach(table => {
-    if (table.parentElement?.classList.contains('table-wrap')) return
-    const wrapper = doc.createElement('div')
-    wrapper.className = 'table-wrap'
-    const assetId = table.getAttribute('data-asset-id')
-    if (assetId) {
-      wrapper.setAttribute('data-asset-id', assetId)
-      table.removeAttribute('data-asset-id')
-    }
-    table.replaceWith(wrapper)
-    const caption = table.querySelector('caption')
-    if (caption) {
-      const tcaption = doc.createElement('div')
-      tcaption.className = 'tcaption'
-      tcaption.innerHTML = caption.innerHTML
-      caption.remove()
-      wrapper.append(tcaption)
-    }
-    wrapper.append(table)
-  })
-}
-
-function normalizeReferenceableBlocks(doc: Document): void {
-  doc.body.querySelectorAll<HTMLElement>('[data-asset-id]').forEach(element => {
-    const assetId = element.getAttribute('data-asset-id')?.trim()
-    if (assetId && !element.id) element.id = assetId
-  })
-
-  doc.body
-    .querySelectorAll<HTMLElement>(
-      '[data-type="block-math"],[data-asset-id^="asset_blockMath_"]',
-    )
-    .forEach(element => {
-      element.classList.add('equation')
-      if (!element.querySelector('.eq-body')) {
-        const body = doc.createElement('span')
-        body.className = 'eq-body'
-        body.innerHTML = element.innerHTML
-        element.replaceChildren(body)
-      }
-      if (!element.querySelector('.eq-num')) {
-        const number = doc.createElement('span')
-        number.className = 'eq-num'
-        element.append(number)
-      }
-    })
-}
-
-function normalizeCrossReferenceLinks(doc: Document): void {
-  doc.body
-    .querySelectorAll<HTMLAnchorElement>('a[data-xref-target]')
-    .forEach(link => {
-      const targetId = link.getAttribute('data-xref-target')?.trim()
-      if (!targetId) return
-      link.setAttribute('href', `#${targetId}`)
-      const kind = xrefKindFromTargetId(targetId)
-      if (kind) {
-        link.classList.add(`xref-${kind}`)
-        link.textContent = `${xrefLabelPrefix(kind)} `
-      }
-    })
-}
-
-function xrefKindFromTargetId(targetId: string): 'fig' | 'tbl' | 'eq' | null {
-  if (/^asset_(fig|figure)_/.test(targetId)) return 'fig'
-  if (/^asset_table_/.test(targetId)) return 'tbl'
-  if (/^asset_blockMath_/.test(targetId)) return 'eq'
-  return null
-}
-
-function xrefLabelPrefix(kind: 'fig' | 'tbl' | 'eq'): string {
-  if (kind === 'fig') return 'Figure'
-  if (kind === 'tbl') return 'Table'
-  return 'Equation'
-}
-
-function normalizeHeadings(doc: Document): void {
-  doc.body.querySelectorAll('h1:not(.doc-title)').forEach(heading => {
-    const next = doc.createElement('h2')
-    next.innerHTML = heading.innerHTML
-    copySafeAttributes(heading, next)
-    heading.replaceWith(next)
-  })
-}
-
-function normalizeSections(
-  doc: Document,
-  errors: PureRenderValidationError[],
-): void {
-  doc.body.querySelectorAll('section[data-type]').forEach(section => {
-    const type = section.getAttribute('data-type')?.trim()
-    if (type && !ALLOWED_DATA_TYPES.has(type)) {
-      errors.push({
-        code: 'unknown-data-type',
-        message: `Unknown section data-type "${type}"`,
-      })
-    }
-  })
-}
-
-function assignMissingIds(doc: Document): void {
-  const used = new Set<string>()
-  doc.body.querySelectorAll('[id]').forEach(element => {
-    const id = element.id.trim()
-    if (id) used.add(id)
-  })
-  doc.body
-    .querySelectorAll('h2,h3,h4,figure,.table-wrap,.equation')
-    .forEach((element, index) => {
-      if (element.id) return
-      const base =
-        slugify(element.textContent?.trim() || element.className || 'item') ||
-        `item-${index + 1}`
-      let id = base
-      let suffix = 2
-      while (used.has(id)) {
-        id = `${base}-${suffix}`
-        suffix += 1
-      }
-      element.id = id
-      used.add(id)
-    })
-}
-
-function materializeReferenceLabels(
-  doc: Document,
-  profile: PureRenderProfile,
-): void {
-  if (profile === 'book') {
-    assignChapterScopedLabels(doc, 'figure', 'figure')
-    assignChapterScopedLabels(doc, '.table-wrap', 'table')
-    assignChapterScopedLabels(doc, '.equation', 'equation')
-  } else {
-    assignSequentialLabels(doc, 'figure', 'figure')
-    assignSequentialLabels(doc, '.table-wrap', 'table')
-    assignSequentialLabels(doc, '.equation', 'equation')
-  }
-
-  doc.body
-    .querySelectorAll<HTMLAnchorElement>(
-      'a.xref-fig[href^="#"],a.xref-tbl[href^="#"],a.xref-eq[href^="#"]',
-    )
-    .forEach(link => {
-      const id = link.getAttribute('href')?.slice(1)
-      const target = id ? doc.getElementById(id) : null
-      const label = target?.getAttribute('data-label')?.trim()
-      const kind = link.classList.contains('xref-fig')
-        ? 'fig'
-        : link.classList.contains('xref-tbl')
-        ? 'tbl'
-        : 'eq'
-      link.textContent = label
-        ? `${xrefLabelPrefix(kind)} ${label}`
-        : xrefLabelPrefix(kind)
-    })
-}
-
-function normalizeCitationLinks(doc: Document): void {
-  const referenceIds = new Set<string>()
-  doc.body
-    .querySelectorAll<HTMLElement>(
-      'section[data-type="references"] [id],.pm-references [id],.paper-references [id]',
-    )
-    .forEach(element => referenceIds.add(element.id))
-
-  doc.body
-    .querySelectorAll<HTMLElement>('cite[data-ref-ids]')
-    .forEach(cite => {
-      const refIds = (cite.getAttribute('data-ref-ids') ?? '')
-        .split(',')
-        .map(id => id.trim())
-        .filter(Boolean)
-      if (refIds.length === 0) return
-
-      const targets = refIds.map(refId => citationTargetFor(refId, referenceIds))
-      if (targets.some(target => !target)) return
-
-      cite.classList.add('ps-citation')
-      const labels = citationLabels(cite.textContent ?? '', refIds.length)
-      cite.replaceChildren()
-      if (targets.length === 1) {
-        cite.append(citationAnchor(doc, targets[0] as string, labels[0]))
-        return
-      }
-      cite.append(doc.createTextNode('['))
-      targets.forEach((target, index) => {
-        if (index > 0) cite.append(doc.createTextNode(', '))
-        cite.append(citationAnchor(doc, target as string, labels[index]))
-      })
-      cite.append(doc.createTextNode(']'))
-    })
-}
-
-function citationTargetFor(
-  refId: string,
-  referenceIds: Set<string>,
-): string | null {
-  const entryId = `ref-entry-${refId}`
-  if (referenceIds.has(entryId)) return entryId
-  if (referenceIds.has(refId)) return refId
-  return null
-}
-
-function citationLabels(text: string, count: number): string[] {
-  if (count === 1) return [text.trim() || '[?]']
-  const numbers = text.match(/\d+/g) ?? []
-  if (numbers.length >= count) return numbers.slice(0, count)
-  return Array.from({ length: count }, (_, index) => String(index + 1))
-}
-
-function citationAnchor(doc: Document, targetId: string, label: string): Element {
-  const anchor = doc.createElement('a')
-  anchor.setAttribute('href', `#${targetId}`)
-  anchor.textContent = label
-  return anchor
-}
-
-function assignChapterScopedLabels(
-  doc: Document,
-  selector: string,
-  labelName: 'figure' | 'table' | 'equation',
-): void {
-  const labelled = new Set<HTMLElement>()
-  let chapterIndex = 0
-  doc.body
-    .querySelectorAll<HTMLElement>('section[data-type="chapter"]')
-    .forEach(chapter => {
-      chapterIndex += 1
-      let itemIndex = 0
-      chapter.querySelectorAll<HTMLElement>(selector).forEach(element => {
-        itemIndex += 1
-        applyMaterializedLabel(
-          element,
-          `${chapterIndex}.${itemIndex}`,
-          labelName,
-        )
-        labelled.add(element)
-      })
-    })
-
-  let fallbackIndex = 0
-  doc.body.querySelectorAll<HTMLElement>(selector).forEach(element => {
-    if (labelled.has(element)) return
-    fallbackIndex += 1
-    applyMaterializedLabel(element, String(fallbackIndex), labelName)
-  })
-}
-
-function assignSequentialLabels(
-  doc: Document,
-  selector: string,
-  labelName: 'figure' | 'table' | 'equation',
-): void {
-  let index = 0
-  doc.body.querySelectorAll<HTMLElement>(selector).forEach(element => {
-    index += 1
-    applyMaterializedLabel(element, String(index), labelName)
-  })
-}
-
-function applyMaterializedLabel(
-  element: HTMLElement,
-  label: string,
-  labelName: 'figure' | 'table' | 'equation',
-): void {
-  element.setAttribute('data-label', label)
-  element.setAttribute('data-label-kind', labelName)
-  if (labelName === 'figure') {
-    element.querySelector('figcaption')?.setAttribute('data-label', label)
-  } else if (labelName === 'table') {
-    element.querySelector('.tcaption')?.setAttribute('data-label', label)
-  } else {
-    element.querySelector('.eq-num')?.setAttribute('data-label', label)
-  }
-}
-
-function validateCrossReferences(
-  doc: Document,
-  errors: PureRenderValidationError[],
-): void {
-  const ids = new Set<string>()
-  doc.body.querySelectorAll('[id]').forEach(element => ids.add(element.id))
-  for (const selector of XREF_SELECTORS) {
-    doc.body.querySelectorAll<HTMLAnchorElement>(selector).forEach(link => {
-      const id = link.getAttribute('href')?.slice(1)
-      if (id && !ids.has(id)) {
-        errors.push({
-          code: 'unresolved-xref',
-          message: `Cross-reference target "#${id}" does not exist`,
-        })
-      }
-    })
-  }
-}
-
-function buildCanonicalArticle(
-  doc: Document,
-  metadata: PureRenderMetadata | undefined,
-): HTMLElement {
-  const existingArticle = doc.body.querySelector('article')
-  const article = doc.createElement('article')
-  const lang =
-    existingArticle?.getAttribute('lang') ||
-    doc.documentElement.getAttribute('lang') ||
-    'en'
-  article.setAttribute('lang', lang)
-
-  const contentSource = existingArticle ?? doc.body
-  const existingTitle = contentSource.querySelector('.doc-title')
-  const existingTitleHtml = existingTitle?.outerHTML
-  if (existingTitle && !metadata?.title?.trim()) existingTitle.remove()
-  const metadataTitle = metadata?.title?.trim()
-  const content = removeDuplicateLeadingTitle(
-    contentSource.innerHTML,
-    metadataTitle,
-  )
-
-  const frontMatter = buildFrontMatter(metadata, existingTitleHtml)
-  article.innerHTML = `${frontMatter}${content}`.trim()
-  return article
-}
-
-function buildFrontMatter(
-  metadata: PureRenderMetadata | undefined,
-  existingTitleHtml: string | undefined,
-): string {
-  const parts: string[] = []
-  if (metadata?.title?.trim()) {
-    parts.push(
-      `<h1 class="doc-title">${escapeHtml(metadata.title.trim())}</h1>`,
-    )
-  } else if (existingTitleHtml) {
-    parts.push(existingTitleHtml)
-  }
-
-  const authors = metadata?.authorsHtml ?? metadata?.authorsText
-  if (authors?.trim()) {
-    parts.push(
-      `<p class="authors">${
-        metadata?.authorsHtml
-          ? sanitizeMetadataInlineHtml(authors)
-          : escapeHtml(authors.trim())
-      }</p>`,
-    )
-  }
-
-  const affiliations = metadata?.affiliationsHtml ?? metadata?.affiliationsText
-  if (affiliations?.trim()) {
-    parts.push(
-      `<p class="affil">${
-        metadata?.affiliationsHtml
-          ? sanitizeMetadataInlineHtml(affiliations)
-          : escapeHtml(affiliations.trim())
-      }</p>`,
-    )
-  }
-
-  const abstract = metadata?.abstractHtml ?? metadata?.abstractText
-  if (abstract?.trim()) {
-    const abstractHtml = metadata?.abstractHtml
-      ? sanitizeMetadataBlockHtml(abstract)
-      : abstract
-          .trim()
-          .split(/\n{2,}/)
-          .map(paragraph => `<p>${escapeHtml(paragraph.trim())}</p>`)
-          .join('\n')
-    parts.push(
-      `<section data-type="abstract"><h2>Abstract</h2>\n${abstractHtml}</section>`,
-    )
-  }
-
-  if (metadata?.keywords?.length) {
-    parts.push(
-      `<p class="keywords"><b>Keywords:</b> ${metadata.keywords
-        .map(keyword => escapeHtml(keyword))
-        .join(', ')}</p>`,
-    )
-  }
-
-  return parts.join('\n')
-}
-
-function sanitizeMetadataInlineHtml(html: string): string {
-  const doc = parseHtml(`<div>${html}</div>`)
-  const root = doc.body.firstElementChild
-  if (!root) return ''
-  sanitizeMetadataNode(root, 'inline')
-  return root.innerHTML.trim()
-}
-
-function sanitizeMetadataBlockHtml(html: string): string {
-  const doc = parseHtml(`<div>${html}</div>`)
-  const root = doc.body.firstElementChild
-  if (!root) return ''
-  sanitizeMetadataNode(root, 'block')
-  return root.innerHTML.trim()
-}
-
-function sanitizeMetadataNode(node: Element, mode: 'inline' | 'block'): void {
-  for (const child of Array.from(node.children)) {
-    const tag = child.tagName.toLowerCase()
-    if (['script', 'style', 'link', 'font', 'center'].includes(tag)) {
-      child.remove()
-      continue
-    }
-    if (!isAllowedMetadataTag(tag, mode)) {
-      sanitizeMetadataNode(child, mode)
-      child.replaceWith(...Array.from(child.childNodes))
-      continue
-    }
-    sanitizeMetadataAttributes(child)
-    sanitizeMetadataNode(child, mode)
-  }
-}
-
-function isAllowedMetadataTag(tag: string, mode: 'inline' | 'block'): boolean {
-  const inlineTags = [
-    'a',
-    'span',
-    'sup',
-    'sub',
-    'strong',
-    'b',
-    'em',
-    'i',
-    'code',
-    'br',
-  ]
-  const blockTags = ['p', 'ul', 'ol', 'li', 'blockquote']
-  return (
-    inlineTags.includes(tag) || (mode === 'block' && blockTags.includes(tag))
-  )
-}
-
-function sanitizeMetadataAttributes(element: Element): void {
-  for (const attr of Array.from(element.attributes)) {
-    const name = attr.name.toLowerCase()
-    if (
-      name === 'style' ||
-      name.startsWith('on') ||
-      (!['class', 'id', 'href', 'title', 'aria-label'].includes(name) &&
-        !name.startsWith('data-'))
-    ) {
-      element.removeAttribute(attr.name)
-      continue
-    }
-    if (name === 'href' && !/^(https?:|mailto:|#)/i.test(attr.value.trim())) {
-      element.removeAttribute(attr.name)
-    }
-  }
-}
-
-function copySafeAttributes(from: Element, to: Element): void {
-  for (const attr of Array.from(from.attributes)) {
-    if (attr.name === 'style') continue
-    to.setAttribute(attr.name, attr.value)
-  }
-}
-
-function removeDuplicateLeadingTitle(
-  html: string,
-  title: string | undefined,
-): string {
-  const normalizedTitle = normalizeText(title ?? '')
-  if (!normalizedTitle) return html
-  const match = /^\s*<h[12]\b[^>]*>([\s\S]*?)<\/h[12]>/i.exec(html)
-  if (!match) return html
-  const headingText = normalizeText(match[1].replace(/<[^>]+>/g, ' '))
-  if (headingText !== normalizedTitle) return html
-  return html.slice(match[0].length)
-}
-
-function titleFromDocument(html: string): string | null {
-  const match = /<h[12]\b[^>]*>([\s\S]*?)<\/h[12]>/i.exec(html)
-  if (!match) return null
-  const text = displayText(match[1].replace(/<[^>]+>/g, ' '))
-  return text || null
-}
-
-function displayText(value: string): string {
-  return value.replace(/\s+/g, ' ').trim()
-}
-
-function normalizeText(value: string): string {
-  return value.replace(/\s+/g, ' ').trim().toLowerCase()
-}
-
-function slugify(value: string): string {
-  return value
-    .toLowerCase()
-    .replace(/<[^>]+>/g, '')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '')
-}
+import { escapeHtml } from '../printDocument.js'
+import type {
+  PureRenderMetadata,
+  PureRenderNormalizeResult,
+  PureRenderOptions,
+  PureRenderProfile,
+  PureRenderValidationError,
+} from './types.js'
+
+const ALLOWED_DATA_TYPES = new Set([
+  'abstract',
+  'part',
+  'chapter',
+  'appendix',
+  'references',
+  'acknowledgments',
+  'toc',
+  'frontmatter',
+  'backmatter',
+  'footnotes',
+  'endnotes',
+])
+
+const XREF_SELECTORS = [
+  'a.xref-fig[href^="#"]',
+  'a.xref-tbl[href^="#"]',
+  'a.xref-eq[href^="#"]',
+  'a.xref-sec[href^="#"]',
+  'a.fnref[href^="#"]',
+]
+
+export function normalizePureRenderHtml(options: {
+  html: string
+  profile: PureRenderProfile
+  metadata?: PureRenderMetadata
+  options?: PureRenderOptions
+}): PureRenderNormalizeResult {
+  const doc = parseHtml(options.html)
+  const errors: PureRenderValidationError[] = []
+
+  stripEditorTablePresentation(doc)
+  collectHardErrors(doc, errors)
+  stripEmptyParagraphs(doc)
+  wrapBareTables(doc)
+  normalizeReferenceableBlocks(doc)
+  normalizeCrossReferenceLinks(doc)
+  normalizeFootnotes(doc)
+  normalizeInlineFootnoteMarkers(doc)
+  normalizeHeadings(doc)
+  normalizeSections(doc, errors)
+  assignMissingIds(doc)
+  materializeReferenceLabels(doc, options.profile)
+  normalizeCitationLinks(doc)
+  validateCrossReferences(doc, errors)
+
+  const article = buildCanonicalArticle(doc, options.metadata)
+  const lang = article.getAttribute('lang')?.trim() || 'en'
+  article.setAttribute('lang', lang)
+  if (options.options?.variant) {
+    article.setAttribute('data-variant', options.options.variant)
+  }
+
+  const title =
+    options.metadata?.title?.trim() ||
+    article.querySelector('.doc-title')?.textContent?.trim() ||
+    titleFromDocument(doc.body.innerHTML) ||
+    'Document'
+
+  return { html: article.outerHTML, title, errors }
+}
+
+function stripEditorTablePresentation(doc: Document): void {
+  doc.body.querySelectorAll('table,colgroup,col').forEach(element => {
+    element.removeAttribute('style')
+  })
+}
+
+function normalizeFootnotes(doc: Document): void {
+  const notes = new Map<string, string>()
+  doc.body
+    .querySelectorAll<HTMLElement>(
+      'section.footnotes, aside.footnotes, section[data-type="footnotes"]',
+    )
+    .forEach(container => {
+      container.querySelectorAll<HTMLElement>('li[id]').forEach(item => {
+        const id = item.id.trim()
+        if (!id) return
+        const clone = item.cloneNode(true) as HTMLElement
+        clone
+          .querySelectorAll<HTMLAnchorElement>(
+            'a[href^="#fnref"],a[rev="footnote"]',
+          )
+          .forEach(backlink => backlink.remove())
+        notes.set(id, clone.innerHTML.trim())
+      })
+      container.remove()
+    })
+
+  if (notes.size === 0) return
+
+  doc.body.querySelectorAll<HTMLAnchorElement>('a[href^="#"]').forEach(link => {
+    const targetId = link.getAttribute('href')?.slice(1)
+    const noteHtml = targetId ? notes.get(targetId) : undefined
+    if (!targetId || !noteHtml) return
+    link.classList.add('fnref')
+    if (!link.textContent?.trim()) {
+      link.textContent = String(noteIndexFromId(targetId) ?? notes.size)
+    }
+    if (doc.getElementById(targetId)) return
+    const note = doc.createElement('span')
+    note.className = 'fn'
+    note.id = targetId
+    note.innerHTML = noteHtml
+    const wrapper = link.closest('sup') ?? link
+    wrapper.replaceWith(note)
+  })
+}
+
+function normalizeInlineFootnoteMarkers(doc: Document): void {
+  doc.body.querySelectorAll<HTMLElement>('.fn[id]').forEach(note => {
+    const id = note.id.trim()
+    if (!id) return
+    doc.body
+      .querySelectorAll<HTMLAnchorElement>(
+        `a.fnref[href="#${cssEscape(id)}"],a[href="#${cssEscape(id)}"]`,
+      )
+      .forEach(link => {
+        const wrapper = link.closest('sup') ?? link
+        if (wrapper.nextElementSibling === note) {
+          wrapper.remove()
+        }
+      })
+  })
+}
+
+function cssEscape(value: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(value)
+  }
+  return value.replace(/["\\]/g, '\\$&')
+}
+
+function noteIndexFromId(id: string): number | undefined {
+  const match = /(\d+)$/.exec(id)
+  return match ? Number.parseInt(match[1], 10) : undefined
+}
+
+function parseHtml(html: string): Document {
+  return new DOMParser().parseFromString(html || '', 'text/html')
+}
+
+function collectHardErrors(
+  doc: Document,
+  errors: PureRenderValidationError[],
+): void {
+  doc.body.querySelectorAll('[style]').forEach(element => {
+    errors.push({
+      code: 'forbidden-style-attribute',
+      message: `<${element.tagName.toLowerCase()}> includes a style attribute`,
+    })
+  })
+  doc.body
+    .querySelectorAll('script, style, link, font, center')
+    .forEach(element => {
+      errors.push({
+        code: 'forbidden-element',
+        message: `<${element.tagName.toLowerCase()}> is not allowed in print content`,
+      })
+    })
+  doc.body.querySelectorAll('h1').forEach(element => {
+    if (!element.classList.contains('doc-title')) {
+      errors.push({
+        code: 'invalid-h1',
+        message: 'Only the canonical .doc-title may use h1',
+      })
+    }
+  })
+}
+
+function stripEmptyParagraphs(doc: Document): void {
+  doc.body.querySelectorAll('p').forEach(paragraph => {
+    if (!paragraph.textContent?.trim() && paragraph.children.length === 0) {
+      paragraph.remove()
+    }
+  })
+}
+
+function wrapBareTables(doc: Document): void {
+  doc.body.querySelectorAll('table').forEach(table => {
+    if (table.parentElement?.classList.contains('table-wrap')) return
+    const wrapper = doc.createElement('div')
+    wrapper.className = 'table-wrap'
+    const assetId = table.getAttribute('data-asset-id')
+    if (assetId) {
+      wrapper.setAttribute('data-asset-id', assetId)
+      table.removeAttribute('data-asset-id')
+    }
+    table.replaceWith(wrapper)
+    const caption = table.querySelector('caption')
+    if (caption) {
+      const tcaption = doc.createElement('div')
+      tcaption.className = 'tcaption'
+      tcaption.innerHTML = caption.innerHTML
+      caption.remove()
+      wrapper.append(tcaption)
+    }
+    wrapper.append(table)
+  })
+}
+
+function normalizeReferenceableBlocks(doc: Document): void {
+  doc.body.querySelectorAll<HTMLElement>('[data-asset-id]').forEach(element => {
+    const assetId = element.getAttribute('data-asset-id')?.trim()
+    if (assetId && !element.id) element.id = assetId
+  })
+
+  doc.body
+    .querySelectorAll<HTMLElement>(
+      '[data-type="block-math"],[data-asset-id^="asset_blockMath_"]',
+    )
+    .forEach(element => {
+      element.classList.add('equation')
+      if (!element.querySelector('.eq-body')) {
+        const body = doc.createElement('span')
+        body.className = 'eq-body'
+        body.innerHTML = element.innerHTML
+        element.replaceChildren(body)
+      }
+      if (!element.querySelector('.eq-num')) {
+        const number = doc.createElement('span')
+        number.className = 'eq-num'
+        element.append(number)
+      }
+    })
+}
+
+function normalizeCrossReferenceLinks(doc: Document): void {
+  doc.body
+    .querySelectorAll<HTMLAnchorElement>('a[data-xref-target]')
+    .forEach(link => {
+      const targetId = link.getAttribute('data-xref-target')?.trim()
+      if (!targetId) return
+      link.setAttribute('href', `#${targetId}`)
+      const kind = xrefKindFromTargetId(targetId)
+      if (kind) {
+        link.classList.add(`xref-${kind}`)
+        link.textContent = `${xrefLabelPrefix(kind)} `
+      }
+    })
+}
+
+function xrefKindFromTargetId(targetId: string): 'fig' | 'tbl' | 'eq' | null {
+  if (/^asset_(fig|figure)_/.test(targetId)) return 'fig'
+  if (/^asset_table_/.test(targetId)) return 'tbl'
+  if (/^asset_blockMath_/.test(targetId)) return 'eq'
+  return null
+}
+
+function xrefLabelPrefix(kind: 'fig' | 'tbl' | 'eq'): string {
+  if (kind === 'fig') return 'Figure'
+  if (kind === 'tbl') return 'Table'
+  return 'Equation'
+}
+
+function normalizeHeadings(doc: Document): void {
+  doc.body.querySelectorAll('h1:not(.doc-title)').forEach(heading => {
+    const next = doc.createElement('h2')
+    next.innerHTML = heading.innerHTML
+    copySafeAttributes(heading, next)
+    heading.replaceWith(next)
+  })
+}
+
+function normalizeSections(
+  doc: Document,
+  errors: PureRenderValidationError[],
+): void {
+  doc.body.querySelectorAll('section[data-type]').forEach(section => {
+    const type = section.getAttribute('data-type')?.trim()
+    if (type && !ALLOWED_DATA_TYPES.has(type)) {
+      errors.push({
+        code: 'unknown-data-type',
+        message: `Unknown section data-type "${type}"`,
+      })
+    }
+  })
+}
+
+function assignMissingIds(doc: Document): void {
+  const used = new Set<string>()
+  doc.body.querySelectorAll('[id]').forEach(element => {
+    const id = element.id.trim()
+    if (id) used.add(id)
+  })
+  doc.body
+    .querySelectorAll('h2,h3,h4,figure,.table-wrap,.equation')
+    .forEach((element, index) => {
+      if (element.id) return
+      const base =
+        slugify(element.textContent?.trim() || element.className || 'item') ||
+        `item-${index + 1}`
+      let id = base
+      let suffix = 2
+      while (used.has(id)) {
+        id = `${base}-${suffix}`
+        suffix += 1
+      }
+      element.id = id
+      used.add(id)
+    })
+}
+
+function materializeReferenceLabels(
+  doc: Document,
+  profile: PureRenderProfile,
+): void {
+  if (profile === 'book') {
+    assignChapterScopedLabels(doc, 'figure', 'figure')
+    assignChapterScopedLabels(doc, '.table-wrap', 'table')
+    assignChapterScopedLabels(doc, '.equation', 'equation')
+  } else {
+    assignSequentialLabels(doc, 'figure', 'figure')
+    assignSequentialLabels(doc, '.table-wrap', 'table')
+    assignSequentialLabels(doc, '.equation', 'equation')
+  }
+
+  doc.body
+    .querySelectorAll<HTMLAnchorElement>(
+      'a.xref-fig[href^="#"],a.xref-tbl[href^="#"],a.xref-eq[href^="#"]',
+    )
+    .forEach(link => {
+      const id = link.getAttribute('href')?.slice(1)
+      const target = id ? doc.getElementById(id) : null
+      const label = target?.getAttribute('data-label')?.trim()
+      const kind = link.classList.contains('xref-fig')
+        ? 'fig'
+        : link.classList.contains('xref-tbl')
+        ? 'tbl'
+        : 'eq'
+      link.textContent = label
+        ? `${xrefLabelPrefix(kind)} ${label}`
+        : xrefLabelPrefix(kind)
+    })
+}
+
+function normalizeCitationLinks(doc: Document): void {
+  const referenceIds = new Set<string>()
+  doc.body
+    .querySelectorAll<HTMLElement>(
+      'section[data-type="references"] [id],.pm-references [id],.paper-references [id]',
+    )
+    .forEach(element => referenceIds.add(element.id))
+
+  doc.body
+    .querySelectorAll<HTMLElement>('cite[data-ref-ids]')
+    .forEach(cite => {
+      const refIds = (cite.getAttribute('data-ref-ids') ?? '')
+        .split(',')
+        .map(id => id.trim())
+        .filter(Boolean)
+      if (refIds.length === 0) return
+
+      const targets = refIds.map(refId => citationTargetFor(refId, referenceIds))
+      if (targets.some(target => !target)) return
+
+      cite.classList.add('ps-citation')
+      const labels = citationLabels(cite.textContent ?? '', refIds.length)
+      cite.replaceChildren()
+      if (targets.length === 1) {
+        cite.append(citationAnchor(doc, targets[0] as string, labels[0]))
+        return
+      }
+      cite.append(doc.createTextNode('['))
+      targets.forEach((target, index) => {
+        if (index > 0) cite.append(doc.createTextNode(', '))
+        cite.append(citationAnchor(doc, target as string, labels[index]))
+      })
+      cite.append(doc.createTextNode(']'))
+    })
+}
+
+function citationTargetFor(
+  refId: string,
+  referenceIds: Set<string>,
+): string | null {
+  const entryId = `ref-entry-${refId}`
+  if (referenceIds.has(entryId)) return entryId
+  if (referenceIds.has(refId)) return refId
+  return null
+}
+
+function citationLabels(text: string, count: number): string[] {
+  if (count === 1) return [text.trim() || '[?]']
+  const numbers = text.match(/\d+/g) ?? []
+  if (numbers.length >= count) return numbers.slice(0, count)
+  return Array.from({ length: count }, (_, index) => String(index + 1))
+}
+
+function citationAnchor(doc: Document, targetId: string, label: string): Element {
+  const anchor = doc.createElement('a')
+  anchor.setAttribute('href', `#${targetId}`)
+  anchor.textContent = label
+  return anchor
+}
+
+function assignChapterScopedLabels(
+  doc: Document,
+  selector: string,
+  labelName: 'figure' | 'table' | 'equation',
+): void {
+  const labelled = new Set<HTMLElement>()
+  let chapterIndex = 0
+  doc.body
+    .querySelectorAll<HTMLElement>('section[data-type="chapter"]')
+    .forEach(chapter => {
+      chapterIndex += 1
+      let itemIndex = 0
+      chapter.querySelectorAll<HTMLElement>(selector).forEach(element => {
+        itemIndex += 1
+        applyMaterializedLabel(
+          element,
+          `${chapterIndex}.${itemIndex}`,
+          labelName,
+        )
+        labelled.add(element)
+      })
+    })
+
+  let fallbackIndex = 0
+  doc.body.querySelectorAll<HTMLElement>(selector).forEach(element => {
+    if (labelled.has(element)) return
+    fallbackIndex += 1
+    applyMaterializedLabel(element, String(fallbackIndex), labelName)
+  })
+}
+
+function assignSequentialLabels(
+  doc: Document,
+  selector: string,
+  labelName: 'figure' | 'table' | 'equation',
+): void {
+  let index = 0
+  doc.body.querySelectorAll<HTMLElement>(selector).forEach(element => {
+    index += 1
+    applyMaterializedLabel(element, String(index), labelName)
+  })
+}
+
+function applyMaterializedLabel(
+  element: HTMLElement,
+  label: string,
+  labelName: 'figure' | 'table' | 'equation',
+): void {
+  element.setAttribute('data-label', label)
+  element.setAttribute('data-label-kind', labelName)
+  if (labelName === 'figure') {
+    element.querySelector('figcaption')?.setAttribute('data-label', label)
+  } else if (labelName === 'table') {
+    element.querySelector('.tcaption')?.setAttribute('data-label', label)
+  } else {
+    element.querySelector('.eq-num')?.setAttribute('data-label', label)
+  }
+}
+
+function validateCrossReferences(
+  doc: Document,
+  errors: PureRenderValidationError[],
+): void {
+  const ids = new Set<string>()
+  doc.body.querySelectorAll('[id]').forEach(element => ids.add(element.id))
+  for (const selector of XREF_SELECTORS) {
+    doc.body.querySelectorAll<HTMLAnchorElement>(selector).forEach(link => {
+      const id = link.getAttribute('href')?.slice(1)
+      if (id && !ids.has(id)) {
+        errors.push({
+          code: 'unresolved-xref',
+          message: `Cross-reference target "#${id}" does not exist`,
+        })
+      }
+    })
+  }
+}
+
+function buildCanonicalArticle(
+  doc: Document,
+  metadata: PureRenderMetadata | undefined,
+): HTMLElement {
+  const existingArticle = doc.body.querySelector('article')
+  const article = doc.createElement('article')
+  const lang =
+    existingArticle?.getAttribute('lang') ||
+    doc.documentElement.getAttribute('lang') ||
+    'en'
+  article.setAttribute('lang', lang)
+
+  const contentSource = existingArticle ?? doc.body
+  const existingTitle = contentSource.querySelector('.doc-title')
+  const existingTitleHtml = existingTitle?.outerHTML
+  if (existingTitle && !metadata?.title?.trim()) existingTitle.remove()
+  const metadataTitle = metadata?.title?.trim()
+  const content = removeDuplicateLeadingTitle(
+    contentSource.innerHTML,
+    metadataTitle,
+  )
+
+  const frontMatter = buildFrontMatter(metadata, existingTitleHtml)
+  article.innerHTML = `${frontMatter}${content}`.trim()
+  return article
+}
+
+function buildFrontMatter(
+  metadata: PureRenderMetadata | undefined,
+  existingTitleHtml: string | undefined,
+): string {
+  const parts: string[] = []
+  if (metadata?.title?.trim()) {
+    parts.push(
+      `<h1 class="doc-title">${escapeHtml(metadata.title.trim())}</h1>`,
+    )
+  } else if (existingTitleHtml) {
+    parts.push(existingTitleHtml)
+  }
+
+  const authors = metadata?.authorsHtml ?? metadata?.authorsText
+  if (authors?.trim()) {
+    parts.push(
+      `<p class="authors">${
+        metadata?.authorsHtml
+          ? sanitizeMetadataInlineHtml(authors)
+          : escapeHtml(authors.trim())
+      }</p>`,
+    )
+  }
+
+  const affiliations = metadata?.affiliationsHtml ?? metadata?.affiliationsText
+  if (affiliations?.trim()) {
+    parts.push(
+      `<p class="affil">${
+        metadata?.affiliationsHtml
+          ? sanitizeMetadataInlineHtml(affiliations)
+          : escapeHtml(affiliations.trim())
+      }</p>`,
+    )
+  }
+
+  const abstract = metadata?.abstractHtml ?? metadata?.abstractText
+  if (abstract?.trim()) {
+    const abstractHtml = metadata?.abstractHtml
+      ? sanitizeMetadataBlockHtml(abstract)
+      : abstract
+          .trim()
+          .split(/\n{2,}/)
+          .map(paragraph => `<p>${escapeHtml(paragraph.trim())}</p>`)
+          .join('\n')
+    parts.push(
+      `<section data-type="abstract"><h2>Abstract</h2>\n${abstractHtml}</section>`,
+    )
+  }
+
+  if (metadata?.keywords?.length) {
+    parts.push(
+      `<p class="keywords"><b>Keywords:</b> ${metadata.keywords
+        .map(keyword => escapeHtml(keyword))
+        .join(', ')}</p>`,
+    )
+  }
+
+  return parts.join('\n')
+}
+
+function sanitizeMetadataInlineHtml(html: string): string {
+  const doc = parseHtml(`<div>${html}</div>`)
+  const root = doc.body.firstElementChild
+  if (!root) return ''
+  sanitizeMetadataNode(root, 'inline')
+  return root.innerHTML.trim()
+}
+
+function sanitizeMetadataBlockHtml(html: string): string {
+  const doc = parseHtml(`<div>${html}</div>`)
+  const root = doc.body.firstElementChild
+  if (!root) return ''
+  sanitizeMetadataNode(root, 'block')
+  return root.innerHTML.trim()
+}
+
+function sanitizeMetadataNode(node: Element, mode: 'inline' | 'block'): void {
+  for (const child of Array.from(node.children)) {
+    const tag = child.tagName.toLowerCase()
+    if (['script', 'style', 'link', 'font', 'center'].includes(tag)) {
+      child.remove()
+      continue
+    }
+    if (!isAllowedMetadataTag(tag, mode)) {
+      sanitizeMetadataNode(child, mode)
+      child.replaceWith(...Array.from(child.childNodes))
+      continue
+    }
+    sanitizeMetadataAttributes(child)
+    sanitizeMetadataNode(child, mode)
+  }
+}
+
+function isAllowedMetadataTag(tag: string, mode: 'inline' | 'block'): boolean {
+  const inlineTags = [
+    'a',
+    'span',
+    'sup',
+    'sub',
+    'strong',
+    'b',
+    'em',
+    'i',
+    'code',
+    'br',
+  ]
+  const blockTags = ['p', 'ul', 'ol', 'li', 'blockquote']
+  return (
+    inlineTags.includes(tag) || (mode === 'block' && blockTags.includes(tag))
+  )
+}
+
+function sanitizeMetadataAttributes(element: Element): void {
+  for (const attr of Array.from(element.attributes)) {
+    const name = attr.name.toLowerCase()
+    if (
+      name === 'style' ||
+      name.startsWith('on') ||
+      (!['class', 'id', 'href', 'title', 'aria-label'].includes(name) &&
+        !name.startsWith('data-'))
+    ) {
+      element.removeAttribute(attr.name)
+      continue
+    }
+    if (name === 'href' && !/^(https?:|mailto:|#)/i.test(attr.value.trim())) {
+      element.removeAttribute(attr.name)
+    }
+  }
+}
+
+function copySafeAttributes(from: Element, to: Element): void {
+  for (const attr of Array.from(from.attributes)) {
+    if (attr.name === 'style') continue
+    to.setAttribute(attr.name, attr.value)
+  }
+}
+
+function removeDuplicateLeadingTitle(
+  html: string,
+  title: string | undefined,
+): string {
+  const normalizedTitle = normalizeText(title ?? '')
+  if (!normalizedTitle) return html
+  const match = /^\s*<h[12]\b[^>]*>([\s\S]*?)<\/h[12]>/i.exec(html)
+  if (!match) return html
+  const headingText = normalizeText(match[1].replace(/<[^>]+>/g, ' '))
+  if (headingText !== normalizedTitle) return html
+  return html.slice(match[0].length)
+}
+
+function titleFromDocument(html: string): string | null {
+  const match = /<h[12]\b[^>]*>([\s\S]*?)<\/h[12]>/i.exec(html)
+  if (!match) return null
+  const text = displayText(match[1].replace(/<[^>]+>/g, ' '))
+  return text || null
+}
+
+function displayText(value: string): string {
+  return value.replace(/\s+/g, ' ').trim()
+}
+
+function normalizeText(value: string): string {
+  return value.replace(/\s+/g, ' ').trim().toLowerCase()
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/<[^>]+>/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}