PDF Assets

sections:
  # ── Single page embed
  - type: image
    src: "Documents/certificate-of-compliance.pdf"
    mode: "embed"

  # ── Multi-page embed with all options
  - type: image
    src: "Documents/inspection-report.pdf"
    mode: "embed"
    pageRange: "1-3"
    extractDpi: 300
    extractQuality: 90
    width: 487
    columns: 3
    show_captions: true

PDF file
  → parse and extract page
  → render to PNG pixel buffer
  → compress PNG to JPEG at extractQuality
  → embed as base64 data URI in the PDF

sections:
  # ── Single standalone image
  - type: image
    src: "Media/Images/site-photo.jpg"
    caption: "Site overview"

  # ── Standalone image grid
  - type: image_grid
    images:
      - src: "Media/Images/before.jpg"
        caption: "Before"
      - src: "Media/Images/after.jpg"
        caption: "After"
    columns: 2

sections:
  # ── Minimal append
  - type: pdf_appendix
    src: "Attachments/warranty-terms.pdf"

  # ── Full options
  - type: pdf_appendix
    src: "Documentation/safety-manual.pdf"
    library: assets
    title: "Appendix B: Safety Procedures"
    pageNumbers: true

PDF file
  → download or read from assets
  → validate PDF structure
  → store buffer and metadata
  → after main PDF is generated: merge pages into output

// pdfPreprocessor.ts, _resolveStandaloneImageSrc (standalone image/image_grid cell):
const library = typeof target.library === 'string' && target.library.trim() !== '' ? target.library : undefined;
const ref: AnnexImageRef = {
  url:     src,
  caption: typeof target.caption === 'string' ? target.caption : undefined,
  library,
};

// pdfAssetHelper.ts, resolvePdfForAppend (pdf_appendix):
// block.library (a required field on PdfAppendixBlock, documented since [before]) called
// with library omitted, silently defaulting to 'assets' regardless.
const library = typeof block.library === 'string' && block.library.trim() !== '' ? block.library : 'assets';

// annexImageHelper.ts
export type FetchFailureCategory = 'author' | 'environmental';

export function _classifyAssetFailure(library: string, filePath: string, err: unknown): ClassifiedFetchFailure {
  ...
  if (LIBRARY_NOT_CONFIGURED_RE.test(rawMessage)) {
    return {
      category: 'author',
      message:  `Asset library '${library}' is not configured in this environment. Check the 'library' value on this image (path: '${filePath}').`,
    };
  }
  if (statusCode === 404) {
    return {
      category: 'author',
      message:  `Asset not found: '${filePath}' in library '${library}' (HTTP 404). Check the path and library name.`,
    };
  }
  if (statusCode === 401 || statusCode === 403) {
    return {
      category: 'environmental',
      message:  `Access denied fetching '${filePath}' from library '${library}' (HTTP ${statusCode}). This may be a permissions issue in the storage backend, or an incorrect path/library treated as unauthorized.`,
    };
  }
  ...
}

// structuredContentRenderer.ts, case 'image':
case 'image': {
  if (block.src && !block.data && block._authorFaultError) {
    throw new Error(`[StructuredContent] image block failed to resolve: ${block._authorFaultError}`);
  }
  return renderImageBlock(block, theme);
}

// structuredContentRenderer.ts, case 'pdf_appendix' (environmental branch):
if (appendix.failureReason) {
  return [{
    stack: [
      { text: '[Attachment unavailable]', ... },
      { text: appendix.failureReason, ... },
    ],
  } as unknown as Content];
}

// supplementaryAnnexRenderer.ts doc comment on AnnexImageRef.failureCategory:
// A caller that wants an author-fault failure to fail the whole render reads this back --
// see processAnnexImage's own doc comment for the full mechanism and why the annex path
// (this file) does not do that.

{
  "Lines": [
    {
      "No.": "A101",
      "Description": "Foundation Inspection",
      "notes": ["Concrete poured on 2025-11-15"],
      "images": [
        "Media/Images/foundation-photo.jpg",
        "Documents/Reports/soil-test-report.pdf",
        "https://storage.example.com/photos/rebar-layout.png"
      ]
    }
  ]
}

- type: image_grid
  source: "{{item.images}}"
  columns: 2
  target_dpi: 150        # controls PDF render resolution too
  image_quality: 80      # controls PDF JPEG quality too
  show_captions: true
  caption: "Documentation - Item {{item.id}}"

{
  "id": "supplementary-annex",
  "type": "structured_content",
  "props": {
    "assetPath": "Documents/SupplementaryAnnex/supplementary-annex-layout.yaml",
    "library": "assets"
  },
  "pagination": { "breakBefore": "always" }
}

# ── Supplementary Annex Layout
#
# Per-line-item supporting documentation section.
# Renders a themed header, notes, and photo grid for every qualifying item.
#
# Supports JPEG, PNG, GIF, WebP, SVG images AND .pdf files in the images array.
# PDF files are auto-detected and the first page is extracted as a JPEG thumbnail.

documentType: supplementary-annex
version: "1.0.0"
title: Supporting Documentation

