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

package/src/bridge/pureRender/extraction.ts

@@ -1,1023 +1,1023 @@
-import type {
-  PrintStylePaletteObservation,
-  PrintStyleProfile,
-  PrintStyleRule,
-  PrintStyleTypeObservation,
-} from './types.js'
-
-export const PRINT_TOKEN_EXTRACTION_PROMPT = `PRINT-TOKEN EXTRACTION PROMPT - v1.0
-=========================================================================
-Sent to a vision model alongside one or more reference images (a journal
-page, a book spread, a typeset PDF, a cover). Produces a STYLE PROFILE that
-the compiler turns into a print theme.json for the Pure Render system.
-
-Pair this prompt with: print-style-profile.schema.json (the output shape).
-=========================================================================
-
-ROLE
-You are a print design-system extractor. Given one or more reference images of
-TYPESET PAGES, reverse-engineer a reusable visual system that could set NEW text
-in the same family. You are not describing the image; you are inferring the rules
-a typesetter followed.
-
-DIVISION OF LABOR (critical)
-- You judge classification, relationships, mood, and rules - what you are good at.
-- You do NOT report exact colors or measurements as truth. A separate pixel pass
-  refines every numeric value. Give approx values as HINTS only.
-- You NEVER name or identify a typeface. Report ATTRIBUTES that let a substitute be
-  chosen from a licensed library.
-- Print-specific: estimate things in RELATIVE terms (ratios, proportions of the
-  page, x-heights relative to cap height) rather than absolute points, because you
-  cannot measure the trim size from pixels.
-
-PER IMAGE, record OBSERVATIONS (what is literally present):
-
-1. palette - print is restrained. By ROLE, not swatch:
-   - surface (paper/background), ink (body text), accent (rules/links/numbers - note
-     how sparingly used), and any secondary (captions, folios).
-   - For each: role, approx_hex (HINT), where_seen, coverage (dominant|frequent|sparse).
-
-2. type - by ATTRIBUTE not identity, per ROLE you can see (display/headings, body,
-   caption/folio, mono/code):
-   - class (serif|sans|slab|script), weight, width, contrast/stress (thick-thin),
-     x_height (low|medium|high), case_usage, and the SERIF DETAIL if serif
-     (bracketed|slab|hairline|wedge) - this most determines the substitute.
-     - pairing: heading/body relationship, and size_contrast (dramatic|moderate|subtle)
-     - implies the scale ratio.
-   - type_scale: relative or estimated scale for title, chapter title, section
-     heading, body, caption, and footnote. Keep absolute point sizes low-confidence
-     unless the source provides a known trim/scale.
-
-3. text setting - the heart of print. Estimate RELATIVELY:
-   - alignment (justified|flush-left), hyphenation (present|absent),
-   - measure: approx characters per line (count a representative full line),
-   - leading_feel (tight|normal|airy) - ratio of line gap to text size,
-   - paragraphing (indented runs | space-between | both),
-   - density (airy|balanced|dense).
-
-4. page model - what you can infer about the page:
-   - columns (1|2|n),
-   - margin_generosity (tight|moderate|generous) and which margins are larger
-     (inner/outer/top/bottom asymmetry -> suggests recto/verso canon),
-     - running heads (present|absent, position), folio (position),
-     - figure/table treatment (captions above|below, rule style, numbering visible).
-
-5. page furniture and ornaments - manuscript/book references often depend on
-   details outside body text. Capture these as structured observations:
-   - running_heads: presence, position, transform, rule/no rule, font_role.
-   - folio: position, style, suppress_on first/opener pages if visible.
-   - opener: chapter/opening spacing, recto_start, ornament, drop_cap.
-   - ornaments: none|rule|divider|fleuron|chapter-mark, weight, placement.
-   - table_treatment: rule_weight, header_treatment, row_rules, density.
-   - caption_treatment: position, label_style, alignment.
-
-6. finish & mood - register (scholarly|literary|editorial|technical|...),
-   temperature, era. Subjective; only you can supply it.
-
-THEN INFER THE RULES (the most important output)
-List the constraints the setting obeys - what must stay true for a NEW page to
-belong to this family.
-
-REQUIREMENTS
-- Cite evidence for every field (where in the image you saw it).
-- Give confidence 0..1 per field. When unsure, LOWER confidence - do NOT guess to
-  fill a slot. A low-confidence field is dropped for a safe default; a confident
-  wrong guess corrupts the system.
-- Output OBSERVATIONS and RULES only. Do NOT output final tokens or a theme - the
-  compiler derives those. Leave "derived": null.
-- Flag bad exemplars: if a source is a poor reference, set exemplar_quality.usable=false
-  with a reason, so it is not faithfully reproduced.
-- Multiple images: observations PER source id. Do NOT merge or average; the compiler
-  reconciles.
-
-OUTPUT
-Strict JSON conforming to print-style-profile.schema.json. No prose, no markdown,
-no commentary outside the JSON.`
-
-export const PRINT_STYLE_PROFILE_SCHEMA = {
-  type: 'object',
-  required: [
-    'schema_version',
-    'sources',
-    'exemplar_quality',
-    'observations',
-    'rules',
-    'derived',
-  ],
-  properties: {
-    schema_version: { const: '1.0' },
-    sources: {
-      type: 'array',
-      items: {
-        type: 'object',
-        required: ['id'],
-        properties: { id: { type: 'string' }, note: { type: 'string' } },
-      },
-    },
-    exemplar_quality: {
-      type: 'object',
-      required: ['usable', 'reason', 'confidence'],
-      properties: {
-        usable: { type: 'boolean' },
-        reason: { type: 'string' },
-        confidence: { type: 'number', minimum: 0, maximum: 1 },
-      },
-    },
-    observations: {
-      type: 'object',
-      properties: {
-        palette: {
-          type: 'array',
-          items: {
-            type: 'object',
-            required: ['role', 'confidence'],
-            properties: {
-              role: { enum: ['surface', 'ink', 'accent', 'secondary'] },
-              approx_hex: {
-                type: 'string',
-                description: 'HINT only; refined by pixel pass',
-              },
-              coverage: { enum: ['dominant', 'frequent', 'sparse'] },
-              where_seen: { type: 'string' },
-              confidence: { type: 'number' },
-            },
-          },
-        },
-        type: {
-          type: 'array',
-          items: {
-            type: 'object',
-            required: ['role', 'class', 'confidence'],
-            properties: {
-              role: { enum: ['display', 'body', 'caption', 'mono'] },
-              class: { enum: ['serif', 'sans', 'slab', 'script'] },
-              mood: {
-                enum: [
-                  'old-style',
-                  'transitional',
-                  'slab',
-                  'humanist-sans',
-                  'grotesque-sans',
-                  'geometric-sans',
-                  'mono',
-                ],
-              },
-              serif_detail: {
-                enum: ['bracketed', 'slab', 'hairline', 'wedge', 'none'],
-              },
-              weight: { type: 'string' },
-              width: { type: 'string' },
-              stress: { enum: ['high-contrast', 'moderate', 'low-contrast'] },
-              x_height: { enum: ['low', 'medium', 'high'] },
-              case_usage: { type: 'string' },
-              where_seen: { type: 'string' },
-              confidence: { type: 'number' },
-            },
-          },
-        },
-        type_pairing: {
-          type: 'object',
-          properties: {
-            size_contrast: { enum: ['dramatic', 'moderate', 'subtle'] },
-            note: { type: 'string' },
-            confidence: { type: 'number' },
-          },
-        },
-        type_scale: {
-          type: 'object',
-          properties: {
-            body_pt: { type: 'number' },
-            title_scale: { type: 'number' },
-            chapter_title_scale: { type: 'number' },
-            section_scale: { type: 'number' },
-            caption_scale: { type: 'number' },
-            footnote_scale: { type: 'number' },
-            confidence: { type: 'number' },
-          },
-        },
-        text_setting: {
-          type: 'object',
-          properties: {
-            alignment: { enum: ['justified', 'flush-left'] },
-            hyphenation: { enum: ['present', 'absent'] },
-            measure_cpl: { type: 'number' },
-            leading_feel: { enum: ['tight', 'normal', 'airy'] },
-            paragraphing: { enum: ['indented', 'spaced', 'both'] },
-            density: { enum: ['airy', 'balanced', 'dense'] },
-            confidence: { type: 'number' },
-          },
-        },
-        page_model: {
-          type: 'object',
-          properties: {
-            columns: { type: 'integer' },
-            margin_generosity: { enum: ['tight', 'moderate', 'generous'] },
-            margin_asymmetry: { type: 'string' },
-            running_heads: { enum: ['present', 'absent'] },
-            folio_position: { type: 'string' },
-            caption_position: { enum: ['above', 'below'] },
-            confidence: { type: 'number' },
-          },
-        },
-        running_heads: {
-          type: 'object',
-          properties: {
-            presence: { enum: ['present', 'absent'] },
-            position: { type: 'string' },
-            transform: {
-              enum: ['uppercase', 'small-caps', 'title-case', 'none'],
-            },
-            rule: { enum: ['none', 'hairline', 'solid'] },
-            font_role: {
-              enum: ['display', 'body', 'caption', 'sans'],
-            },
-            evidence: { type: 'string' },
-            confidence: { type: 'number' },
-          },
-        },
-        folio: {
-          type: 'object',
-          properties: {
-            position: { type: 'string' },
-            style: { enum: ['plain', 'small-caps', 'bracketed'] },
-            suppress_on: {
-              type: 'array',
-              items: { type: 'string' },
-            },
-            evidence: { type: 'string' },
-            confidence: { type: 'number' },
-          },
-        },
-        opener: {
-          type: 'object',
-          properties: {
-            spacing: { enum: ['compact', 'balanced', 'generous'] },
-            recto_start: { type: 'boolean' },
-            ornament: {
-              enum: ['none', 'rule', 'divider', 'fleuron', 'chapter-mark'],
-            },
-            drop_cap: { type: 'boolean' },
-            evidence: { type: 'string' },
-            confidence: { type: 'number' },
-          },
-        },
-        ornaments: {
-          type: 'object',
-          properties: {
-            kind: {
-              enum: ['none', 'rule', 'divider', 'fleuron', 'chapter-mark'],
-            },
-            weight: { enum: ['hairline', 'light', 'medium'] },
-            placement: { type: 'string' },
-            evidence: { type: 'string' },
-            confidence: { type: 'number' },
-          },
-        },
-        table_treatment: {
-          type: 'object',
-          properties: {
-            rule_weight: { enum: ['hairline', 'light', 'medium'] },
-            header_treatment: { type: 'string' },
-            row_rules: { enum: ['none', 'hairline', 'light'] },
-            density: { enum: ['airy', 'balanced', 'dense'] },
-            evidence: { type: 'string' },
-            confidence: { type: 'number' },
-          },
-        },
-        caption_treatment: {
-          type: 'object',
-          properties: {
-            position: { enum: ['above', 'below'] },
-            label_style: { enum: ['bold', 'small-caps', 'plain'] },
-            alignment: { enum: ['left', 'center', 'justified'] },
-            evidence: { type: 'string' },
-            confidence: { type: 'number' },
-          },
-        },
-        finish: {
-          type: 'object',
-          properties: {
-            register: { type: 'string' },
-            temperature: { type: 'string' },
-            era: { type: 'string' },
-            confidence: { type: 'number' },
-          },
-        },
-      },
-    },
-    rules: {
-      type: 'array',
-      items: {
-        type: 'object',
-        required: ['rule', 'confidence'],
-        properties: {
-          rule: { type: 'string' },
-          evidence: { type: 'string' },
-          confidence: { type: 'number' },
-        },
-      },
-    },
-    derived: {
-      type: ['object', 'null'],
-      description: 'compiler-only; model leaves null',
-    },
-  },
-} as const
-
-export interface PrintStyleProfilePromptInput {
-  mode: 'image' | 'description'
-  concerns?: string
-  imageName?: string
-  imageMimeType?: string
-  imagePixelSummary?: string
-}
-
-export function buildPrintStyleProfilePrompt(
-  input: PrintStyleProfilePromptInput,
-): string {
-  const reference =
-    input.mode === 'image'
-      ? [
-          `Reference image: ${input.imageName ?? 'uploaded image'}`,
-          input.imageMimeType ? `MIME type: ${input.imageMimeType}` : '',
-          input.imagePixelSummary
-            ? `Pixel pass summary: ${input.imagePixelSummary}`
-            : 'Use the attached image as the visual source.',
-        ]
-          .filter(Boolean)
-          .join('\n')
-      : [
-          'Text-only design brief. This is valid style evidence.',
-          'Do not reject the exemplar merely because no image is attached.',
-          'Infer the print style profile from the user concerns and keep visual-only fields low-confidence.',
-        ].join('\n')
-
-  return [
-    PRINT_TOKEN_EXTRACTION_PROMPT,
-    '',
-    'JSON SCHEMA',
-    JSON.stringify(PRINT_STYLE_PROFILE_SCHEMA, null, 2),
-    '',
-    'USER DESIGN INPUT',
-    reference,
-    `Concerns/preferences: ${input.concerns?.trim() || 'none supplied'}`,
-    '',
-    'Return only one JSON object matching the schema.',
-  ].join('\n')
-}
-
-export function parsePrintStyleProfileResponse(
-  text: string,
-): PrintStyleProfile {
-  const parsed = JSON.parse(extractJsonObject(text)) as unknown
-  if (!isPrintStyleProfile(parsed)) {
-    throw new Error(
-      'Model response did not match the print style profile schema',
-    )
-  }
-  return parsed
-}
-
-export function reconcilePrintStyleProfiles(
-  profiles: readonly PrintStyleProfile[],
-): PrintStyleProfile {
-  const usable = profiles.filter(profile => profile.exemplar_quality.usable)
-  const inputs = usable.length > 0 ? usable : profiles
-  if (inputs.length === 0) {
-    throw new Error('No print style profiles to reconcile')
-  }
-  if (inputs.length === 1) return inputs[0]!
-
-  return {
-    schema_version: '1.0',
-    sources: inputs.flatMap(profile => profile.sources ?? []),
-    exemplar_quality: {
-      usable: usable.length > 0,
-      reason:
-        usable.length === profiles.length
-          ? 'reconciled multiple usable print references'
-          : 'reconciled usable print references; discarded unusable exemplars',
-      confidence: average(
-        inputs.map(profile => profile.exemplar_quality.confidence),
-      ),
-    },
-    observations: {
-      palette: bestByRole(
-        inputs.flatMap(profile => profile.observations.palette ?? []),
-      ),
-      type: bestByRole(
-        inputs.flatMap(profile => profile.observations.type ?? []),
-      ),
-      type_pairing: bestByConfidence(
-        inputs.map(profile => profile.observations.type_pairing),
-      ),
-      type_scale: bestByConfidence(
-        inputs.map(profile => profile.observations.type_scale),
-      ),
-      text_setting: bestByConfidence(
-        inputs.map(profile => profile.observations.text_setting),
-      ),
-      page_model: bestByConfidence(
-        inputs.map(profile => profile.observations.page_model),
-      ),
-      running_heads: bestByConfidence(
-        inputs.map(profile => profile.observations.running_heads),
-      ),
-      folio: bestByConfidence(
-        inputs.map(profile => profile.observations.folio),
-      ),
-      opener: bestByConfidence(
-        inputs.map(profile => profile.observations.opener),
-      ),
-      ornaments: bestByConfidence(
-        inputs.map(profile => profile.observations.ornaments),
-      ),
-      table_treatment: bestByConfidence(
-        inputs.map(profile => profile.observations.table_treatment),
-      ),
-      caption_treatment: bestByConfidence(
-        inputs.map(profile => profile.observations.caption_treatment),
-      ),
-      finish: bestByConfidence(
-        inputs.map(profile => profile.observations.finish),
-      ),
-    },
-    rules: [
-      ...reconcileRules(inputs.flatMap(profile => profile.rules ?? [])),
-      ...detectReconciliationConflicts(inputs),
-    ],
-    derived: null,
-  }
-}
-
-export function isPrintStyleProfile(
-  value: unknown,
-): value is PrintStyleProfile {
-  if (!value || typeof value !== 'object') return false
-  const candidate = value as Partial<PrintStyleProfile>
-  return (
-    typeof candidate.schema_version === 'string' &&
-    Boolean(candidate.observations) &&
-    typeof candidate.observations === 'object' &&
-    Boolean(candidate.exemplar_quality) &&
-    typeof candidate.exemplar_quality === 'object' &&
-    typeof candidate.exemplar_quality.usable === 'boolean' &&
-    typeof candidate.exemplar_quality.reason === 'string' &&
-    typeof candidate.exemplar_quality.confidence === 'number' &&
-    Array.isArray(candidate.rules) &&
-    candidate.derived === null
-  )
-}
-
-export interface PrintReferenceImageSample {
-  paper: string
-  ink: string
-  accent: string
-  accentConfidence: number
-}
-
-export async function samplePrintReferenceImageColors(
-  image: File,
-): Promise<PrintReferenceImageSample> {
-  const bitmap = await createImageBitmap(image)
-  try {
-    const canvas = document.createElement('canvas')
-    canvas.width = 80
-    canvas.height = 80
-    const context = canvas.getContext('2d')
-    if (!context) return defaultPrintReferenceImageSample()
-
-    context.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
-    const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data
-    const buckets = new Map<
-      string,
-      { rgb: [number, number, number]; count: number }
-    >()
-    for (let index = 0; index < pixels.length; index += 16) {
-      const alpha = pixels[index + 3]
-      if (alpha < 128) continue
-      const rgb: [number, number, number] = [
-        quantizeColor(pixels[index]),
-        quantizeColor(pixels[index + 1]),
-        quantizeColor(pixels[index + 2]),
-      ]
-      const key = rgb.join(',')
-      const bucket = buckets.get(key)
-      if (bucket) bucket.count += 1
-      else buckets.set(key, { rgb, count: 1 })
-    }
-
-    const ranked = Array.from(buckets.values()).sort(
-      (a, b) => b.count - a.count,
-    )
-    const light = ranked.find(bucket => colorLuminance(bucket.rgb) > 0.72)
-    const dark =
-      ranked
-        .filter(bucket => colorLuminance(bucket.rgb) < 0.36)
-        .sort((a, b) => b.count - a.count)[0] ?? ranked[ranked.length - 1]
-    const saturated = ranked
-      .filter(bucket => colorSaturation(bucket.rgb) > 0.22)
-      .sort(
-        (a, b) =>
-          colorSaturation(b.rgb) * b.count - colorSaturation(a.rgb) * a.count,
-      )[0]
-
-    return {
-      paper: rgbToHex(light?.rgb ?? [255, 255, 255]),
-      ink: rgbToHex(dark?.rgb ?? [26, 26, 26]),
-      accent: rgbToHex(saturated?.rgb ?? [70, 88, 75]),
-      accentConfidence: saturated ? 0.72 : 0.45,
-    }
-  } finally {
-    bitmap.close()
-  }
-}
-
-export function buildBookPrintStyleProfileFromReference({
-  source,
-  prompt,
-  sample,
-}: {
-  source: string
-  prompt: string
-  sample?: PrintReferenceImageSample
-}): PrintStyleProfile {
-  const text = prompt.toLowerCase()
-  const sans = text.includes('sans')
-  const dramatic = text.includes('dramatic') || text.includes('literary')
-  const airy = text.includes('airy') || text.includes('generous')
-  return {
-    schema_version: '1.0',
-    sources: [{ id: source, note: 'book print design reference' }],
-    exemplar_quality: {
-      usable: true,
-      reason: sample
-        ? 'local pixel extraction from uploaded book reference image'
-        : 'book design concern inferred from description',
-      confidence: sample ? 0.78 : 0.68,
-    },
-    observations: {
-      palette: [
-        {
-          role: 'surface',
-          approx_hex:
-            sample?.paper ?? (text.includes('cream') ? '#FBFAF4' : '#FFFFFF'),
-          coverage: 'dominant',
-          where_seen: sample ? 'largest light color cluster' : 'description',
-          confidence: sample ? 0.82 : 0.64,
-        },
-        {
-          role: 'ink',
-          approx_hex: sample?.ink ?? '#1A1A1A',
-          coverage: 'frequent',
-          where_seen: sample ? 'dark text-like pixels' : 'description',
-          confidence: sample ? 0.76 : 0.64,
-        },
-        {
-          role: 'accent',
-          approx_hex:
-            sample?.accent ?? (text.includes('red') ? '#7A2634' : '#46584B'),
-          coverage: 'sparse',
-          where_seen: sample
-            ? 'most saturated non-neutral cluster'
-            : 'description',
-          confidence: sample?.accentConfidence ?? 0.62,
-        },
-      ],
-      type: [
-        {
-          role: 'display',
-          class: sans ? 'sans' : 'serif',
-          serif_detail: dramatic ? 'hairline' : 'bracketed',
-          confidence: 0.72,
-        },
-        {
-          role: 'body',
-          class: sans ? 'sans' : 'serif',
-          serif_detail: 'bracketed',
-          confidence: 0.72,
-        },
-        {
-          role: 'caption',
-          class: 'sans',
-          confidence: 0.7,
-        },
-      ],
-      type_pairing: {
-        size_contrast: dramatic ? 'dramatic' : 'moderate',
-        confidence: 0.72,
-      },
-      type_scale: {
-        body_pt: dramatic ? 10.8 : 10.6,
-        title_scale: dramatic ? 2.6 : 2.2,
-        chapter_title_scale: dramatic ? 2.2 : 1.9,
-        section_scale: dramatic ? 1.5 : 1.35,
-        caption_scale: 0.82,
-        footnote_scale: 0.78,
-        confidence: sample ? 0.68 : 0.62,
-      },
-      text_setting: {
-        alignment: text.includes('flush') ? 'flush-left' : 'justified',
-        hyphenation: text.includes('no hyphen') ? 'absent' : 'present',
-        measure_cpl: text.includes('narrow') ? 54 : 58,
-        leading_feel: airy ? 'airy' : 'normal',
-        confidence: 0.7,
-      },
-      page_model: {
-        columns: 1,
-        margin_generosity: airy ? 'generous' : 'moderate',
-        margin_asymmetry: 'inner<outer',
-        running_heads: 'present',
-        folio_position: 'outside bottom',
-        caption_position: 'below',
-        confidence: 0.7,
-      },
-      running_heads: {
-        presence: 'present',
-        position: 'outer top',
-        transform: text.includes('uppercase') ? 'uppercase' : 'small-caps',
-        rule: text.includes('rule') || dramatic ? 'hairline' : 'none',
-        font_role: 'caption',
-        evidence: source,
-        confidence: 0.7,
-      },
-      folio: {
-        position: 'outside bottom',
-        style: 'plain',
-        suppress_on: ['title', 'opener'],
-        evidence: source,
-        confidence: 0.7,
-      },
-      opener: {
-        spacing: airy ? 'generous' : 'compact',
-        recto_start: true,
-        ornament: text.includes('ornament') || dramatic ? 'rule' : 'none',
-        drop_cap: false,
-        evidence: source,
-        confidence: 0.68,
-      },
-      ornaments: {
-        kind: text.includes('ornament') || dramatic ? 'rule' : 'none',
-        weight: 'hairline',
-        placement: 'chapter opener',
-        evidence: source,
-        confidence: 0.66,
-      },
-      table_treatment: {
-        rule_weight: 'hairline',
-        header_treatment: 'plain',
-        row_rules: 'header-only',
-        density: 'balanced',
-        evidence: source,
-        confidence: 0.7,
-      },
-      caption_treatment: {
-        position: 'below',
-        label_style: 'small-caps',
-        alignment: text.includes('left') ? 'left' : 'center',
-        evidence: source,
-        confidence: 0.7,
-      },
-      finish: {
-        register: 'literary',
-        confidence: 0.7,
-      },
-    },
-    rules: [
-      {
-        rule: 'emulate the uploaded book reference through safe Pure Render tokens',
-        evidence: source,
-        confidence: sample ? 0.78 : 0.68,
-      },
-      {
-        rule: prompt.trim() || 'use restrained long-form book treatment',
-        evidence: 'book design concern',
-        confidence: prompt.trim() ? 0.72 : 0.62,
-      },
-    ],
-    derived: null,
-  }
-}
-
-export function buildWriterPrintStyleProfileFromReference({
-  source,
-  prompt,
-  sample,
-}: {
-  source: string
-  prompt: string
-  sample?: PrintReferenceImageSample
-}): PrintStyleProfile {
-  const text = prompt.toLowerCase()
-  const sans = text.includes('sans') || text.includes('modern')
-  const airy = text.includes('airy') || text.includes('open')
-  const compact = text.includes('compact') || text.includes('dense')
-  const highContrast =
-    text.includes('high contrast') || text.includes('crisp')
-  const flush = !text.includes('justify')
-  return {
-    schema_version: '1.0',
-    sources: [{ id: source, note: 'writer print design reference' }],
-    exemplar_quality: {
-      usable: true,
-      reason: sample
-        ? 'local pixel extraction from uploaded writer reference image'
-        : 'writer design concern inferred from description',
-      confidence: sample ? 0.74 : 0.66,
-    },
-    observations: {
-      palette: [
-        {
-          role: 'surface',
-          approx_hex:
-            sample?.paper ?? (text.includes('cream') ? '#FBFAF4' : '#FFFFFF'),
-          coverage: 'dominant',
-          where_seen: sample ? 'largest light color cluster' : 'description',
-          confidence: sample ? 0.78 : 0.62,
-        },
-        {
-          role: 'ink',
-          approx_hex: sample?.ink ?? (highContrast ? '#111111' : '#202020'),
-          coverage: 'frequent',
-          where_seen: sample ? 'dark text-like pixels' : 'description',
-          confidence: sample ? 0.74 : 0.64,
-        },
-        {
-          role: 'accent',
-          approx_hex:
-            sample?.accent ?? (text.includes('blue') ? '#335f8f' : '#5f7f6c'),
-          coverage: 'sparse',
-          where_seen: sample
-            ? 'most saturated non-neutral cluster'
-            : 'description',
-          confidence: sample?.accentConfidence ?? 0.62,
-        },
-      ],
-      type: [
-        {
-          role: 'display',
-          class: sans ? 'sans' : 'serif',
-          serif_detail: 'bracketed',
-          confidence: 0.68,
-        },
-        {
-          role: 'body',
-          class: sans ? 'sans' : 'serif',
-          serif_detail: 'bracketed',
-          confidence: 0.7,
-        },
-        {
-          role: 'caption',
-          class: 'sans',
-          confidence: 0.68,
-        },
-      ],
-      type_pairing: {
-        size_contrast: compact ? 'subtle' : 'moderate',
-        confidence: 0.66,
-      },
-      type_scale: {
-        body_pt: compact ? 10.2 : 10.8,
-        title_scale: compact ? 1.75 : 2,
-        section_scale: compact ? 1.2 : 1.28,
-        caption_scale: 0.82,
-        footnote_scale: 0.78,
-        confidence: sample ? 0.64 : 0.6,
-      },
-      text_setting: {
-        alignment: flush ? 'flush-left' : 'justified',
-        hyphenation: flush ? 'absent' : 'present',
-        measure_cpl: compact ? 68 : 62,
-        leading_feel: airy ? 'airy' : compact ? 'tight' : 'normal',
-        confidence: 0.68,
-      },
-      page_model: {
-        columns: 1,
-        margin_generosity: airy ? 'generous' : 'moderate',
-        margin_asymmetry: 'symmetric',
-        running_heads: 'absent',
-        folio_position: 'bottom center',
-        caption_position: 'below',
-        confidence: 0.62,
-      },
-      table_treatment: {
-        rule_weight: 'hairline',
-        header_treatment: 'plain',
-        row_rules: 'header-only',
-        density: compact ? 'compact' : 'balanced',
-        evidence: source,
-        confidence: 0.66,
-      },
-      caption_treatment: {
-        position: 'below',
-        label_style: 'plain',
-        alignment: 'left',
-        evidence: source,
-        confidence: 0.66,
-      },
-      finish: {
-        register: 'draft',
-        confidence: 0.72,
-      },
-    },
-    rules: [
-      {
-        rule: 'emulate the uploaded writer reference through safe Pure Render tokens',
-        evidence: source,
-        confidence: sample ? 0.74 : 0.66,
-      },
-      {
-        rule:
-          prompt.trim() ||
-          'keep writer output simple, readable, and free of manuscript noise',
-        evidence: 'writer design concern',
-        confidence: prompt.trim() ? 0.68 : 0.62,
-      },
-    ],
-    derived: null,
-  }
-}
-
-function extractJsonObject(text: string): string {
-  const trimmed = text.trim()
-  if (trimmed.startsWith('{') && trimmed.endsWith('}')) return trimmed
-  const start = trimmed.indexOf('{')
-  const end = trimmed.lastIndexOf('}')
-  if (start === -1 || end === -1 || end <= start) {
-    throw new Error('Model response did not contain a JSON object')
-  }
-  return trimmed.slice(start, end + 1)
-}
-
-function bestByRole<
-  T extends PrintStylePaletteObservation | PrintStyleTypeObservation,
->(items: readonly T[]): T[] {
-  const byRole = new Map<string, T>()
-  for (const item of items) {
-    const existing = byRole.get(item.role)
-    if (!existing || item.confidence > existing.confidence) {
-      byRole.set(item.role, item)
-    }
-  }
-  return Array.from(byRole.values())
-}
-
-function bestByConfidence<T extends { confidence?: number }>(
-  items: readonly (T | undefined)[],
-): T | undefined {
-  return items
-    .filter((item): item is T => Boolean(item))
-    .sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0))[0]
-}
-
-function reconcileRules(rules: readonly PrintStyleRule[]): PrintStyleRule[] {
-  const byRule = new Map<string, PrintStyleRule>()
-  for (const rule of rules) {
-    const key = rule.rule.trim().toLowerCase()
-    if (!key) continue
-    const existing = byRule.get(key)
-    if (!existing || rule.confidence > existing.confidence) {
-      byRule.set(key, rule)
-    }
-  }
-  return Array.from(byRule.values()).sort((a, b) => b.confidence - a.confidence)
-}
-
-function detectReconciliationConflicts(
-  profiles: readonly PrintStyleProfile[],
-): PrintStyleRule[] {
-  const conflicts: PrintStyleRule[] = []
-  const addConflict = (label: string, values: readonly FieldValue[]): void => {
-    const confident = values.filter(
-      item => item.value !== undefined && item.value !== '' && item.confidence >= 0.6,
-    )
-    const unique = Array.from(
-      new Map(confident.map(item => [String(item.value), item])).values(),
-    )
-    if (unique.length < 2) return
-    conflicts.push({
-      rule: `Reference conflict: ${label} disagrees across uploaded images (${unique
-        .map(item => `${item.source}: ${item.value}`)
-        .join('; ')}). Highest-confidence value was used; review before saving as a shared theme.`,
-      evidence: unique.map(item => item.source).join(', '),
-      confidence: Math.min(0.9, average(unique.map(item => item.confidence))),
-    })
-  }
-
-  const sourceId = (profile: PrintStyleProfile, index: number): string =>
-    profile.sources?.[0]?.id ?? `source-${index + 1}`
-
-  addConflict(
-    'body font class',
-    profiles.map((profile, index) => ({
-      source: sourceId(profile, index),
-      value: profile.observations.type?.find(item => item.role === 'body')?.class,
-      confidence:
-        profile.observations.type?.find(item => item.role === 'body')?.confidence ??
-        0,
-    })),
-  )
-  addConflict(
-    'accent color',
-    profiles.map((profile, index) => ({
-      source: sourceId(profile, index),
-      value: profile.observations.palette?.find(item => item.role === 'accent')
-        ?.approx_hex,
-      confidence:
-        profile.observations.palette?.find(item => item.role === 'accent')
-          ?.confidence ?? 0,
-    })),
-  )
-  addConflict(
-    'text alignment',
-    profiles.map((profile, index) => ({
-      source: sourceId(profile, index),
-      value: profile.observations.text_setting?.alignment,
-      confidence: profile.observations.text_setting?.confidence ?? 0,
-    })),
-  )
-  addConflict(
-    'page columns',
-    profiles.map((profile, index) => ({
-      source: sourceId(profile, index),
-      value: profile.observations.page_model?.columns,
-      confidence: profile.observations.page_model?.confidence ?? 0,
-    })),
-  )
-  addConflict(
-    'running heads',
-    profiles.map((profile, index) => ({
-      source: sourceId(profile, index),
-      value: profile.observations.running_heads?.presence,
-      confidence: profile.observations.running_heads?.confidence ?? 0,
-    })),
-  )
-  addConflict(
-    'opener ornament',
-    profiles.map((profile, index) => ({
-      source: sourceId(profile, index),
-      value: profile.observations.opener?.ornament,
-      confidence: profile.observations.opener?.confidence ?? 0,
-    })),
-  )
-  addConflict(
-    'table density',
-    profiles.map((profile, index) => ({
-      source: sourceId(profile, index),
-      value: profile.observations.table_treatment?.density,
-      confidence: profile.observations.table_treatment?.confidence ?? 0,
-    })),
-  )
-  addConflict(
-    'caption position',
-    profiles.map((profile, index) => ({
-      source: sourceId(profile, index),
-      value: profile.observations.caption_treatment?.position,
-      confidence: profile.observations.caption_treatment?.confidence ?? 0,
-    })),
-  )
-
-  return conflicts
-}
-
-interface FieldValue {
-  source: string
-  value: string | number | undefined
-  confidence: number
-}
-
-function average(values: readonly number[]): number {
-  if (values.length === 0) return 0
-  return values.reduce((sum, value) => sum + value, 0) / values.length
-}
-
-function defaultPrintReferenceImageSample(): PrintReferenceImageSample {
-  return {
-    paper: '#FFFFFF',
-    ink: '#1A1A1A',
-    accent: '#46584B',
-    accentConfidence: 0.45,
-  }
-}
-
-function quantizeColor(value: number | undefined): number {
-  return Math.round((value ?? 0) / 24) * 24
-}
-
-function rgbToHex(rgb: readonly number[]): string {
-  return `#${rgb
-    .map(value =>
-      Math.max(0, Math.min(255, value)).toString(16).padStart(2, '0'),
-    )
-    .join('')}`
-}
-
-function colorLuminance([r, g, b]: readonly number[]): number {
-  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255
-}
-
-function colorSaturation([r, g, b]: readonly number[]): number {
-  const max = Math.max(r, g, b)
-  const min = Math.min(r, g, b)
-  return max === 0 ? 0 : (max - min) / max
-}
+import type {
+  PrintStylePaletteObservation,
+  PrintStyleProfile,
+  PrintStyleRule,
+  PrintStyleTypeObservation,
+} from './types.js'
+
+export const PRINT_TOKEN_EXTRACTION_PROMPT = `PRINT-TOKEN EXTRACTION PROMPT - v1.0
+=========================================================================
+Sent to a vision model alongside one or more reference images (a journal
+page, a book spread, a typeset PDF, a cover). Produces a STYLE PROFILE that
+the compiler turns into a print theme.json for the Pure Render system.
+
+Pair this prompt with: print-style-profile.schema.json (the output shape).
+=========================================================================
+
+ROLE
+You are a print design-system extractor. Given one or more reference images of
+TYPESET PAGES, reverse-engineer a reusable visual system that could set NEW text
+in the same family. You are not describing the image; you are inferring the rules
+a typesetter followed.
+
+DIVISION OF LABOR (critical)
+- You judge classification, relationships, mood, and rules - what you are good at.
+- You do NOT report exact colors or measurements as truth. A separate pixel pass
+  refines every numeric value. Give approx values as HINTS only.
+- You NEVER name or identify a typeface. Report ATTRIBUTES that let a substitute be
+  chosen from a licensed library.
+- Print-specific: estimate things in RELATIVE terms (ratios, proportions of the
+  page, x-heights relative to cap height) rather than absolute points, because you
+  cannot measure the trim size from pixels.
+
+PER IMAGE, record OBSERVATIONS (what is literally present):
+
+1. palette - print is restrained. By ROLE, not swatch:
+   - surface (paper/background), ink (body text), accent (rules/links/numbers - note
+     how sparingly used), and any secondary (captions, folios).
+   - For each: role, approx_hex (HINT), where_seen, coverage (dominant|frequent|sparse).
+
+2. type - by ATTRIBUTE not identity, per ROLE you can see (display/headings, body,
+   caption/folio, mono/code):
+   - class (serif|sans|slab|script), weight, width, contrast/stress (thick-thin),
+     x_height (low|medium|high), case_usage, and the SERIF DETAIL if serif
+     (bracketed|slab|hairline|wedge) - this most determines the substitute.
+     - pairing: heading/body relationship, and size_contrast (dramatic|moderate|subtle)
+     - implies the scale ratio.
+   - type_scale: relative or estimated scale for title, chapter title, section
+     heading, body, caption, and footnote. Keep absolute point sizes low-confidence
+     unless the source provides a known trim/scale.
+
+3. text setting - the heart of print. Estimate RELATIVELY:
+   - alignment (justified|flush-left), hyphenation (present|absent),
+   - measure: approx characters per line (count a representative full line),
+   - leading_feel (tight|normal|airy) - ratio of line gap to text size,
+   - paragraphing (indented runs | space-between | both),
+   - density (airy|balanced|dense).
+
+4. page model - what you can infer about the page:
+   - columns (1|2|n),
+   - margin_generosity (tight|moderate|generous) and which margins are larger
+     (inner/outer/top/bottom asymmetry -> suggests recto/verso canon),
+     - running heads (present|absent, position), folio (position),
+     - figure/table treatment (captions above|below, rule style, numbering visible).
+
+5. page furniture and ornaments - manuscript/book references often depend on
+   details outside body text. Capture these as structured observations:
+   - running_heads: presence, position, transform, rule/no rule, font_role.
+   - folio: position, style, suppress_on first/opener pages if visible.
+   - opener: chapter/opening spacing, recto_start, ornament, drop_cap.
+   - ornaments: none|rule|divider|fleuron|chapter-mark, weight, placement.
+   - table_treatment: rule_weight, header_treatment, row_rules, density.
+   - caption_treatment: position, label_style, alignment.
+
+6. finish & mood - register (scholarly|literary|editorial|technical|...),
+   temperature, era. Subjective; only you can supply it.
+
+THEN INFER THE RULES (the most important output)
+List the constraints the setting obeys - what must stay true for a NEW page to
+belong to this family.
+
+REQUIREMENTS
+- Cite evidence for every field (where in the image you saw it).
+- Give confidence 0..1 per field. When unsure, LOWER confidence - do NOT guess to
+  fill a slot. A low-confidence field is dropped for a safe default; a confident
+  wrong guess corrupts the system.
+- Output OBSERVATIONS and RULES only. Do NOT output final tokens or a theme - the
+  compiler derives those. Leave "derived": null.
+- Flag bad exemplars: if a source is a poor reference, set exemplar_quality.usable=false
+  with a reason, so it is not faithfully reproduced.
+- Multiple images: observations PER source id. Do NOT merge or average; the compiler
+  reconciles.
+
+OUTPUT
+Strict JSON conforming to print-style-profile.schema.json. No prose, no markdown,
+no commentary outside the JSON.`
+
+export const PRINT_STYLE_PROFILE_SCHEMA = {
+  type: 'object',
+  required: [
+    'schema_version',
+    'sources',
+    'exemplar_quality',
+    'observations',
+    'rules',
+    'derived',
+  ],
+  properties: {
+    schema_version: { const: '1.0' },
+    sources: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['id'],
+        properties: { id: { type: 'string' }, note: { type: 'string' } },
+      },
+    },
+    exemplar_quality: {
+      type: 'object',
+      required: ['usable', 'reason', 'confidence'],
+      properties: {
+        usable: { type: 'boolean' },
+        reason: { type: 'string' },
+        confidence: { type: 'number', minimum: 0, maximum: 1 },
+      },
+    },
+    observations: {
+      type: 'object',
+      properties: {
+        palette: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['role', 'confidence'],
+            properties: {
+              role: { enum: ['surface', 'ink', 'accent', 'secondary'] },
+              approx_hex: {
+                type: 'string',
+                description: 'HINT only; refined by pixel pass',
+              },
+              coverage: { enum: ['dominant', 'frequent', 'sparse'] },
+              where_seen: { type: 'string' },
+              confidence: { type: 'number' },
+            },
+          },
+        },
+        type: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['role', 'class', 'confidence'],
+            properties: {
+              role: { enum: ['display', 'body', 'caption', 'mono'] },
+              class: { enum: ['serif', 'sans', 'slab', 'script'] },
+              mood: {
+                enum: [
+                  'old-style',
+                  'transitional',
+                  'slab',
+                  'humanist-sans',
+                  'grotesque-sans',
+                  'geometric-sans',
+                  'mono',
+                ],
+              },
+              serif_detail: {
+                enum: ['bracketed', 'slab', 'hairline', 'wedge', 'none'],
+              },
+              weight: { type: 'string' },
+              width: { type: 'string' },
+              stress: { enum: ['high-contrast', 'moderate', 'low-contrast'] },
+              x_height: { enum: ['low', 'medium', 'high'] },
+              case_usage: { type: 'string' },
+              where_seen: { type: 'string' },
+              confidence: { type: 'number' },
+            },
+          },
+        },
+        type_pairing: {
+          type: 'object',
+          properties: {
+            size_contrast: { enum: ['dramatic', 'moderate', 'subtle'] },
+            note: { type: 'string' },
+            confidence: { type: 'number' },
+          },
+        },
+        type_scale: {
+          type: 'object',
+          properties: {
+            body_pt: { type: 'number' },
+            title_scale: { type: 'number' },
+            chapter_title_scale: { type: 'number' },
+            section_scale: { type: 'number' },
+            caption_scale: { type: 'number' },
+            footnote_scale: { type: 'number' },
+            confidence: { type: 'number' },
+          },
+        },
+        text_setting: {
+          type: 'object',
+          properties: {
+            alignment: { enum: ['justified', 'flush-left'] },
+            hyphenation: { enum: ['present', 'absent'] },
+            measure_cpl: { type: 'number' },
+            leading_feel: { enum: ['tight', 'normal', 'airy'] },
+            paragraphing: { enum: ['indented', 'spaced', 'both'] },
+            density: { enum: ['airy', 'balanced', 'dense'] },
+            confidence: { type: 'number' },
+          },
+        },
+        page_model: {
+          type: 'object',
+          properties: {
+            columns: { type: 'integer' },
+            margin_generosity: { enum: ['tight', 'moderate', 'generous'] },
+            margin_asymmetry: { type: 'string' },
+            running_heads: { enum: ['present', 'absent'] },
+            folio_position: { type: 'string' },
+            caption_position: { enum: ['above', 'below'] },
+            confidence: { type: 'number' },
+          },
+        },
+        running_heads: {
+          type: 'object',
+          properties: {
+            presence: { enum: ['present', 'absent'] },
+            position: { type: 'string' },
+            transform: {
+              enum: ['uppercase', 'small-caps', 'title-case', 'none'],
+            },
+            rule: { enum: ['none', 'hairline', 'solid'] },
+            font_role: {
+              enum: ['display', 'body', 'caption', 'sans'],
+            },
+            evidence: { type: 'string' },
+            confidence: { type: 'number' },
+          },
+        },
+        folio: {
+          type: 'object',
+          properties: {
+            position: { type: 'string' },
+            style: { enum: ['plain', 'small-caps', 'bracketed'] },
+            suppress_on: {
+              type: 'array',
+              items: { type: 'string' },
+            },
+            evidence: { type: 'string' },
+            confidence: { type: 'number' },
+          },
+        },
+        opener: {
+          type: 'object',
+          properties: {
+            spacing: { enum: ['compact', 'balanced', 'generous'] },
+            recto_start: { type: 'boolean' },
+            ornament: {
+              enum: ['none', 'rule', 'divider', 'fleuron', 'chapter-mark'],
+            },
+            drop_cap: { type: 'boolean' },
+            evidence: { type: 'string' },
+            confidence: { type: 'number' },
+          },
+        },
+        ornaments: {
+          type: 'object',
+          properties: {
+            kind: {
+              enum: ['none', 'rule', 'divider', 'fleuron', 'chapter-mark'],
+            },
+            weight: { enum: ['hairline', 'light', 'medium'] },
+            placement: { type: 'string' },
+            evidence: { type: 'string' },
+            confidence: { type: 'number' },
+          },
+        },
+        table_treatment: {
+          type: 'object',
+          properties: {
+            rule_weight: { enum: ['hairline', 'light', 'medium'] },
+            header_treatment: { type: 'string' },
+            row_rules: { enum: ['none', 'hairline', 'light'] },
+            density: { enum: ['airy', 'balanced', 'dense'] },
+            evidence: { type: 'string' },
+            confidence: { type: 'number' },
+          },
+        },
+        caption_treatment: {
+          type: 'object',
+          properties: {
+            position: { enum: ['above', 'below'] },
+            label_style: { enum: ['bold', 'small-caps', 'plain'] },
+            alignment: { enum: ['left', 'center', 'justified'] },
+            evidence: { type: 'string' },
+            confidence: { type: 'number' },
+          },
+        },
+        finish: {
+          type: 'object',
+          properties: {
+            register: { type: 'string' },
+            temperature: { type: 'string' },
+            era: { type: 'string' },
+            confidence: { type: 'number' },
+          },
+        },
+      },
+    },
+    rules: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['rule', 'confidence'],
+        properties: {
+          rule: { type: 'string' },
+          evidence: { type: 'string' },
+          confidence: { type: 'number' },
+        },
+      },
+    },
+    derived: {
+      type: ['object', 'null'],
+      description: 'compiler-only; model leaves null',
+    },
+  },
+} as const
+
+export interface PrintStyleProfilePromptInput {
+  mode: 'image' | 'description'
+  concerns?: string
+  imageName?: string
+  imageMimeType?: string
+  imagePixelSummary?: string
+}
+
+export function buildPrintStyleProfilePrompt(
+  input: PrintStyleProfilePromptInput,
+): string {
+  const reference =
+    input.mode === 'image'
+      ? [
+          `Reference image: ${input.imageName ?? 'uploaded image'}`,
+          input.imageMimeType ? `MIME type: ${input.imageMimeType}` : '',
+          input.imagePixelSummary
+            ? `Pixel pass summary: ${input.imagePixelSummary}`
+            : 'Use the attached image as the visual source.',
+        ]
+          .filter(Boolean)
+          .join('\n')
+      : [
+          'Text-only design brief. This is valid style evidence.',
+          'Do not reject the exemplar merely because no image is attached.',
+          'Infer the print style profile from the user concerns and keep visual-only fields low-confidence.',
+        ].join('\n')
+
+  return [
+    PRINT_TOKEN_EXTRACTION_PROMPT,
+    '',
+    'JSON SCHEMA',
+    JSON.stringify(PRINT_STYLE_PROFILE_SCHEMA, null, 2),
+    '',
+    'USER DESIGN INPUT',
+    reference,
+    `Concerns/preferences: ${input.concerns?.trim() || 'none supplied'}`,
+    '',
+    'Return only one JSON object matching the schema.',
+  ].join('\n')
+}
+
+export function parsePrintStyleProfileResponse(
+  text: string,
+): PrintStyleProfile {
+  const parsed = JSON.parse(extractJsonObject(text)) as unknown
+  if (!isPrintStyleProfile(parsed)) {
+    throw new Error(
+      'Model response did not match the print style profile schema',
+    )
+  }
+  return parsed
+}
+
+export function reconcilePrintStyleProfiles(
+  profiles: readonly PrintStyleProfile[],
+): PrintStyleProfile {
+  const usable = profiles.filter(profile => profile.exemplar_quality.usable)
+  const inputs = usable.length > 0 ? usable : profiles
+  if (inputs.length === 0) {
+    throw new Error('No print style profiles to reconcile')
+  }
+  if (inputs.length === 1) return inputs[0]!
+
+  return {
+    schema_version: '1.0',
+    sources: inputs.flatMap(profile => profile.sources ?? []),
+    exemplar_quality: {
+      usable: usable.length > 0,
+      reason:
+        usable.length === profiles.length
+          ? 'reconciled multiple usable print references'
+          : 'reconciled usable print references; discarded unusable exemplars',
+      confidence: average(
+        inputs.map(profile => profile.exemplar_quality.confidence),
+      ),
+    },
+    observations: {
+      palette: bestByRole(
+        inputs.flatMap(profile => profile.observations.palette ?? []),
+      ),
+      type: bestByRole(
+        inputs.flatMap(profile => profile.observations.type ?? []),
+      ),
+      type_pairing: bestByConfidence(
+        inputs.map(profile => profile.observations.type_pairing),
+      ),
+      type_scale: bestByConfidence(
+        inputs.map(profile => profile.observations.type_scale),
+      ),
+      text_setting: bestByConfidence(
+        inputs.map(profile => profile.observations.text_setting),
+      ),
+      page_model: bestByConfidence(
+        inputs.map(profile => profile.observations.page_model),
+      ),
+      running_heads: bestByConfidence(
+        inputs.map(profile => profile.observations.running_heads),
+      ),
+      folio: bestByConfidence(
+        inputs.map(profile => profile.observations.folio),
+      ),
+      opener: bestByConfidence(
+        inputs.map(profile => profile.observations.opener),
+      ),
+      ornaments: bestByConfidence(
+        inputs.map(profile => profile.observations.ornaments),
+      ),
+      table_treatment: bestByConfidence(
+        inputs.map(profile => profile.observations.table_treatment),
+      ),
+      caption_treatment: bestByConfidence(
+        inputs.map(profile => profile.observations.caption_treatment),
+      ),
+      finish: bestByConfidence(
+        inputs.map(profile => profile.observations.finish),
+      ),
+    },
+    rules: [
+      ...reconcileRules(inputs.flatMap(profile => profile.rules ?? [])),
+      ...detectReconciliationConflicts(inputs),
+    ],
+    derived: null,
+  }
+}
+
+export function isPrintStyleProfile(
+  value: unknown,
+): value is PrintStyleProfile {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<PrintStyleProfile>
+  return (
+    typeof candidate.schema_version === 'string' &&
+    Boolean(candidate.observations) &&
+    typeof candidate.observations === 'object' &&
+    Boolean(candidate.exemplar_quality) &&
+    typeof candidate.exemplar_quality === 'object' &&
+    typeof candidate.exemplar_quality.usable === 'boolean' &&
+    typeof candidate.exemplar_quality.reason === 'string' &&
+    typeof candidate.exemplar_quality.confidence === 'number' &&
+    Array.isArray(candidate.rules) &&
+    candidate.derived === null
+  )
+}
+
+export interface PrintReferenceImageSample {
+  paper: string
+  ink: string
+  accent: string
+  accentConfidence: number
+}
+
+export async function samplePrintReferenceImageColors(
+  image: File,
+): Promise<PrintReferenceImageSample> {
+  const bitmap = await createImageBitmap(image)
+  try {
+    const canvas = document.createElement('canvas')
+    canvas.width = 80
+    canvas.height = 80
+    const context = canvas.getContext('2d')
+    if (!context) return defaultPrintReferenceImageSample()
+
+    context.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
+    const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data
+    const buckets = new Map<
+      string,
+      { rgb: [number, number, number]; count: number }
+    >()
+    for (let index = 0; index < pixels.length; index += 16) {
+      const alpha = pixels[index + 3]
+      if (alpha < 128) continue
+      const rgb: [number, number, number] = [
+        quantizeColor(pixels[index]),
+        quantizeColor(pixels[index + 1]),
+        quantizeColor(pixels[index + 2]),
+      ]
+      const key = rgb.join(',')
+      const bucket = buckets.get(key)
+      if (bucket) bucket.count += 1
+      else buckets.set(key, { rgb, count: 1 })
+    }
+
+    const ranked = Array.from(buckets.values()).sort(
+      (a, b) => b.count - a.count,
+    )
+    const light = ranked.find(bucket => colorLuminance(bucket.rgb) > 0.72)
+    const dark =
+      ranked
+        .filter(bucket => colorLuminance(bucket.rgb) < 0.36)
+        .sort((a, b) => b.count - a.count)[0] ?? ranked[ranked.length - 1]
+    const saturated = ranked
+      .filter(bucket => colorSaturation(bucket.rgb) > 0.22)
+      .sort(
+        (a, b) =>
+          colorSaturation(b.rgb) * b.count - colorSaturation(a.rgb) * a.count,
+      )[0]
+
+    return {
+      paper: rgbToHex(light?.rgb ?? [255, 255, 255]),
+      ink: rgbToHex(dark?.rgb ?? [26, 26, 26]),
+      accent: rgbToHex(saturated?.rgb ?? [70, 88, 75]),
+      accentConfidence: saturated ? 0.72 : 0.45,
+    }
+  } finally {
+    bitmap.close()
+  }
+}
+
+export function buildBookPrintStyleProfileFromReference({
+  source,
+  prompt,
+  sample,
+}: {
+  source: string
+  prompt: string
+  sample?: PrintReferenceImageSample
+}): PrintStyleProfile {
+  const text = prompt.toLowerCase()
+  const sans = text.includes('sans')
+  const dramatic = text.includes('dramatic') || text.includes('literary')
+  const airy = text.includes('airy') || text.includes('generous')
+  return {
+    schema_version: '1.0',
+    sources: [{ id: source, note: 'book print design reference' }],
+    exemplar_quality: {
+      usable: true,
+      reason: sample
+        ? 'local pixel extraction from uploaded book reference image'
+        : 'book design concern inferred from description',
+      confidence: sample ? 0.78 : 0.68,
+    },
+    observations: {
+      palette: [
+        {
+          role: 'surface',
+          approx_hex:
+            sample?.paper ?? (text.includes('cream') ? '#FBFAF4' : '#FFFFFF'),
+          coverage: 'dominant',
+          where_seen: sample ? 'largest light color cluster' : 'description',
+          confidence: sample ? 0.82 : 0.64,
+        },
+        {
+          role: 'ink',
+          approx_hex: sample?.ink ?? '#1A1A1A',
+          coverage: 'frequent',
+          where_seen: sample ? 'dark text-like pixels' : 'description',
+          confidence: sample ? 0.76 : 0.64,
+        },
+        {
+          role: 'accent',
+          approx_hex:
+            sample?.accent ?? (text.includes('red') ? '#7A2634' : '#46584B'),
+          coverage: 'sparse',
+          where_seen: sample
+            ? 'most saturated non-neutral cluster'
+            : 'description',
+          confidence: sample?.accentConfidence ?? 0.62,
+        },
+      ],
+      type: [
+        {
+          role: 'display',
+          class: sans ? 'sans' : 'serif',
+          serif_detail: dramatic ? 'hairline' : 'bracketed',
+          confidence: 0.72,
+        },
+        {
+          role: 'body',
+          class: sans ? 'sans' : 'serif',
+          serif_detail: 'bracketed',
+          confidence: 0.72,
+        },
+        {
+          role: 'caption',
+          class: 'sans',
+          confidence: 0.7,
+        },
+      ],
+      type_pairing: {
+        size_contrast: dramatic ? 'dramatic' : 'moderate',
+        confidence: 0.72,
+      },
+      type_scale: {
+        body_pt: dramatic ? 10.8 : 10.6,
+        title_scale: dramatic ? 2.6 : 2.2,
+        chapter_title_scale: dramatic ? 2.2 : 1.9,
+        section_scale: dramatic ? 1.5 : 1.35,
+        caption_scale: 0.82,
+        footnote_scale: 0.78,
+        confidence: sample ? 0.68 : 0.62,
+      },
+      text_setting: {
+        alignment: text.includes('flush') ? 'flush-left' : 'justified',
+        hyphenation: text.includes('no hyphen') ? 'absent' : 'present',
+        measure_cpl: text.includes('narrow') ? 54 : 58,
+        leading_feel: airy ? 'airy' : 'normal',
+        confidence: 0.7,
+      },
+      page_model: {
+        columns: 1,
+        margin_generosity: airy ? 'generous' : 'moderate',
+        margin_asymmetry: 'inner<outer',
+        running_heads: 'present',
+        folio_position: 'outside bottom',
+        caption_position: 'below',
+        confidence: 0.7,
+      },
+      running_heads: {
+        presence: 'present',
+        position: 'outer top',
+        transform: text.includes('uppercase') ? 'uppercase' : 'small-caps',
+        rule: text.includes('rule') || dramatic ? 'hairline' : 'none',
+        font_role: 'caption',
+        evidence: source,
+        confidence: 0.7,
+      },
+      folio: {
+        position: 'outside bottom',
+        style: 'plain',
+        suppress_on: ['title', 'opener'],
+        evidence: source,
+        confidence: 0.7,
+      },
+      opener: {
+        spacing: airy ? 'generous' : 'compact',
+        recto_start: true,
+        ornament: text.includes('ornament') || dramatic ? 'rule' : 'none',
+        drop_cap: false,
+        evidence: source,
+        confidence: 0.68,
+      },
+      ornaments: {
+        kind: text.includes('ornament') || dramatic ? 'rule' : 'none',
+        weight: 'hairline',
+        placement: 'chapter opener',
+        evidence: source,
+        confidence: 0.66,
+      },
+      table_treatment: {
+        rule_weight: 'hairline',
+        header_treatment: 'plain',
+        row_rules: 'header-only',
+        density: 'balanced',
+        evidence: source,
+        confidence: 0.7,
+      },
+      caption_treatment: {
+        position: 'below',
+        label_style: 'small-caps',
+        alignment: text.includes('left') ? 'left' : 'center',
+        evidence: source,
+        confidence: 0.7,
+      },
+      finish: {
+        register: 'literary',
+        confidence: 0.7,
+      },
+    },
+    rules: [
+      {
+        rule: 'emulate the uploaded book reference through safe Pure Render tokens',
+        evidence: source,
+        confidence: sample ? 0.78 : 0.68,
+      },
+      {
+        rule: prompt.trim() || 'use restrained long-form book treatment',
+        evidence: 'book design concern',
+        confidence: prompt.trim() ? 0.72 : 0.62,
+      },
+    ],
+    derived: null,
+  }
+}
+
+export function buildWriterPrintStyleProfileFromReference({
+  source,
+  prompt,
+  sample,
+}: {
+  source: string
+  prompt: string
+  sample?: PrintReferenceImageSample
+}): PrintStyleProfile {
+  const text = prompt.toLowerCase()
+  const sans = text.includes('sans') || text.includes('modern')
+  const airy = text.includes('airy') || text.includes('open')
+  const compact = text.includes('compact') || text.includes('dense')
+  const highContrast =
+    text.includes('high contrast') || text.includes('crisp')
+  const flush = !text.includes('justify')
+  return {
+    schema_version: '1.0',
+    sources: [{ id: source, note: 'writer print design reference' }],
+    exemplar_quality: {
+      usable: true,
+      reason: sample
+        ? 'local pixel extraction from uploaded writer reference image'
+        : 'writer design concern inferred from description',
+      confidence: sample ? 0.74 : 0.66,
+    },
+    observations: {
+      palette: [
+        {
+          role: 'surface',
+          approx_hex:
+            sample?.paper ?? (text.includes('cream') ? '#FBFAF4' : '#FFFFFF'),
+          coverage: 'dominant',
+          where_seen: sample ? 'largest light color cluster' : 'description',
+          confidence: sample ? 0.78 : 0.62,
+        },
+        {
+          role: 'ink',
+          approx_hex: sample?.ink ?? (highContrast ? '#111111' : '#202020'),
+          coverage: 'frequent',
+          where_seen: sample ? 'dark text-like pixels' : 'description',
+          confidence: sample ? 0.74 : 0.64,
+        },
+        {
+          role: 'accent',
+          approx_hex:
+            sample?.accent ?? (text.includes('blue') ? '#335f8f' : '#5f7f6c'),
+          coverage: 'sparse',
+          where_seen: sample
+            ? 'most saturated non-neutral cluster'
+            : 'description',
+          confidence: sample?.accentConfidence ?? 0.62,
+        },
+      ],
+      type: [
+        {
+          role: 'display',
+          class: sans ? 'sans' : 'serif',
+          serif_detail: 'bracketed',
+          confidence: 0.68,
+        },
+        {
+          role: 'body',
+          class: sans ? 'sans' : 'serif',
+          serif_detail: 'bracketed',
+          confidence: 0.7,
+        },
+        {
+          role: 'caption',
+          class: 'sans',
+          confidence: 0.68,
+        },
+      ],
+      type_pairing: {
+        size_contrast: compact ? 'subtle' : 'moderate',
+        confidence: 0.66,
+      },
+      type_scale: {
+        body_pt: compact ? 10.2 : 10.8,
+        title_scale: compact ? 1.75 : 2,
+        section_scale: compact ? 1.2 : 1.28,
+        caption_scale: 0.82,
+        footnote_scale: 0.78,
+        confidence: sample ? 0.64 : 0.6,
+      },
+      text_setting: {
+        alignment: flush ? 'flush-left' : 'justified',
+        hyphenation: flush ? 'absent' : 'present',
+        measure_cpl: compact ? 68 : 62,
+        leading_feel: airy ? 'airy' : compact ? 'tight' : 'normal',
+        confidence: 0.68,
+      },
+      page_model: {
+        columns: 1,
+        margin_generosity: airy ? 'generous' : 'moderate',
+        margin_asymmetry: 'symmetric',
+        running_heads: 'absent',
+        folio_position: 'bottom center',
+        caption_position: 'below',
+        confidence: 0.62,
+      },
+      table_treatment: {
+        rule_weight: 'hairline',
+        header_treatment: 'plain',
+        row_rules: 'header-only',
+        density: compact ? 'compact' : 'balanced',
+        evidence: source,
+        confidence: 0.66,
+      },
+      caption_treatment: {
+        position: 'below',
+        label_style: 'plain',
+        alignment: 'left',
+        evidence: source,
+        confidence: 0.66,
+      },
+      finish: {
+        register: 'draft',
+        confidence: 0.72,
+      },
+    },
+    rules: [
+      {
+        rule: 'emulate the uploaded writer reference through safe Pure Render tokens',
+        evidence: source,
+        confidence: sample ? 0.74 : 0.66,
+      },
+      {
+        rule:
+          prompt.trim() ||
+          'keep writer output simple, readable, and free of manuscript noise',
+        evidence: 'writer design concern',
+        confidence: prompt.trim() ? 0.68 : 0.62,
+      },
+    ],
+    derived: null,
+  }
+}
+
+function extractJsonObject(text: string): string {
+  const trimmed = text.trim()
+  if (trimmed.startsWith('{') && trimmed.endsWith('}')) return trimmed
+  const start = trimmed.indexOf('{')
+  const end = trimmed.lastIndexOf('}')
+  if (start === -1 || end === -1 || end <= start) {
+    throw new Error('Model response did not contain a JSON object')
+  }
+  return trimmed.slice(start, end + 1)
+}
+
+function bestByRole<
+  T extends PrintStylePaletteObservation | PrintStyleTypeObservation,
+>(items: readonly T[]): T[] {
+  const byRole = new Map<string, T>()
+  for (const item of items) {
+    const existing = byRole.get(item.role)
+    if (!existing || item.confidence > existing.confidence) {
+      byRole.set(item.role, item)
+    }
+  }
+  return Array.from(byRole.values())
+}
+
+function bestByConfidence<T extends { confidence?: number }>(
+  items: readonly (T | undefined)[],
+): T | undefined {
+  return items
+    .filter((item): item is T => Boolean(item))
+    .sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0))[0]
+}
+
+function reconcileRules(rules: readonly PrintStyleRule[]): PrintStyleRule[] {
+  const byRule = new Map<string, PrintStyleRule>()
+  for (const rule of rules) {
+    const key = rule.rule.trim().toLowerCase()
+    if (!key) continue
+    const existing = byRule.get(key)
+    if (!existing || rule.confidence > existing.confidence) {
+      byRule.set(key, rule)
+    }
+  }
+  return Array.from(byRule.values()).sort((a, b) => b.confidence - a.confidence)
+}
+
+function detectReconciliationConflicts(
+  profiles: readonly PrintStyleProfile[],
+): PrintStyleRule[] {
+  const conflicts: PrintStyleRule[] = []
+  const addConflict = (label: string, values: readonly FieldValue[]): void => {
+    const confident = values.filter(
+      item => item.value !== undefined && item.value !== '' && item.confidence >= 0.6,
+    )
+    const unique = Array.from(
+      new Map(confident.map(item => [String(item.value), item])).values(),
+    )
+    if (unique.length < 2) return
+    conflicts.push({
+      rule: `Reference conflict: ${label} disagrees across uploaded images (${unique
+        .map(item => `${item.source}: ${item.value}`)
+        .join('; ')}). Highest-confidence value was used; review before saving as a shared theme.`,
+      evidence: unique.map(item => item.source).join(', '),
+      confidence: Math.min(0.9, average(unique.map(item => item.confidence))),
+    })
+  }
+
+  const sourceId = (profile: PrintStyleProfile, index: number): string =>
+    profile.sources?.[0]?.id ?? `source-${index + 1}`
+
+  addConflict(
+    'body font class',
+    profiles.map((profile, index) => ({
+      source: sourceId(profile, index),
+      value: profile.observations.type?.find(item => item.role === 'body')?.class,
+      confidence:
+        profile.observations.type?.find(item => item.role === 'body')?.confidence ??
+        0,
+    })),
+  )
+  addConflict(
+    'accent color',
+    profiles.map((profile, index) => ({
+      source: sourceId(profile, index),
+      value: profile.observations.palette?.find(item => item.role === 'accent')
+        ?.approx_hex,
+      confidence:
+        profile.observations.palette?.find(item => item.role === 'accent')
+          ?.confidence ?? 0,
+    })),
+  )
+  addConflict(
+    'text alignment',
+    profiles.map((profile, index) => ({
+      source: sourceId(profile, index),
+      value: profile.observations.text_setting?.alignment,
+      confidence: profile.observations.text_setting?.confidence ?? 0,
+    })),
+  )
+  addConflict(
+    'page columns',
+    profiles.map((profile, index) => ({
+      source: sourceId(profile, index),
+      value: profile.observations.page_model?.columns,
+      confidence: profile.observations.page_model?.confidence ?? 0,
+    })),
+  )
+  addConflict(
+    'running heads',
+    profiles.map((profile, index) => ({
+      source: sourceId(profile, index),
+      value: profile.observations.running_heads?.presence,
+      confidence: profile.observations.running_heads?.confidence ?? 0,
+    })),
+  )
+  addConflict(
+    'opener ornament',
+    profiles.map((profile, index) => ({
+      source: sourceId(profile, index),
+      value: profile.observations.opener?.ornament,
+      confidence: profile.observations.opener?.confidence ?? 0,
+    })),
+  )
+  addConflict(
+    'table density',
+    profiles.map((profile, index) => ({
+      source: sourceId(profile, index),
+      value: profile.observations.table_treatment?.density,
+      confidence: profile.observations.table_treatment?.confidence ?? 0,
+    })),
+  )
+  addConflict(
+    'caption position',
+    profiles.map((profile, index) => ({
+      source: sourceId(profile, index),
+      value: profile.observations.caption_treatment?.position,
+      confidence: profile.observations.caption_treatment?.confidence ?? 0,
+    })),
+  )
+
+  return conflicts
+}
+
+interface FieldValue {
+  source: string
+  value: string | number | undefined
+  confidence: number
+}
+
+function average(values: readonly number[]): number {
+  if (values.length === 0) return 0
+  return values.reduce((sum, value) => sum + value, 0) / values.length
+}
+
+function defaultPrintReferenceImageSample(): PrintReferenceImageSample {
+  return {
+    paper: '#FFFFFF',
+    ink: '#1A1A1A',
+    accent: '#46584B',
+    accentConfidence: 0.45,
+  }
+}
+
+function quantizeColor(value: number | undefined): number {
+  return Math.round((value ?? 0) / 24) * 24
+}
+
+function rgbToHex(rgb: readonly number[]): string {
+  return `#${rgb
+    .map(value =>
+      Math.max(0, Math.min(255, value)).toString(16).padStart(2, '0'),
+    )
+    .join('')}`
+}
+
+function colorLuminance([r, g, b]: readonly number[]): number {
+  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255
+}
+
+function colorSaturation([r, g, b]: readonly number[]): number {
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  return max === 0 ? 0 : (max - min) / max
+}