fix: wait for images before photographing a story

[lemarier]

Change

node .storybook/verify.mjs could not tell whether a change had moved anything, because its screenshots moved on their own. Five of the six differed between two runs of the same build — buddy-welcome-320 by 4,528 pixels, which is the whole Buddy portrait present in one run and absent in the next.

The run waited for the document (waitUntil: "load") and for text (document.fonts.ready) but never for an image. Three separate causes had to be covered:

• A decode that had not finished, so the avatar was photographed part-drawn.
• Images in frames the outer page does not own. The manager preset shoots a story through an iframe and some stories embed the site through another, so waiting only on the top document left the avatar inside them still moving.
• A lazy image below the fold that never began loading while the page sat still. This is the one that produced a missing portrait rather than a half-drawn one, and it is why checking currentSrc first was not enough — an image that has not started looks the same as one with nothing to load.

So the wait now runs in every frame, promotes loading="lazy" to eager, waits for load or error, then decodes. Each image is raced against a five-second timeout so a broken asset cannot hold a run open; reporting a broken image stays the job of the asset check.

This is test infrastructure only. No product code changes.

Validation

just check passes (exit 0): lint, tests, type check, site build and Storybook build.

Stability, measured by running the verifier repeatedly against one unchanged build and comparing every screenshot to the first run:

	runs	comparisons	differing pixels
before	3	12	five of six files moved, up to 4,528
after	8	42	0

The fix settles on the correct state rather than a consistently wrong one: the portrait is present in the screenshots it now produces, which was checked by eye against the run where it was missing.

A run takes about ten seconds, and still reports 55 stories rendering with no page errors.

Two intermediate versions of this fix were measured and rejected as incomplete, which is how the frame and lazy-loading causes were found: waiting on the top document alone left storybook-phone-review and buddy-welcome-desktop moving, and adding frames left buddy-welcome-320 swinging by the full 4,528.

No Changeset: the site is not a published package.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: QUIET

Plan: Advanced

Run ID: d357c172-d57f-4265-b4ec-7e534eb27904

📥 Commits

Reviewing files that changed from the base of the PR and between ee95ff8 and a99c9ba.

📒 Files selected for processing (1)

• apps/website/.storybook/verify.mjs

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The screenshot verification flow adds imagesSettled. It makes lazy images eager, waits up to five seconds for loading, attempts image decoding, and continues after image or frame failures. screenshot calls this synchronization before capturing each page.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 1 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: the Storybook verifier now waits for images before capturing screenshots.
Description check	✅ Passed	The description directly explains the image synchronization changes, the causes of screenshot instability, validation results, and the test-infrastructure scope.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

---

_{Comment @coderabbitai help to get the list of available commands.}