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

package/src/bridge/pureRender/extraction.ts

@@ -0,0 +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
+}