### Install Dependencies

Source: https://github.com/sztheory/rendro/blob/main/examples/phoenix_example/README.md

Navigate to the example directory and fetch project dependencies.

```sh
cd examples/phoenix_example
mix deps.get
```

--------------------------------

### Show Code Example

Source: https://github.com/sztheory/rendro/blob/main/brand/copy/VOICE.md

Prefer a working snippet over an adjective to demonstrate capabilities. This example shows a composable pipeline returning a Rendro Document.

```Elixir
def render(document) do
  document
  |> Rendro.Layout.apply_styles()
  |> Rendro.Render.to_pdf()
end
```

--------------------------------

### Start Phoenix Server

Source: https://github.com/sztheory/rendro/blob/main/examples/phoenix_example/README.md

Boot the Phoenix development server.

```sh
mix phx.server
```

--------------------------------

### Schematic Application Example

Source: https://github.com/sztheory/rendro/blob/main/guides/integrations.md

A schematic example demonstrating fetching an invoice and rendering it using Rendro's Accrue adapter. This is schematic because fetch_invoice/1 is application-specific.

```elixir
invoice = MyApp.Billing.fetch_invoice!(invoice_id)

{:ok, doc} = Rendro.Adapters.Accrue.recipe(invoice)
{:ok, pdf}  = Rendro.render(doc)
```

--------------------------------

### Apply Branding to Document (Schematic)

Source: https://github.com/sztheory/rendro/blob/main/guides/branding.md

A schematic example showing how to apply branding by registering a font and an image to a document within a module.

```elixir
defmodule MyApp.Branding do
  def apply(doc) do
    doc
    |> Rendro.Document.register_embedded_font(:brand_heading, {:path, "/path/to/brand.ttf"})
    |> Rendro.Document.register_image(:company_logo, {:path, "/path/to/logo.png"})
  end
end
```

--------------------------------

### First Mention Rule Example

Source: https://github.com/sztheory/rendro/blob/main/prompts/Rendro Brand Book.txt

Demonstrates the correct way to introduce Rendro on public surfaces, emphasizing its Elixir-native nature.

```text
Rendro is an open-source, Elixir-native PDF layout library.
```

--------------------------------

### Detailed Error Message Example

Source: https://github.com/sztheory/rendro/blob/main/prompts/elixir-native-pdf-generation-oss-lib-deep-research.md

Provides a good example of detailed error messages for layout failures. Includes context like template, block path, and available vs. required space, suggesting solutions.

```text
Table overflowed page body frame.
Template: MyApp.PDF.Invoice
Block path: document/body/table[2]/row[47]/cell[3]
Available height: 18pt
Required height: 42pt
Try: reduce font size, allow row splitting, or set on_overflow: :new_page
```

--------------------------------

### Automatic Project Bootstrap Command

Source: https://github.com/sztheory/rendro/blob/main/prompts/rendro-gsd-seed.md

Use this command in a clean context window to automatically bootstrap a new Rendro project using the GSD seed file. This is the recommended approach for a streamlined setup.

```text
/clear
/gsd-new-project --auto @prompts/rendro-gsd-seed.md
```

--------------------------------

### Serve PDFs from Phoenix Controllers

Source: https://github.com/sztheory/rendro/blob/main/README.md

Integrate Rendro with Phoenix to serve generated PDFs. This schematic example shows how to create a document using a recipe and render it as a PDF using the Phoenix adapter.

```elixir-schematic
defmodule MyAppWeb.PDFController do
  use MyAppWeb, :controller
  alias Rendro.Adapters.Phoenix, as: RendroPhoenix

  def show(conn, _params) do
    data = %{
      id: "INV-001",
      date: Date.utc_today(),
      items: [%{name: "Consulting", qty: 1, price: 1_500}]
    }

    doc = Rendro.Recipes.Invoice.document(data)

    RendroPhoenix.render_pdf(conn, doc, "invoice.pdf")
  end
end
```

--------------------------------

### Elixir Code Block Example

Source: https://github.com/sztheory/rendro/blob/main/brand/index.html

Example of how to use the Rendro library in Elixir to generate a PDF document from invoice data. This snippet demonstrates chaining document generation methods and rendering the final PDF.

```elixir
invoice
  |> Rendro.Document.new(page_size: :a4)
  |> Rendro.heading("Invoice #{invoice.number}")
  |> Rendro.table(invoice.line_items, repeat_header: true)
  |> Rendro.render()  # => {:ok, pdf_binary}
```

--------------------------------

### Flow/Layout API Example

Source: https://github.com/sztheory/rendro/blob/main/prompts/elixir-native-pdf-generation-oss-lib-deep-research.md

Illustrates the flow/layout API for generating documents like reports and invoices. It handles content arrangement and automatic pagination.

