Export a PDF with cross-origin images

Check result.warnings first

The capture you hold already knows what it could not read. The PDF pages are drawn from that capture, so a grey box in the result is a grey box in the PDF. Log the warnings before you export:

import { snapdom } from '@zumer/snapdom'
import { pdf } from '@zumer/snapdom-pdf'

const result = await snapdom(document.querySelector('#report'), { plugins: [pdf()] })
for (const w of result.warnings) console.log(w.code, w.message)
// image-fallback  image failed to inline, using placeholder: https://cdn.example.com/avatars/42.png

const blob = await result.toPdf({ page: 'a4' })

Each entry includes code and message, and debug: true prints the same lines to the console. Keep placeholders on while you look: with placeholders: false the box stays empty and nothing is recorded. A CSS background or an SVG <image> the capture cannot read is dropped without a warning.

Your own CSP: connect-src, not img-src

SnapDOM reads every image it embeds with fetch(), and a Content Security Policy governs that read through connect-src. img-src only decides what the page may display. A policy that lists your CDN under img-src and not under connect-src shows the avatars on the page and exports grey boxes, with no CORS problem anywhere. The same rule covers the proxy origin from the section below, and the stylesheet and font hosts when fonts are embedded (embedFonts, 'auto' by default, fetches the webfonts the element uses).

Content-Security-Policy:
  img-src 'self' https://cdn.example.com;
  connect-src 'self' https://cdn.example.com https://image-proxy.example.com https://fonts.googleapis.com https://fonts.gstatic.com

List the hosts. connect-src * makes the images load, and it also lets any script on the page talk to any server, which is what the policy was there to prevent.

Fix it at the source

If you control the image server, add the header to the image responses and nothing else changes, in your code or in the export. Your own origin needs nothing: a same-origin image is read directly, cookies included.

Access-Control-Allow-Origin: *

A proxy for hosts you do not control

When the images come from a server you cannot change, put a proxy of your own in between that fetches them and adds the header. The CORS guide includes an image proxy, a Cloudflare Worker with a host allowlist; any server that adds the header does the same job. Then hand it to the capture:

const PROXY = 'https://image-proxy.example.com/?url='

const result = await snapdom(report, {
  plugins: [pdf()],
  // only the <img> the capture could not read, fetched again through the proxy
  fallbackURL: ({ src }) => PROXY + encodeURIComponent(src)
})
const blob = await result.toPdf({ page: 'a4' })

fallbackURL is called only for an <img> SnapDOM could not read. useProxy: PROXY instead sends every cross-origin request through the proxy: images that already allow CORS, CSS backgrounds, SVG <image>, stylesheets and font files. Use it when the missing images are backgrounds or SVG <image>, which fallbackURL does not cover, and let the proxy accept your font hosts too. It takes a base ending in ?url= or /, or a template with {url}; any other base gets ?url= appended.

Both are capture options: set them on snapdom(), not on toPdf(). The pages come from that capture, and the elements the export captures on its own (an element header or footer, a watermark element, cover and back pages) get the same useProxy, fallbackURL, placeholders and exclude. Add the proxy origin to connect-src, and note that the proxied request carries no cookies: the proxy has to fetch the image on its own.

Large PDFs

Each image URL is fetched once per capture: identical requests in flight share one response, a failure is remembered for eight seconds so a broken URL is not retried per node, and the data URL stays in a cache that later captures reuse. Images are fetched six at a time and each request has 3000 ms. A proxy that answers in two seconds adds about two seconds per six uncached images; one that does not answer in time gives a placeholder and an image-fallback warning, the same as a CORS failure. Give the proxy a cache (the Worker in the CORS guide sets cache-control: public, max-age=86400), and when result.warnings is not empty, show the warnings before you offer the download.