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

package/src/bridge/pureRender/compiler.ts

@@ -1,660 +1,660 @@
-import { DEFAULT_PURE_RENDER_THEME } from './theme.js'
-import type {
-  CompilePrintThemeResult,
-  PureRenderProfileRules,
-  PrintStyleProfile,
-  PureRenderTheme,
-} from './types.js'
-
-const CONF_FLOOR = 0.6
-const MANUSCRIPT_SURFACE_CONF_FLOOR = 0.95
-const AA = 4.5
-const BODY_PT = 10.6
-
-const LIBRARY: {
-  display: Record<string, string>
-  body: Record<string, string>
-  caption: Record<string, string>
-  mono: string
-} = {
-  display: {
-    'serif:bracketed': '"Source Serif 4", Georgia, serif',
-    'serif:hairline': '"Newsreader", Georgia, serif',
-    'serif:slab': '"Roboto Slab", Georgia, serif',
-    'serif:wedge': '"Spectral", Georgia, serif',
-    sans: '"Archivo", system-ui, sans-serif',
-    slab: '"Roboto Slab", serif',
-  },
-  body: {
-    'serif:bracketed': '"Source Serif 4", Georgia, serif',
-    'serif:hairline': '"Newsreader", Georgia, serif',
-    'serif:wedge': '"Spectral", Georgia, serif',
-    sans: '"Source Sans 3", system-ui, sans-serif',
-  },
-  caption: {
-    sans: '"Archivo", system-ui, sans-serif',
-    'serif:bracketed': '"Source Serif 4", serif',
-  },
-  mono: '"JetBrains Mono", ui-monospace, monospace',
-} as const
-
-const RATIO: Record<string, number> = {
-  dramatic: 1.414,
-  moderate: 1.333,
-  subtle: 1.2,
-}
-
-const LEAD: Record<string, number> = {
-  tight: 1.35,
-  normal: 1.5,
-  airy: 1.65,
-}
-
-export function compilePrintTheme(
-  profile: PrintStyleProfile,
-  base: PureRenderTheme = DEFAULT_PURE_RENDER_THEME,
-): CompilePrintThemeResult {
-  const decisions: [string, string][] = []
-  const ok = (field?: { confidence?: number }): boolean =>
-    Boolean(field && (field.confidence ?? 0) >= CONF_FLOOR)
-
-  if (!profile.exemplar_quality.usable) {
-    return {
-      theme: null,
-      decisions: [
-        [
-          'reject',
-          `exemplar flagged unusable: ${profile.exemplar_quality.reason}`,
-        ],
-      ],
-      rules: [],
-    }
-  }
-
-  const obs = profile.observations
-  const find = <T extends { role: string }>(
-    items: readonly T[] | undefined,
-    role: string,
-  ): T | undefined => items?.find(item => item.role === role)
-
-  const surface = find(obs.palette, 'surface')
-  const ink = find(obs.palette, 'ink')
-  const accent = find(obs.palette, 'accent')
-  const secondary = find(obs.palette, 'secondary')
-  const surfaceStrongEnough = Boolean(
-    ok(surface) &&
-      surface?.approx_hex &&
-      (!isManuscriptLikeProfile(profile) ||
-        (surface.confidence ?? 0) >= MANUSCRIPT_SURFACE_CONF_FLOOR),
-  )
-  const paper = surfaceStrongEnough
-    ? surface?.approx_hex ?? '#FFFFFF'
-    : base.color.surface ?? base.color.paper ?? '#FFFFFF'
-  decisions.push(
-    surfaceStrongEnough
-      ? [
-          'apply',
-          `surface ${surface?.approx_hex ?? paper} (conf ${
-            surface?.confidence ?? 0
-          })`,
-        ]
-      : isManuscriptLikeProfile(profile) && surface?.approx_hex
-      ? [
-          'fallback',
-          `manuscript surface ${surface.approx_hex} confidence ${
-            surface.confidence ?? 0
-          } < ${MANUSCRIPT_SURFACE_CONF_FLOOR} -> white paper`,
-        ]
-      : ['fallback', 'surface low confidence -> base'],
-  )
-
-  let safeInk = base.color.ink ?? '#191919'
-  if (ok(ink) && ink?.approx_hex) {
-    const repaired = repairInk(ink.approx_hex, paper)
-    safeInk = repaired.hex
-    decisions.push(
-      repaired.repaired
-        ? [
-            'repair',
-            `ink ${ink.approx_hex} fails AA (${contrast(
-              ink.approx_hex,
-              paper,
-            ).toFixed(1)}:1) -> ${repaired.hex} (${contrast(
-              repaired.hex,
-              paper,
-            ).toFixed(1)}:1), hue kept`,
-          ]
-        : [
-            'apply',
-            `ink ${repaired.hex} passes AA (${contrast(
-              repaired.hex,
-              paper,
-            ).toFixed(1)}:1)`,
-          ],
-    )
-  } else {
-    decisions.push(['fallback', 'ink low confidence -> base'])
-  }
-
-  let accentHex = base.color.accent ?? '#46584b'
-  let accentInk = base.color['accent-ink'] ?? accentHex
-  if (ok(accent) && accent?.approx_hex) {
-    accentHex = accent.approx_hex
-    accentInk =
-      contrast(accentHex, paper) >= AA
-        ? accentHex
-        : repairInk(accentHex, paper).hex
-    decisions.push([
-      'apply',
-      `accent ${accentHex} (marks only); text-safe variant ${accentInk}`,
-    ])
-  } else {
-    decisions.push(['fallback', 'accent low confidence -> base'])
-  }
-
-  const display = find(obs.type, 'display')
-  const body = find(obs.type, 'body')
-  const caption = find(obs.type, 'caption')
-  const fonts = { ...base.type.fonts }
-  if (ok(display)) {
-    fonts.display =
-      LIBRARY.display[typeKey(display)] ??
-      LIBRARY.display[display?.class ?? ''] ??
-      fonts.display ??
-      fonts.sans
-    const displayFont = fonts.display
-    decisions.push([
-      'apply',
-      `display ${display?.class}/${display?.serif_detail ?? '-'} -> ${
-        displayFont.split(',')[0]
-      }`,
-    ])
-  }
-  if (ok(body)) {
-    fonts.serif =
-      LIBRARY.body[typeKey(body)] ??
-      LIBRARY.body[body?.class ?? ''] ??
-      fonts.serif
-    decisions.push([
-      'apply',
-      `body ${typeKey(body)} -> ${fonts.serif.split(',')[0]}`,
-    ])
-  } else {
-    decisions.push(['fallback', 'body type low confidence -> base serif'])
-  }
-  if (ok(caption) && caption?.class === 'sans') {
-    fonts.sans = LIBRARY.caption.sans
-    decisions.push(['note', 'caption is sans -> uses --sans'])
-  }
-
-  const textSetting = obs.text_setting
-  let bodyPt = BODY_PT
-  let measure = base.type.measure
-  let lead = Number(base.type.lead) || 1.5
-  let align = base.setting?.align ?? 'justified'
-  let hyphenate = base.setting?.hyphenate ?? true
-  if (ok(textSetting)) {
-    if (textSetting?.measure_cpl) {
-      measure = `${(textSetting.measure_cpl * 0.5).toFixed(1)}rem`
-      decisions.push([
-        'apply',
-        `measure ~${textSetting.measure_cpl} cpl -> ${measure}`,
-      ])
-    }
-    lead = LEAD[textSetting?.leading_feel ?? ''] ?? lead
-    align = textSetting?.alignment ?? align
-    hyphenate = textSetting?.hyphenation !== 'absent'
-    decisions.push([
-      'apply',
-      `leading_feel "${textSetting?.leading_feel}" -> --lead ${lead}`,
-    ])
-  } else {
-    decisions.push([
-      'fallback',
-      'text_setting low confidence -> base measure/lead',
-    ])
-  }
-
-  if (ok(obs.type_scale)) {
-    if (
-      typeof obs.type_scale?.body_pt === 'number' &&
-      obs.type_scale.body_pt >= 8 &&
-      obs.type_scale.body_pt <= 13
-    ) {
-      bodyPt = obs.type_scale.body_pt
-      decisions.push(['apply', `body scale ${bodyPt}pt from reference page`])
-    }
-    decisions.push([
-      'note',
-      `type scale captured: title ${
-        obs.type_scale?.title_scale ?? '-'
-      }, section ${obs.type_scale?.section_scale ?? '-'}`,
-    ])
-  } else if (obs.type_scale) {
-    decisions.push([
-      'fallback',
-      `type_scale confidence ${obs.type_scale.confidence} < ${CONF_FLOOR} -> base type scale`,
-    ])
-  }
-
-  const ratio = ok(obs.type_pairing)
-    ? RATIO[obs.type_pairing?.size_contrast ?? ''] ?? base.type.scaleRatio
-    : base.type.scaleRatio
-  decisions.push([
-    'apply',
-    `size_contrast "${obs.type_pairing?.size_contrast}" -> ratio ${ratio}`,
-  ])
-
-  const page = { ...base.page }
-  const pageModel = obs.page_model
-  if (ok(pageModel)) {
-    if (pageModel?.columns) page.columns = pageModel.columns
-    page.recto_verso = /inner<outer/.test(pageModel?.margin_asymmetry ?? '')
-    decisions.push([
-      'apply',
-      `page: ${pageModel?.columns ?? 1}-col, recto/verso ${page.recto_verso}`,
-    ])
-  } else {
-    decisions.push([
-      'fallback',
-      `page_model confidence ${pageModel?.confidence} < ${CONF_FLOOR} -> base page geometry`,
-    ])
-  }
-
-  const confidentProfileRules = (profile.rules ?? []).filter(
-    rule => rule.confidence >= CONF_FLOOR,
-  )
-  const rules = confidentProfileRules
-    .filter(rule => !isReconciliationConflictRule(rule.rule))
-    .map(rule => rule.rule)
-  confidentProfileRules
-    .filter(rule => isReconciliationConflictRule(rule.rule))
-    .forEach(rule => {
-      decisions.push(['warn', rule.rule])
-    })
-  const profileRules = profileRulesFromObservations(profile, decisions)
-  const pageRuleStrings = profileRuleStrings(profileRules)
-  rules.push(...pageRuleStrings)
-  rules.forEach(rule => decisions.push(['rule', rule]))
-  appendApproximationWarnings(profile, decisions)
-
-  return {
-    theme: {
-      $schema: 'https://pure.science/render-theme/v1',
-      name: `Extracted - ${obs.finish?.register ?? 'profile'}`,
-      version: '1.0.0',
-      color: {
-        ink: safeInk,
-        'ink-soft': mix(safeInk, paper, 0.25),
-        muted:
-          ok(secondary) && secondary?.approx_hex
-            ? secondary.approx_hex
-            : base.color.muted ?? mix(safeInk, paper, 0.4),
-        surface: paper,
-        paper,
-        rule: mix(safeInk, paper, 0.7),
-        'rule-soft': mix(safeInk, paper, 0.88),
-        accent: accentHex,
-        'accent-ink': accentInk,
-      },
-      type: {
-        body: `${bodyPt}pt`,
-        lead,
-        measure,
-        scaleRatio: ratio,
-        fonts,
-      },
-      rhythm: `${(bodyPt * lead).toFixed(1)}pt`,
-      page,
-      setting: { align, hyphenate },
-      enforced_rules: rules,
-      ...(Object.keys(profileRules).length > 0
-        ? { profile_rules: profileRules }
-        : {}),
-    },
-    decisions,
-    rules,
-  }
-}
-
-function appendApproximationWarnings(
-  profile: PrintStyleProfile,
-  decisions: [string, string][],
-): void {
-  const obs = profile.observations
-  if (obs.type?.some(field => (field.confidence ?? 0) >= CONF_FLOOR)) {
-    decisions.push([
-      'warn',
-      'font matching uses licensed substitutes; exact font identity is not guaranteed.',
-    ])
-  }
-  if (obs.type_scale) {
-    decisions.push([
-      'warn',
-      'point sizes are approximate; reference pages provide scale and contrast, not exact measurements.',
-    ])
-  }
-  if (obs.page_model) {
-    decisions.push([
-      'warn',
-      'page geometry is approximate; margins and trim are applied only when confidence clears the compiler threshold.',
-    ])
-  }
-  if (obs.opener?.ornament || obs.ornaments) {
-    decisions.push([
-      'warn',
-      'ornaments are mapped to supported rules/dividers; arbitrary custom ornament replication is unsupported.',
-    ])
-  }
-}
-
-function isReconciliationConflictRule(rule: string): boolean {
-  return rule.startsWith('Reference conflict:')
-}
-
-function profileRulesFromObservations(
-  profile: PrintStyleProfile,
-  decisions: [string, string][],
-): PureRenderProfileRules {
-  const obs = profile.observations
-  const rules: PureRenderProfileRules = {}
-  const ok = (field?: { confidence?: number }): boolean =>
-    Boolean(field && (field.confidence ?? 0) >= CONF_FLOOR)
-
-  if (ok(obs.running_heads)) {
-    rules.running_heads = {
-      presence:
-        obs.running_heads?.presence ??
-        obs.page_model?.running_heads ??
-        'present',
-      position: obs.running_heads?.position,
-      transform: obs.running_heads?.transform,
-      rule: obs.running_heads?.rule,
-      font_role: obs.running_heads?.font_role,
-    }
-    decisions.push([
-      'apply',
-      `running heads ${rules.running_heads.presence} ${
-        rules.running_heads.position ?? ''
-      }`.trim(),
-    ])
-  } else if (obs.running_heads) {
-    decisions.push([
-      'fallback',
-      `running_heads confidence ${obs.running_heads.confidence} < ${CONF_FLOOR} -> profile default`,
-    ])
-  }
-
-  if (ok(obs.folio)) {
-    rules.folio = {
-      position: obs.folio?.position,
-      style: obs.folio?.style,
-      suppress_on: obs.folio?.suppress_on,
-    }
-    decisions.push([
-      'apply',
-      `folio ${rules.folio.position ?? 'profile default'}`,
-    ])
-  } else if (obs.folio) {
-    decisions.push([
-      'fallback',
-      `folio confidence ${obs.folio.confidence} < ${CONF_FLOOR} -> profile default`,
-    ])
-  }
-
-  if (ok(obs.opener)) {
-    rules.opener = {
-      spacing: obs.opener?.spacing,
-      recto_start: obs.opener?.recto_start,
-      ornament: obs.opener?.ornament,
-      drop_cap: obs.opener?.drop_cap,
-    }
-    decisions.push([
-      'apply',
-      `opener ${rules.opener.spacing ?? 'profile'} ${
-        rules.opener.ornament ?? 'no ornament'
-      }`,
-    ])
-  } else if (obs.opener) {
-    decisions.push([
-      'fallback',
-      `opener confidence ${obs.opener.confidence} < ${CONF_FLOOR} -> profile default`,
-    ])
-  }
-
-  if (ok(obs.ornaments)) {
-    rules.ornaments = {
-      kind: obs.ornaments?.kind,
-      weight: obs.ornaments?.weight,
-      placement: obs.ornaments?.placement,
-    }
-    decisions.push([
-      'apply',
-      `ornament ${rules.ornaments.kind ?? 'none'} ${
-        rules.ornaments.weight ?? ''
-      }`.trim(),
-    ])
-  } else if (obs.ornaments) {
-    decisions.push([
-      'fallback',
-      `ornaments confidence ${obs.ornaments.confidence} < ${CONF_FLOOR} -> none/default`,
-    ])
-  }
-
-  if (ok(obs.table_treatment)) {
-    rules.table = {
-      rule_weight: obs.table_treatment?.rule_weight,
-      header_treatment: obs.table_treatment?.header_treatment,
-      density: obs.table_treatment?.density,
-    }
-    decisions.push([
-      'apply',
-      `table rules ${rules.table.rule_weight ?? 'profile default'}, density ${
-        rules.table.density ?? 'default'
-      }`,
-    ])
-  } else if (obs.table_treatment) {
-    decisions.push([
-      'fallback',
-      `table_treatment confidence ${obs.table_treatment.confidence} < ${CONF_FLOOR} -> profile default`,
-    ])
-  }
-
-  if (ok(obs.caption_treatment)) {
-    rules.caption = {
-      position:
-        obs.caption_treatment?.position ?? obs.page_model?.caption_position,
-      label_style: obs.caption_treatment?.label_style,
-      alignment: obs.caption_treatment?.alignment,
-    }
-    decisions.push([
-      'apply',
-      `caption ${rules.caption.position ?? 'profile'} labels ${
-        rules.caption.label_style ?? 'profile'
-      }`,
-    ])
-  } else if (obs.caption_treatment) {
-    decisions.push([
-      'fallback',
-      `caption_treatment confidence ${obs.caption_treatment.confidence} < ${CONF_FLOOR} -> profile default`,
-    ])
-  }
-
-  return removeUndefinedRules(rules)
-}
-
-function removeUndefinedRules(
-  rules: PureRenderProfileRules,
-): PureRenderProfileRules {
-  return Object.fromEntries(
-    Object.entries(rules).map(([key, value]) => [
-      key,
-      Object.fromEntries(
-        Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined),
-      ),
-    ]),
-  ) as PureRenderProfileRules
-}
-
-function isManuscriptLikeProfile(profile: PrintStyleProfile): boolean {
-  const register = profile.observations.finish?.register?.toLowerCase()
-  return register === 'scholarly' || register === 'technical'
-}
-
-function profileRuleStrings(rules: PureRenderProfileRules): string[] {
-  const out: string[] = []
-  if (rules.running_heads) {
-    out.push(
-      `Reference page furniture: running heads ${
-        rules.running_heads.presence ?? 'present'
-      }${
-        rules.running_heads.position
-          ? ` at ${rules.running_heads.position}`
-          : ''
-      }.`,
-    )
-  }
-  if (rules.folio) {
-    out.push(
-      `Reference page furniture: folios ${
-        rules.folio.position ?? 'use profile position'
-      }.`,
-    )
-  }
-  if (rules.opener) {
-    out.push(
-      `Reference opener: ${rules.opener.spacing ?? 'profile'} spacing, ${
-        rules.opener.ornament ?? 'no'
-      } ornament.`,
-    )
-  }
-  if (rules.ornaments) {
-    out.push(
-      `Reference ornaments: ${rules.ornaments.kind ?? 'none'} ${
-        rules.ornaments.weight ?? ''
-      }`.trim(),
-    )
-  }
-  if (rules.table) {
-    out.push(
-      `Reference tables: ${rules.table.rule_weight ?? 'profile'} rules, ${
-        rules.table.density ?? 'profile'
-      } density.`,
-    )
-  }
-  if (rules.caption) {
-    out.push(
-      `Reference captions: ${rules.caption.position ?? 'profile'} position, ${
-        rules.caption.label_style ?? 'profile'
-      } labels.`,
-    )
-  }
-  return out
-}
-
-function typeKey(field?: { class: string; serif_detail?: string }): string {
-  if (!field) return ''
-  return field.class === 'serif'
-    ? `serif:${field.serif_detail || 'bracketed'}`
-    : field.class
-}
-
-function hex2rgb(hex: string): [number, number, number] {
-  const value = hex.replace('#', '')
-  return [0, 2, 4].map(index =>
-    Number.parseInt(value.slice(index, index + 2), 16),
-  ) as [number, number, number]
-}
-
-function rgb2hex(rgb: readonly number[]): string {
-  return `#${rgb
-    .map(value =>
-      Math.max(0, Math.min(255, Math.round(value)))
-        .toString(16)
-        .padStart(2, '0'),
-    )
-    .join('')}`
-}
-
-function lum(hex: string): number {
-  const channel = hex2rgb(hex).map(value => {
-    const v = value / 255
-    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)
-  })
-  return 0.2126 * channel[0] + 0.7152 * channel[1] + 0.0722 * channel[2]
-}
-
-function contrast(a: string, b: string): number {
-  const l1 = lum(a)
-  const l2 = lum(b)
-  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)
-}
-
-function rgb2hsl([rRaw, gRaw, bRaw]: readonly number[]): [
-  number,
-  number,
-  number,
-] {
-  const r = rRaw / 255
-  const g = gRaw / 255
-  const b = bRaw / 255
-  const max = Math.max(r, g, b)
-  const min = Math.min(r, g, b)
-  let h = 0
-  let s = 0
-  const l = (max + min) / 2
-  if (max !== min) {
-    const d = max - min
-    s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
-    h =
-      max === r
-        ? (g - b) / d + (g < b ? 6 : 0)
-        : max === g
-        ? (b - r) / d + 2
-        : (r - g) / d + 4
-    h /= 6
-  }
-  return [h, s, l]
-}
-
-function hsl2rgb([h, s, l]: readonly number[]): [number, number, number] {
-  if (s === 0) return [l * 255, l * 255, l * 255]
-  const q = l < 0.5 ? l * (1 + s) : l + s - l * s
-  const p = 2 * l - q
-  const t = (nRaw: number): number => {
-    let n = nRaw
-    if (n < 0) n += 1
-    if (n > 1) n -= 1
-    if (n < 1 / 6) return p + (q - p) * 6 * n
-    if (n < 1 / 2) return q
-    if (n < 2 / 3) return p + (q - p) * (2 / 3 - n) * 6
-    return p
-  }
-  return [t(h + 1 / 3) * 255, t(h) * 255, t(h - 1 / 3) * 255]
-}
-
-function repairInk(
-  ink: string,
-  surface: string,
-): { hex: string; repaired: boolean } {
-  if (contrast(ink, surface) >= AA) return { hex: ink, repaired: false }
-  const [h, s] = rgb2hsl(hex2rgb(ink))
-  const lightSurface = lum(surface) > 0.4
-  let l = rgb2hsl(hex2rgb(ink))[2]
-  for (let i = 0; i < 100; i += 1) {
-    l = lightSurface ? l - 0.01 : l + 0.01
-    const candidate = rgb2hex(
-      hsl2rgb([h, Math.min(s, 0.6), Math.max(0, Math.min(1, l))]),
-    )
-    if (contrast(candidate, surface) >= AA) {
-      return { hex: candidate, repaired: true }
-    }
-  }
-  return { hex: lightSurface ? '#1A1A1A' : '#FFFFFF', repaired: true }
-}
-
-function mix(a: string, b: string, t: number): string {
-  const left = hex2rgb(a)
-  const right = hex2rgb(b)
-  return rgb2hex(left.map((value, index) => value + (right[index] - value) * t))
-}
+import { DEFAULT_PURE_RENDER_THEME } from './theme.js'
+import type {
+  CompilePrintThemeResult,
+  PureRenderProfileRules,
+  PrintStyleProfile,
+  PureRenderTheme,
+} from './types.js'
+
+const CONF_FLOOR = 0.6
+const MANUSCRIPT_SURFACE_CONF_FLOOR = 0.95
+const AA = 4.5
+const BODY_PT = 10.6
+
+const LIBRARY: {
+  display: Record<string, string>
+  body: Record<string, string>
+  caption: Record<string, string>
+  mono: string
+} = {
+  display: {
+    'serif:bracketed': '"Source Serif 4", Georgia, serif',
+    'serif:hairline': '"Newsreader", Georgia, serif',
+    'serif:slab': '"Roboto Slab", Georgia, serif',
+    'serif:wedge': '"Spectral", Georgia, serif',
+    sans: '"Archivo", system-ui, sans-serif',
+    slab: '"Roboto Slab", serif',
+  },
+  body: {
+    'serif:bracketed': '"Source Serif 4", Georgia, serif',
+    'serif:hairline': '"Newsreader", Georgia, serif',
+    'serif:wedge': '"Spectral", Georgia, serif',
+    sans: '"Source Sans 3", system-ui, sans-serif',
+  },
+  caption: {
+    sans: '"Archivo", system-ui, sans-serif',
+    'serif:bracketed': '"Source Serif 4", serif',
+  },
+  mono: '"JetBrains Mono", ui-monospace, monospace',
+} as const
+
+const RATIO: Record<string, number> = {
+  dramatic: 1.414,
+  moderate: 1.333,
+  subtle: 1.2,
+}
+
+const LEAD: Record<string, number> = {
+  tight: 1.35,
+  normal: 1.5,
+  airy: 1.65,
+}
+
+export function compilePrintTheme(
+  profile: PrintStyleProfile,
+  base: PureRenderTheme = DEFAULT_PURE_RENDER_THEME,
+): CompilePrintThemeResult {
+  const decisions: [string, string][] = []
+  const ok = (field?: { confidence?: number }): boolean =>
+    Boolean(field && (field.confidence ?? 0) >= CONF_FLOOR)
+
+  if (!profile.exemplar_quality.usable) {
+    return {
+      theme: null,
+      decisions: [
+        [
+          'reject',
+          `exemplar flagged unusable: ${profile.exemplar_quality.reason}`,
+        ],
+      ],
+      rules: [],
+    }
+  }
+
+  const obs = profile.observations
+  const find = <T extends { role: string }>(
+    items: readonly T[] | undefined,
+    role: string,
+  ): T | undefined => items?.find(item => item.role === role)
+
+  const surface = find(obs.palette, 'surface')
+  const ink = find(obs.palette, 'ink')
+  const accent = find(obs.palette, 'accent')
+  const secondary = find(obs.palette, 'secondary')
+  const surfaceStrongEnough = Boolean(
+    ok(surface) &&
+      surface?.approx_hex &&
+      (!isManuscriptLikeProfile(profile) ||
+        (surface.confidence ?? 0) >= MANUSCRIPT_SURFACE_CONF_FLOOR),
+  )
+  const paper = surfaceStrongEnough
+    ? surface?.approx_hex ?? '#FFFFFF'
+    : base.color.surface ?? base.color.paper ?? '#FFFFFF'
+  decisions.push(
+    surfaceStrongEnough
+      ? [
+          'apply',
+          `surface ${surface?.approx_hex ?? paper} (conf ${
+            surface?.confidence ?? 0
+          })`,
+        ]
+      : isManuscriptLikeProfile(profile) && surface?.approx_hex
+      ? [
+          'fallback',
+          `manuscript surface ${surface.approx_hex} confidence ${
+            surface.confidence ?? 0
+          } < ${MANUSCRIPT_SURFACE_CONF_FLOOR} -> white paper`,
+        ]
+      : ['fallback', 'surface low confidence -> base'],
+  )
+
+  let safeInk = base.color.ink ?? '#191919'
+  if (ok(ink) && ink?.approx_hex) {
+    const repaired = repairInk(ink.approx_hex, paper)
+    safeInk = repaired.hex
+    decisions.push(
+      repaired.repaired
+        ? [
+            'repair',
+            `ink ${ink.approx_hex} fails AA (${contrast(
+              ink.approx_hex,
+              paper,
+            ).toFixed(1)}:1) -> ${repaired.hex} (${contrast(
+              repaired.hex,
+              paper,
+            ).toFixed(1)}:1), hue kept`,
+          ]
+        : [
+            'apply',
+            `ink ${repaired.hex} passes AA (${contrast(
+              repaired.hex,
+              paper,
+            ).toFixed(1)}:1)`,
+          ],
+    )
+  } else {
+    decisions.push(['fallback', 'ink low confidence -> base'])
+  }
+
+  let accentHex = base.color.accent ?? '#46584b'
+  let accentInk = base.color['accent-ink'] ?? accentHex
+  if (ok(accent) && accent?.approx_hex) {
+    accentHex = accent.approx_hex
+    accentInk =
+      contrast(accentHex, paper) >= AA
+        ? accentHex
+        : repairInk(accentHex, paper).hex
+    decisions.push([
+      'apply',
+      `accent ${accentHex} (marks only); text-safe variant ${accentInk}`,
+    ])
+  } else {
+    decisions.push(['fallback', 'accent low confidence -> base'])
+  }
+
+  const display = find(obs.type, 'display')
+  const body = find(obs.type, 'body')
+  const caption = find(obs.type, 'caption')
+  const fonts = { ...base.type.fonts }
+  if (ok(display)) {
+    fonts.display =
+      LIBRARY.display[typeKey(display)] ??
+      LIBRARY.display[display?.class ?? ''] ??
+      fonts.display ??
+      fonts.sans
+    const displayFont = fonts.display
+    decisions.push([
+      'apply',
+      `display ${display?.class}/${display?.serif_detail ?? '-'} -> ${
+        displayFont.split(',')[0]
+      }`,
+    ])
+  }
+  if (ok(body)) {
+    fonts.serif =
+      LIBRARY.body[typeKey(body)] ??
+      LIBRARY.body[body?.class ?? ''] ??
+      fonts.serif
+    decisions.push([
+      'apply',
+      `body ${typeKey(body)} -> ${fonts.serif.split(',')[0]}`,
+    ])
+  } else {
+    decisions.push(['fallback', 'body type low confidence -> base serif'])
+  }
+  if (ok(caption) && caption?.class === 'sans') {
+    fonts.sans = LIBRARY.caption.sans
+    decisions.push(['note', 'caption is sans -> uses --sans'])
+  }
+
+  const textSetting = obs.text_setting
+  let bodyPt = BODY_PT
+  let measure = base.type.measure
+  let lead = Number(base.type.lead) || 1.5
+  let align = base.setting?.align ?? 'justified'
+  let hyphenate = base.setting?.hyphenate ?? true
+  if (ok(textSetting)) {
+    if (textSetting?.measure_cpl) {
+      measure = `${(textSetting.measure_cpl * 0.5).toFixed(1)}rem`
+      decisions.push([
+        'apply',
+        `measure ~${textSetting.measure_cpl} cpl -> ${measure}`,
+      ])
+    }
+    lead = LEAD[textSetting?.leading_feel ?? ''] ?? lead
+    align = textSetting?.alignment ?? align
+    hyphenate = textSetting?.hyphenation !== 'absent'
+    decisions.push([
+      'apply',
+      `leading_feel "${textSetting?.leading_feel}" -> --lead ${lead}`,
+    ])
+  } else {
+    decisions.push([
+      'fallback',
+      'text_setting low confidence -> base measure/lead',
+    ])
+  }
+
+  if (ok(obs.type_scale)) {
+    if (
+      typeof obs.type_scale?.body_pt === 'number' &&
+      obs.type_scale.body_pt >= 8 &&
+      obs.type_scale.body_pt <= 13
+    ) {
+      bodyPt = obs.type_scale.body_pt
+      decisions.push(['apply', `body scale ${bodyPt}pt from reference page`])
+    }
+    decisions.push([
+      'note',
+      `type scale captured: title ${
+        obs.type_scale?.title_scale ?? '-'
+      }, section ${obs.type_scale?.section_scale ?? '-'}`,
+    ])
+  } else if (obs.type_scale) {
+    decisions.push([
+      'fallback',
+      `type_scale confidence ${obs.type_scale.confidence} < ${CONF_FLOOR} -> base type scale`,
+    ])
+  }
+
+  const ratio = ok(obs.type_pairing)
+    ? RATIO[obs.type_pairing?.size_contrast ?? ''] ?? base.type.scaleRatio
+    : base.type.scaleRatio
+  decisions.push([
+    'apply',
+    `size_contrast "${obs.type_pairing?.size_contrast}" -> ratio ${ratio}`,
+  ])
+
+  const page = { ...base.page }
+  const pageModel = obs.page_model
+  if (ok(pageModel)) {
+    if (pageModel?.columns) page.columns = pageModel.columns
+    page.recto_verso = /inner<outer/.test(pageModel?.margin_asymmetry ?? '')
+    decisions.push([
+      'apply',
+      `page: ${pageModel?.columns ?? 1}-col, recto/verso ${page.recto_verso}`,
+    ])
+  } else {
+    decisions.push([
+      'fallback',
+      `page_model confidence ${pageModel?.confidence} < ${CONF_FLOOR} -> base page geometry`,
+    ])
+  }
+
+  const confidentProfileRules = (profile.rules ?? []).filter(
+    rule => rule.confidence >= CONF_FLOOR,
+  )
+  const rules = confidentProfileRules
+    .filter(rule => !isReconciliationConflictRule(rule.rule))
+    .map(rule => rule.rule)
+  confidentProfileRules
+    .filter(rule => isReconciliationConflictRule(rule.rule))
+    .forEach(rule => {
+      decisions.push(['warn', rule.rule])
+    })
+  const profileRules = profileRulesFromObservations(profile, decisions)
+  const pageRuleStrings = profileRuleStrings(profileRules)
+  rules.push(...pageRuleStrings)
+  rules.forEach(rule => decisions.push(['rule', rule]))
+  appendApproximationWarnings(profile, decisions)
+
+  return {
+    theme: {
+      $schema: 'https://pure.science/render-theme/v1',
+      name: `Extracted - ${obs.finish?.register ?? 'profile'}`,
+      version: '1.0.0',
+      color: {
+        ink: safeInk,
+        'ink-soft': mix(safeInk, paper, 0.25),
+        muted:
+          ok(secondary) && secondary?.approx_hex
+            ? secondary.approx_hex
+            : base.color.muted ?? mix(safeInk, paper, 0.4),
+        surface: paper,
+        paper,
+        rule: mix(safeInk, paper, 0.7),
+        'rule-soft': mix(safeInk, paper, 0.88),
+        accent: accentHex,
+        'accent-ink': accentInk,
+      },
+      type: {
+        body: `${bodyPt}pt`,
+        lead,
+        measure,
+        scaleRatio: ratio,
+        fonts,
+      },
+      rhythm: `${(bodyPt * lead).toFixed(1)}pt`,
+      page,
+      setting: { align, hyphenate },
+      enforced_rules: rules,
+      ...(Object.keys(profileRules).length > 0
+        ? { profile_rules: profileRules }
+        : {}),
+    },
+    decisions,
+    rules,
+  }
+}
+
+function appendApproximationWarnings(
+  profile: PrintStyleProfile,
+  decisions: [string, string][],
+): void {
+  const obs = profile.observations
+  if (obs.type?.some(field => (field.confidence ?? 0) >= CONF_FLOOR)) {
+    decisions.push([
+      'warn',
+      'font matching uses licensed substitutes; exact font identity is not guaranteed.',
+    ])
+  }
+  if (obs.type_scale) {
+    decisions.push([
+      'warn',
+      'point sizes are approximate; reference pages provide scale and contrast, not exact measurements.',
+    ])
+  }
+  if (obs.page_model) {
+    decisions.push([
+      'warn',
+      'page geometry is approximate; margins and trim are applied only when confidence clears the compiler threshold.',
+    ])
+  }
+  if (obs.opener?.ornament || obs.ornaments) {
+    decisions.push([
+      'warn',
+      'ornaments are mapped to supported rules/dividers; arbitrary custom ornament replication is unsupported.',
+    ])
+  }
+}
+
+function isReconciliationConflictRule(rule: string): boolean {
+  return rule.startsWith('Reference conflict:')
+}
+
+function profileRulesFromObservations(
+  profile: PrintStyleProfile,
+  decisions: [string, string][],
+): PureRenderProfileRules {
+  const obs = profile.observations
+  const rules: PureRenderProfileRules = {}
+  const ok = (field?: { confidence?: number }): boolean =>
+    Boolean(field && (field.confidence ?? 0) >= CONF_FLOOR)
+
+  if (ok(obs.running_heads)) {
+    rules.running_heads = {
+      presence:
+        obs.running_heads?.presence ??
+        obs.page_model?.running_heads ??
+        'present',
+      position: obs.running_heads?.position,
+      transform: obs.running_heads?.transform,
+      rule: obs.running_heads?.rule,
+      font_role: obs.running_heads?.font_role,
+    }
+    decisions.push([
+      'apply',
+      `running heads ${rules.running_heads.presence} ${
+        rules.running_heads.position ?? ''
+      }`.trim(),
+    ])
+  } else if (obs.running_heads) {
+    decisions.push([
+      'fallback',
+      `running_heads confidence ${obs.running_heads.confidence} < ${CONF_FLOOR} -> profile default`,
+    ])
+  }
+
+  if (ok(obs.folio)) {
+    rules.folio = {
+      position: obs.folio?.position,
+      style: obs.folio?.style,
+      suppress_on: obs.folio?.suppress_on,
+    }
+    decisions.push([
+      'apply',
+      `folio ${rules.folio.position ?? 'profile default'}`,
+    ])
+  } else if (obs.folio) {
+    decisions.push([
+      'fallback',
+      `folio confidence ${obs.folio.confidence} < ${CONF_FLOOR} -> profile default`,
+    ])
+  }
+
+  if (ok(obs.opener)) {
+    rules.opener = {
+      spacing: obs.opener?.spacing,
+      recto_start: obs.opener?.recto_start,
+      ornament: obs.opener?.ornament,
+      drop_cap: obs.opener?.drop_cap,
+    }
+    decisions.push([
+      'apply',
+      `opener ${rules.opener.spacing ?? 'profile'} ${
+        rules.opener.ornament ?? 'no ornament'
+      }`,
+    ])
+  } else if (obs.opener) {
+    decisions.push([
+      'fallback',
+      `opener confidence ${obs.opener.confidence} < ${CONF_FLOOR} -> profile default`,
+    ])
+  }
+
+  if (ok(obs.ornaments)) {
+    rules.ornaments = {
+      kind: obs.ornaments?.kind,
+      weight: obs.ornaments?.weight,
+      placement: obs.ornaments?.placement,
+    }
+    decisions.push([
+      'apply',
+      `ornament ${rules.ornaments.kind ?? 'none'} ${
+        rules.ornaments.weight ?? ''
+      }`.trim(),
+    ])
+  } else if (obs.ornaments) {
+    decisions.push([
+      'fallback',
+      `ornaments confidence ${obs.ornaments.confidence} < ${CONF_FLOOR} -> none/default`,
+    ])
+  }
+
+  if (ok(obs.table_treatment)) {
+    rules.table = {
+      rule_weight: obs.table_treatment?.rule_weight,
+      header_treatment: obs.table_treatment?.header_treatment,
+      density: obs.table_treatment?.density,
+    }
+    decisions.push([
+      'apply',
+      `table rules ${rules.table.rule_weight ?? 'profile default'}, density ${
+        rules.table.density ?? 'default'
+      }`,
+    ])
+  } else if (obs.table_treatment) {
+    decisions.push([
+      'fallback',
+      `table_treatment confidence ${obs.table_treatment.confidence} < ${CONF_FLOOR} -> profile default`,
+    ])
+  }
+
+  if (ok(obs.caption_treatment)) {
+    rules.caption = {
+      position:
+        obs.caption_treatment?.position ?? obs.page_model?.caption_position,
+      label_style: obs.caption_treatment?.label_style,
+      alignment: obs.caption_treatment?.alignment,
+    }
+    decisions.push([
+      'apply',
+      `caption ${rules.caption.position ?? 'profile'} labels ${
+        rules.caption.label_style ?? 'profile'
+      }`,
+    ])
+  } else if (obs.caption_treatment) {
+    decisions.push([
+      'fallback',
+      `caption_treatment confidence ${obs.caption_treatment.confidence} < ${CONF_FLOOR} -> profile default`,
+    ])
+  }
+
+  return removeUndefinedRules(rules)
+}
+
+function removeUndefinedRules(
+  rules: PureRenderProfileRules,
+): PureRenderProfileRules {
+  return Object.fromEntries(
+    Object.entries(rules).map(([key, value]) => [
+      key,
+      Object.fromEntries(
+        Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined),
+      ),
+    ]),
+  ) as PureRenderProfileRules
+}
+
+function isManuscriptLikeProfile(profile: PrintStyleProfile): boolean {
+  const register = profile.observations.finish?.register?.toLowerCase()
+  return register === 'scholarly' || register === 'technical'
+}
+
+function profileRuleStrings(rules: PureRenderProfileRules): string[] {
+  const out: string[] = []
+  if (rules.running_heads) {
+    out.push(
+      `Reference page furniture: running heads ${
+        rules.running_heads.presence ?? 'present'
+      }${
+        rules.running_heads.position
+          ? ` at ${rules.running_heads.position}`
+          : ''
+      }.`,
+    )
+  }
+  if (rules.folio) {
+    out.push(
+      `Reference page furniture: folios ${
+        rules.folio.position ?? 'use profile position'
+      }.`,
+    )
+  }
+  if (rules.opener) {
+    out.push(
+      `Reference opener: ${rules.opener.spacing ?? 'profile'} spacing, ${
+        rules.opener.ornament ?? 'no'
+      } ornament.`,
+    )
+  }
+  if (rules.ornaments) {
+    out.push(
+      `Reference ornaments: ${rules.ornaments.kind ?? 'none'} ${
+        rules.ornaments.weight ?? ''
+      }`.trim(),
+    )
+  }
+  if (rules.table) {
+    out.push(
+      `Reference tables: ${rules.table.rule_weight ?? 'profile'} rules, ${
+        rules.table.density ?? 'profile'
+      } density.`,
+    )
+  }
+  if (rules.caption) {
+    out.push(
+      `Reference captions: ${rules.caption.position ?? 'profile'} position, ${
+        rules.caption.label_style ?? 'profile'
+      } labels.`,
+    )
+  }
+  return out
+}
+
+function typeKey(field?: { class: string; serif_detail?: string }): string {
+  if (!field) return ''
+  return field.class === 'serif'
+    ? `serif:${field.serif_detail || 'bracketed'}`
+    : field.class
+}
+
+function hex2rgb(hex: string): [number, number, number] {
+  const value = hex.replace('#', '')
+  return [0, 2, 4].map(index =>
+    Number.parseInt(value.slice(index, index + 2), 16),
+  ) as [number, number, number]
+}
+
+function rgb2hex(rgb: readonly number[]): string {
+  return `#${rgb
+    .map(value =>
+      Math.max(0, Math.min(255, Math.round(value)))
+        .toString(16)
+        .padStart(2, '0'),
+    )
+    .join('')}`
+}
+
+function lum(hex: string): number {
+  const channel = hex2rgb(hex).map(value => {
+    const v = value / 255
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)
+  })
+  return 0.2126 * channel[0] + 0.7152 * channel[1] + 0.0722 * channel[2]
+}
+
+function contrast(a: string, b: string): number {
+  const l1 = lum(a)
+  const l2 = lum(b)
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)
+}
+
+function rgb2hsl([rRaw, gRaw, bRaw]: readonly number[]): [
+  number,
+  number,
+  number,
+] {
+  const r = rRaw / 255
+  const g = gRaw / 255
+  const b = bRaw / 255
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  let h = 0
+  let s = 0
+  const l = (max + min) / 2
+  if (max !== min) {
+    const d = max - min
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+    h =
+      max === r
+        ? (g - b) / d + (g < b ? 6 : 0)
+        : max === g
+        ? (b - r) / d + 2
+        : (r - g) / d + 4
+    h /= 6
+  }
+  return [h, s, l]
+}
+
+function hsl2rgb([h, s, l]: readonly number[]): [number, number, number] {
+  if (s === 0) return [l * 255, l * 255, l * 255]
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s
+  const p = 2 * l - q
+  const t = (nRaw: number): number => {
+    let n = nRaw
+    if (n < 0) n += 1
+    if (n > 1) n -= 1
+    if (n < 1 / 6) return p + (q - p) * 6 * n
+    if (n < 1 / 2) return q
+    if (n < 2 / 3) return p + (q - p) * (2 / 3 - n) * 6
+    return p
+  }
+  return [t(h + 1 / 3) * 255, t(h) * 255, t(h - 1 / 3) * 255]
+}
+
+function repairInk(
+  ink: string,
+  surface: string,
+): { hex: string; repaired: boolean } {
+  if (contrast(ink, surface) >= AA) return { hex: ink, repaired: false }
+  const [h, s] = rgb2hsl(hex2rgb(ink))
+  const lightSurface = lum(surface) > 0.4
+  let l = rgb2hsl(hex2rgb(ink))[2]
+  for (let i = 0; i < 100; i += 1) {
+    l = lightSurface ? l - 0.01 : l + 0.01
+    const candidate = rgb2hex(
+      hsl2rgb([h, Math.min(s, 0.6), Math.max(0, Math.min(1, l))]),
+    )
+    if (contrast(candidate, surface) >= AA) {
+      return { hex: candidate, repaired: true }
+    }
+  }
+  return { hex: lightSurface ? '#1A1A1A' : '#FFFFFF', repaired: true }
+}
+
+function mix(a: string, b: string, t: number): string {
+  const left = hex2rgb(a)
+  const right = hex2rgb(b)
+  return rgb2hex(left.map((value, index) => value + (right[index] - value) * t))
+}