```elixir
PDF.document(page_size: :a4, margin: 48)
|> PDF.heading("Invoice #{@invoice.number}")
|> PDF.paragraph("Bill to: #{@customer.name}")
|> PDF.table(@line_items, columns: Invoice.columns(), repeat_header: true)
|> PDF.render()
```

--------------------------------

### Background PDF Rendering with Oban

Source: https://github.com/sztheory/rendro/blob/main/prompts/elixir-native-pdf-generation-oss-lib-deep-research.md

This example demonstrates how to enqueue a PDF rendering job using Oban for background processing. It specifies the template, version, and relevant IDs for the rendering task.

```elixir
%{
  template: "invoice",
  template_version: "2026.04.24",
  invoice_id: invoice.id,
  requested_by_id: current_user.id
} |> MyApp.PDF.RenderWorker.new() |> Oban.insert()
```

--------------------------------

### Run All Normalized Track Comparators

Source: https://github.com/sztheory/rendro/blob/main/bench/comparison/README.md

Executes all defined comparators for the normalized track. Ensure all required tools are installed before running.

```bash
elixir bench/comparison/run.exs --track normalized --all
```

--------------------------------

### Fixed-Position API Example

Source: https://github.com/sztheory/rendro/blob/main/prompts/elixir-native-pdf-generation-oss-lib-deep-research.md

Demonstrates the fixed-position API for precise element placement, suitable for certificates or forms. Uses explicit coordinates and page dimensions.

```elixir
PDF.new(page_size: :letter)
|> PDF.page(fn page ->
  page
  |> PDF.text_at({72, 720}, "Certificate of Completion", font_size: 24)
  |> PDF.image_at("logo.png", {72, 650}, width: 120)
end)
```

--------------------------------

### Configure Rendro Policies

Source: https://github.com/sztheory/rendro/blob/main/README.md

Example of configuring policies for Rendro.flow, including maximum pages, bytes, and timeout. This is verified by the README compile/eval lane in `mix docs.contract`.

```elixir
# docs-contract: readme-policies-compile
_doc = Rendro.flow([], options: %{
  policies: [
    max_pages: 50,
    max_bytes: 1_000_000,
    timeout: 5_000
  ]
})
```

--------------------------------

### Example Release Announcement

Source: https://github.com/sztheory/rendro/blob/main/brand/copy/marketing-copy.md

Details the changes in Rendro v0.3.0, including added features like opt-in table styling and improved layout diagnostics, as well as changes and fixes. It also specifies the upgrade instruction.

```text
Rendro v0.3.0

This release adds opt-in table polish and improves layout diagnostics. No breaking changes.

**Added**
- Opt-in table `borders:`, `border_style:`, and `header_fill:` for deterministic table styling. Borderless defaults are unchanged.
- `Rendro.render_with_diagnostics/2` returns the laid-out document struct alongside the PDF for layout debugging.

**Changed**
- Layout overflow errors now include the region name and the available-vs-required heights.

**Fixed**
- Repeated table headers no longer drop the header fill on the second page.

Telemetry event names, the public break surface (`keep_together`, `keep_with_next`, `break_before`, `break_after`), and deterministic output are unchanged. Upgrade with `{:rendro, "~> 0.3"}`.
```

--------------------------------

### Elixir PDF Library Feature Set - Day 0

Source: https://github.com/sztheory/rendro/blob/main/prompts/elixir-native-pdf-generation-oss-lib-deep-research.md

Core adoption features for a new Elixir PDF library, including installation, generation of common document types, Phoenix integration examples, and essential documentation.

```elixir
mix pdf.install
mix pdf.gen.invoice
mix pdf.gen.report
mix pdf.gen.certificate
```

```elixir
# Phoenix controller examples.
# LiveView preview example.
# S3/storage examples.
# ExDoc guides, not just module docs.
# Copy-paste recipes for invoices, statements, labels, charts, and tables.
# Excellent errors for missing fonts/images, overflow, unsupported image formats, invalid colors, and invalid page sizes.
```

--------------------------------

### Print Runner Help

Source: https://github.com/sztheory/rendro/blob/main/bench/comparison/README.md

Displays the available options and commands for the benchmark runner.

```bash
elixir bench/comparison/run.exs --help
```

--------------------------------

### Create Evidence File

Source: https://github.com/sztheory/rendro/blob/main/guides/viewer_evidence.md

Copies a template to create a new viewer evidence file. The path should follow the pattern priv/viewer_evidence/<surface>/<viewer>.md.

```bash
cp priv/viewer_evidence/_template.md priv/viewer_evidence/<surface>/<viewer>.md
```

--------------------------------

### Prepare Form Fixture

Source: https://github.com/sztheory/rendro/blob/main/guides/viewer_evidence.md

Command to write a fixture file for forms. Ensure the fixture path exists and is committed before manual observation.

