dieter-medium/bidi2pdf/pdf-recipe

Write and run a bidi2pdf recipe

A recipe is a rendering contract: the steps a page needs before it is printed, and what the PDF must be like afterwards. It is not a general automation script. The source of truth for its shape is bidi2pdf schema recipe; read it once before writing one.

Does not: log in through forms, follow links across pages, or extract data. One page, prepared and printed. For a plain page without steps, render is enough (the render-pdf skill).

Ground rules

• bidi2pdf is the renderer. If it fails, report its error.code, error.hint and exit code;

never make the PDF or screenshot another way (Chrome's own print-to-PDF, another PDF engine).

• Install nothing unasked. Name what is missing and suggest a way (the render-pdf skill's

preflight); run nothing that changes the system without the user's yes.

• bidi2pdf's results first. Read its --json result instead of inspecting the PDF with other

tools.

1. Write it

version: 1
source:
  url: https://example.com/invoice/123
actions:
  - wait_for:
      selector: "#invoice"
      timeout: 10
  - click:
      selector: "#show-details"
  - wait_network_idle:
      timeout: 10
assert:
  - selector_exists:
      selector: "#total"
  - no_console_errors: true
  - page_count: 2
  - pdf_text_present:
      text: "Invoice #123"
output:
  pdf: invoice.pdf
  manifest: invoice.manifest.json

• source: exactly one of url, file, stdin.
• actions run in order, after the page has loaded:
• wait_for takes exactly one of selector, paged_js: true (a Paged.js page exists) or script

(a JS expression that becomes truthy), plus an optional timeout (default 10 s).

• click, evaluate (a script, optionally assign: its result), inject_script/inject_style

(content: or url:).

• set_viewport (width, height, optional device_pixel_ratio).
• wait_network_idle (timeout).
• emulate_media (media: screen|print, color_scheme: light|dark, reduced_motion) - from the

0.1.23 or later.

• assert runs after printing. Page checks: selector_exists, text_present,

no_console_errors, no_network_failures, fonts_loaded. PDF checks: page_count, pdf_text_present, pdf_not_blank - these need the pdf-reader gem.

• output needs at least one of pdf, manifest, screenshot.

Two rules people trip over:

• no_console_errors, no_network_failures, fonts_loaded and pdf_not_blank are presence-only:

write them as true. false is rejected - leave the assertion out instead.

• no_network_failures fails on any failed request, a missing favicon or a 404 image included.

Check bidi2pdf diagnose --json first and fix the page, or leave that assertion out.

2. Validate without a browser

bidi2pdf run invoice.yml --validate --json

This checks the shape, every action and assertion name and every value, and that pdf-reader is there when a PDF assertion needs it - no browser starts. Iterate until ok is true; on failure error.details.path names the step (assert[0].no_console_errors).

3. Run it

bidi2pdf run invoice.yml --json --remote-browser-url http://chrome:3000/session

The result lists every action and assertion with its own ok. A failed step stops the run with error.code PAGE_NOT_AS_EXPECTED (or SELECTOR_NOT_FOUND for a wait_for that never matched), exit code 4, and error.details says which check failed and why (for no_network_failures the failed requests). Exit 2 is a recipe the validator refused; exit 3 is the browser or the page not loading. --json-stream reports progress on stderr while it runs.