Canio, a different approach to Laravel PDF rendering: readiness contract instead of timing heuristics

I want to share an approach more than promote a project, because I'm curious what this community thinks of the tradeoff.

The problem: every HTML-to-PDF setup I've shipped on headless Chrome has the same failure mode. The renderer decides when to capture (network idle + an arbitrary delay), but only the application knows when the document is genuinely done, webfonts swapped in, Chart.js finished animating, async data painted. So you end up with waitUntilNetworkIdle() + delay(2000), it works locally, and then it flakes on a queue worker in production.

The approach I took in Canio: invert the control. The page declares readiness explicitly:

window.__CANIO_READY__ = true;

You set it whenever "done" is actually true for that document, after document.fonts.ready, after the chart's onComplete, after the fetch resolves, whatever applies. The runtime blocks on that signal with a timeout fallback. Capture becomes deterministic with respect to your app instead of the network.

The second piece, which I find more interesting than the readiness contract itself: every render can persist an artifact bundle, the exact HTML sent to Chrome, a DOM snapshot at capture time, a screenshot, the console log, and the network log. When someone reports "the invoice from three days ago looked wrong," you open the screenshot artifact and see exactly what Chrome saw, instead of trying to reproduce a nondeterministic render.

Under the hood it's a Go runtime over CDP (no Node dependency in the deploy), it ships its own pinned Chrome for Testing, MIT licensed, Laravel 10–13.

Repo: oxhq/canio (can't post links)

I still use and recommend Browsershot for simple static documents, this isn't a replacement pitch. Canio is for the cases where capture timing or production debuggability genuinely bite you.

Genuinely interested in pushback on the readiness-contract model. Is explicit readiness the right call, or do you prefer keeping the heuristic and tuning it? What breaks for you with HTML-to-PDF?