sections:

  - type: supplementary_Annex

    # ── Data source
    # Top-level key in the payload containing the array of line items.
    data_source: "{{Lines}}"

    # ── Field bindings
    notes_field:  notes
    images_field: images
    id_field:     "No."
    name_field:   Description

    # ── Layout options
    showDivider: false
    includeInToc: true
    sectionNumbering: true

    # ── Per-item layout
    item_template:

      # Themed header bar
      - type: sub_header
        text: "Item {{item.id}} - {{item.name}}"
        subtitle: "Document {{Header.No.}} | Date {{Header.Order Date|date}}"
        style: variant_blue_bar

      # One paragraph per note
      - type: repeat_notes
        source: "{{item.notes}}"
        style: paragraph_block

      # Photo grid (2 columns, 150 DPI)
      # PDF files in the images array are auto-detected and rendered as thumbnails.
      - type: image_grid
        source: "{{item.images}}"
        columns: 2
        target_dpi: 150
        image_quality: 80
        show_captions: true
        caption: "Documentation photo - Item {{item.id}}"

{
  "features": {
    "supplementaryAnnex": true
  },
  "Header": {
    "No.": "SO-2025-001",
    "Order Date": "2025-11-15T00:00:00"
  },
  "Lines": [
    {
      "No.": "A101",
      "Description": "Foundation Repair - Push Piers",
      "notes": [
        "Installed 8 push piers to 22 ft depth.",
        "Load test passed at 35,000 lbs per pier."
      ],
      "images": [
        "Media/Images/push-pier-install.jpg",
        "Documents/Reports/soil-test-report.pdf",
        "Media/Images/load-test-gauge.png"
      ]
    },
    {
      "No.": "B205",
      "Description": "Crawlspace Encapsulation",
      "notes": [
        "20-mil vapor barrier installed across full crawlspace."
      ],
      "images": [
        "Media/Images/crawlspace-before.jpg",
        "Media/Images/crawlspace-after.jpg"
      ]
    }
  ]
}

{
  "id": "certificate-section",
  "type": "structured_content",
  "props": {
    "assetPath": "Documents/certificate-layout.yaml",
    "library": "assets"
  }
}

documentType: certificate-embed
version: "1.0.0"
title: Certificates

sections:
  - type: heading
    level: 2
    text: "Certificate of Compliance"

  - type: paragraph
    text: "The following certificate was issued upon completion of the project."

  # Embed first page of the PDF as an inline image
  - type: image
    src: "Documents/Certificates/compliance-cert.pdf"
    mode: "embed"
    pageRange: "1"
    extractDpi: 200
    extractQuality: 85

documentType: inspection-gallery
version: "1.0.0"
title: Inspection Report Pages

sections:
  - type: heading
    level: 2
    text: "Inspection Report"

  # Extract pages 1 - 4 and display as a 2×2 grid
  - type: image
    src: "Documents/Reports/full-inspection-report.pdf"
    mode: "embed"
    pageRange: "1-4"
    extractDpi: 150
    extractQuality: 80
    columns: 2
    show_captions: true

{
  "id": "appendix-safety",
  "type": "structured_content",
  "props": {
    "assetPath": "Documents/appendix-layout.yaml",
    "library": "assets"
  },
  "pagination": { "breakBefore": "always" }
}

documentType: appendix-collection
version: "1.0.0"
title: Appendices

sections:
  # Append the safety manual as native PDF pages
  - type: pdf_appendix
    src: "Documentation/safety-manual.pdf"
    library: assets
    title: "Appendix A: Safety Procedures"
    pageNumbers: true

  # Append warranty terms (no title page, no page numbers)
  - type: pdf_appendix
    src: "Attachments/warranty-terms.pdf"

documentType: complete-project-report
version: "1.0.0"
title: Project Completion Report

sections:
  # ── Standard content
  - type: heading
    level: 1
    text: "Project Summary"

  - type: paragraph
    text: "This report documents the completion of project {{Header.No.}}."

  # ── Inline PDF embed
  - type: heading
    level: 2
    text: "Engineer's Certificate"

  - type: image
    src: "Documents/engineer-certificate.pdf"
    mode: "embed"
    pageRange: "1"
    extractDpi: 200
    extractQuality: 85

  # ── Supplementary annex
  - type: supplementary_Annex
    data_source: "{{Lines}}"
    notes_field: notes
    images_field: images
    id_field: "No."
    name_field: Description
    showDivider: false
    includeInToc: true
    sectionNumbering: true
    item_template:
      - type: sub_header
        text: "Item {{item.id}} - {{item.name}}"
        style: variant_blue_bar
      - type: repeat_notes
        source: "{{item.notes}}"
        style: paragraph_block
      - type: image_grid
        source: "{{item.images}}"
        columns: 2
        target_dpi: 150
        image_quality: 80
        show_captions: true

  # ── Full PDF appendix
  - type: pdf_appendix
    src: "Documentation/safety-manual.pdf"
    title: "Appendix: Safety Manual"
    pageNumbers: true

{
  "features": {
    "supplementaryAnnex": true
  }
}

{
  "templateSettings": {
    "supplementaryAnnex": {
      "enabled": true
    }
  }
}