```bash
mix run -e 'Rendro.Test.FormSupportFixture.write_fixture("test/fixtures/forms_support_fixture.pdf")'
```

--------------------------------

### Attach Threadline Handler

Source: https://github.com/sztheory/rendro/blob/main/guides/integrations.md

Attach the Rendro Threadline adapter once at application start. This function is idempotent.

```elixir
defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    Rendro.Adapters.Threadline.attach()
    # ... supervise children
  end
end
```

--------------------------------

### Elixir Package Dependency

Source: https://github.com/sztheory/rendro/blob/main/prompts/Rendro Brand Book.txt

Example of how to include the Rendro Hex package in your Elixir project's dependencies.

```elixir
{:rendro, "> 0.1"}
```

--------------------------------

### Run Live PDF Tools Test

Source: https://github.com/sztheory/rendro/blob/main/guides/api_stability.md

Execute local tests for Rendro's live PDF tools, including signing and augmentation, using the provided mix test command. This ensures the functionality of the proof lane.

```bash
mix test --include live_pdf_tools test/rendro/adapters/signing_live_test.exs
```

--------------------------------

### Record Signing Preparation with Adobe Acrobat Reader

Source: https://github.com/sztheory/rendro/blob/main/guides/viewer_evidence.md

Use this command to record evidence for signing preparation support using Adobe Acrobat Reader via the automated path. Set matrix viewer_kind to "pdfium-cli".

```bash
mix rendro.viewer_evidence record signing_preparation adobe_acrobat_reader \
  --recorded-by ci:viewer-evidence-live-proof
```

--------------------------------

### Record Links Support with Apple Preview

Source: https://github.com/sztheory/rendro/blob/main/guides/viewer_evidence.md

Use this command to record evidence for link support using Apple Preview via the automated path. Ensure pdfium-cli is in your PATH.

```bash
mix rendro.viewer_evidence record links apple_preview \
  --fixture test/fixtures/embedded_artifact_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

--------------------------------

### Illustrative Deprecation Example

Source: https://github.com/sztheory/rendro/blob/main/guides/api_stability.md

This Elixir code demonstrates how a function can be soft-deprecated using the `@doc deprecated:` annotation, indicating a replacement and planned removal.

```elixir
@doc deprecated: "Use `Rendro.new_function/2` instead. This function will be removed in 2.0."
def old_function(doc, opts), do: new_function(doc, opts)
```

--------------------------------

### Regenerate Signing Preparation Fixture

Source: https://github.com/sztheory/rendro/blob/main/priv/viewer_evidence/signing_preparation/adobe_acrobat_reader.md

Use this command to regenerate the signing preparation fixture file. Ensure your environment is set to test mode.

```shell
MIX_ENV=test mix run -e 'Rendro.Test.SigningViewerSupportFixture.write_signing_preparation_fixture("test/fixtures/signing_preparation_support_fixture.pdf")'
```

--------------------------------

### Verify Failed Render with Threadline

Source: https://github.com/sztheory/rendro/blob/main/guides/integrations.md

Schematic example to verify a failed render scenario. It sets a policy that will cause a failure and asserts that Threadline recorded a :render_failed action.

```elixir
doc = Rendro.flow(
  [Rendro.block(Rendro.text("x", size: 12))],
  options: %{policies: [max_pages: 0]}
)
{:error, %Rendro.Error{reason: :max_pages_exceeded}} = Rendro.render(doc)

[action | _] = Threadline.list_actions()
assert action.action == :render_failed
```

--------------------------------

### Error Message: Unsupported Input

Source: https://github.com/sztheory/rendro/blob/main/brand/copy/VOICE.md

Example of an error message for attempting to render unsupported HTML/CSS input. It details the call, input type, and provides alternative solutions.

```text
Cannot render arbitrary HTML/CSS.
  Call:  Rendro.render/1
  Input: a string beginning with "<html>"
Rendro builds PDFs from document components, not from HTML or CSS.
Try one of: compose the document with Rendro.flow/2 and Rendro.block/2,
or use an HTML-to-PDF renderer when CSS fidelity is the goal.
```

--------------------------------

### Record Protection Support with Apple Preview

Source: https://github.com/sztheory/rendro/blob/main/guides/viewer_evidence.md

Use this command to record evidence for protection support using Apple Preview via the automated path. Ensure pdfium-cli is in your PATH.

```bash
mix rendro.viewer_evidence record protection apple_preview \
  --fixture test/fixtures/protection_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

--------------------------------

### Record Forms Support with Apple Preview

Source: https://github.com/sztheory/rendro/blob/main/guides/viewer_evidence.md

Use this command to record evidence for forms support using Apple Preview via the automated path. Ensure pdfium-cli is in your PATH.

```bash
mix rendro.viewer_evidence record forms apple_preview \
  --fixture test/fixtures/forms_support_fixture.pdf \
  --recorded-by ci:viewer-evidence-live-proof
```

--------------------------------

### Conditional Adapter Module Definition

Source: https://github.com/sztheory/rendro/blob/main/guides/integrations.md

This Elixir code defines an adapter module only if the specified library is loaded at compile time. This prevents errors when optional dependencies are not installed.

```elixir-schematic
if Code.ensure_loaded?(Threadline) do
  defmodule Rendro.Adapters.Threadline do
    def attach, do: :ok
  end
end
```

--------------------------------

### Record Signature Widget with Apple Preview

Source: https://github.com/sztheory/rendro/blob/main/guides/viewer_evidence.md

Use this command to record evidence for signature widget support using Apple Preview via the automated path. Set matrix viewer_kind to "pdfium-cli".

```bash
mix rendro.viewer_evidence record signature_widget apple_preview \
  --recorded-by ci:viewer-evidence-live-proof
```

--------------------------------

### Fallback Interactive Project Bootstrap Command

Source: https://github.com/sztheory/rendro/blob/main/prompts/rendro-gsd-seed.md

This command serves as a fallback for bootstrapping a new Rendro project interactively. If the automatic method fails or is not suitable, use this command and paste core sections from the seed file when prompted.

```text
/clear
/gsd-new-project
```

--------------------------------

### Run Normalized Benchmark

Source: https://github.com/sztheory/rendro/blob/main/guides/comparison.md

Execute the normalized benchmark from the repository root. This command builds Docker images for specific tools and records raw artifacts.

```bash
elixir bench/comparison/run.exs --track normalized --all
mix rendro.comparison.check
```

--------------------------------

### Compose a Document with the Builder API

Source: https://github.com/sztheory/rendro/blob/main/README.md

Use the pipeline builder API to compose documents by chaining functions that transform a %Rendro.Document{}. This example demonstrates adding a page template, setting it, and adding sections with content.

```elixir
import Rendro.Document

doc =
  Rendro.Document.new()
  |> add_template(
    Rendro.page_template(
      name: :report,
      regions: [
        Rendro.region(name: :header, role: :header, anchor: :top,   x: 24, y: 24,  width: 372, height: 24),
        Rendro.region(name: :body,   role: :body,   anchor: :flow,  x: 24, y: 72,  width: 372, height: 451),
        Rendro.region(name: :footer, role: :footer, anchor: :bottom, x: 24, y: 547, width: 372, height: 24)
      ]
    )
  )
  |> set_template(:report)
  |> add_section(Rendro.section(name: :heading, region: :header, content: [
    Rendro.block(Rendro.text("Account Statement", size: 14))
  ]))
  |> add_section(Rendro.section(name: :body_text, region: :body, content: [
    Rendro.block(Rendro.text("Summary paragraph here.", size: 12), width: 372)
  ]))
  |> add_section(Rendro.section(name: :footer_text, region: :footer, content: [
    Rendro.block(Rendro.text("Generated by Rendro", size: 10))
  ]))

{:ok, _pdf} = Rendro.render(doc)
```

--------------------------------

### Error Message: Row Overflow

Source: https://github.com/sztheory/rendro/blob/main/brand/copy/VOICE.md

Example of a detailed error message for a table row that could not fit. It specifies the template, region, block, available height, and required height, followed by an explanation and suggested fixes.

```text
Table row could not fit the remaining body space.
  Template: MyApp.PDF.Invoice
  Region:   :body
  Block:    document.body.table[2].row[47]
  Available height: 18pt
  Required height:  42pt
Rendro table rows are atomic and do not split across pages.
Try one of: start the row on a new page, reduce cell padding,
or shorten the cell content.
```

--------------------------------

### Record Viewer Evidence

Source: https://github.com/sztheory/rendro/blob/main/guides/viewer_evidence.md

Use this command to record new evidence for a viewer surface. Specify the surface, viewer, fixture path, and your identifier.

```bash
mix rendro.viewer_evidence record <surface> <viewer> \
  --fixture test/fixtures/<surface>_support_fixture.pdf \
  --recorded-by <your-identifier>
```

--------------------------------

### Generate PDF with Asserted Output using Doctest

Source: https://github.com/sztheory/rendro/blob/main/README.md

Demonstrates how to use Rendro's `fixed` API within an `iex` session to generate a PDF and assert its content. This is useful for testing and verifying PDF output.

```iex
iex> doc =
...>   Rendro.fixed([
...>     Rendro.page(blocks: [Rendro.block(Rendro.text("Receipt", size: 12), x: 36, y: 72)])
...>   ])
iex> {:ok, pdf} = Rendro.render(doc)
iex> binary_part(pdf, 0, 4)
"%PDF"
```