test(document-viewer): name the cause when render-ahead is never scheduled, and record the five unreproducible Windows failures

[BigSimmo]

Summary

• Record the finding. A full npm run test on a clean Windows workstation at cdfcbaccd exited 1 with four files / five tests failed. None reproduce on Linux. A new immutable outstanding-issues inbox request captures the evidence, the leads found by reading, and — deliberately — leaves the classification open rather than closing it as environmental.
• Make one of those failures legible.flushIdle() in tests/document-viewer-page-virtualization.dom.test.tsx is the shared failure point of two of the five, and all it could report was expected 0 to be greater than 0. It now throws with the budget explanation and the observable state at timeout. Assertions are unchanged.

What the investigation established

On Linux at HEAD, all five pass individually, and a full GATE_RECEIPTS=off npm run test is green: 696 files / 7770 tests passed, 4 skipped, exit 0 (196 s). The document-viewer pair also passed 3/3 consecutive runs under 3× CPU oversubscription, so ordinary load does not reproduce it.

git diff cdfcbaccd..HEAD shows none of the four test files, nor their subjects (scripts/check-hosted-migration-role.mjs, scripts/setup-codex-cloud.sh, supabase/**, src/components/document-viewer/**), changed between the reported SHA and HEAD. So the Linux green applies to cdfcbaccd itself, and the three intervening commits did not quietly fix these.

Two things worth not glossing over:

• Items 1 and 2 are not timing shapes.hosted-migration-role-guard › "accepts the current repository state" and codex-cloud-setup › "writes managed shell policy behaviorally" are deterministic state assertions. A Windows-only failure there is a real Windows-only defect, not load noise, and is not dismissed as environmental here. Closing them out needs the assertion text from that machine.
• The flake ledger does not apply to any of the five.tests/flake-ledger.json is explicitly Playwright-only (@quarantine title, exact spec match). All five failures are Vitest, so none are eligible for quarantine and none were added.

The flushIdle() change

The viewer schedules a render-ahead idle callback only while liveCanvasLimit > 1, and resolveLiveCanvasWindow collapses that to 1 whenever perCanvasPixels is 0 — which is what jsdom's zero-width layout measurement yields before contentWidth lands. The test's cancelIdleCallback stub is a no-op, so idleCallbacks only ever accumulates callbacks from earlier effect runs; if the first run measures a zero-width canvas, none is ever pushed and no amount of waiting produces one. That failure is indistinguishable from a slow machine, which is how it would be misfiled.

Verified both directions: the file still passes 9/9, and forcing the stub to drop callbacks produces the new message — 8 page slot(s), 1 rendered, 1 intersection observer(s) — which shows the viewer mounted and rastered the reader's page but scheduled nothing.

Verification

• npm run test — full offline suite, 696 passed (696) files, 7770 passed | 4 skipped (7774) tests, exit 0
• npm run typecheck — passed (4371 input files)
• npm run lint — passed (4371 input files)
• npm run format — clean; affected file reports (unchanged)
• npm run check:outstanding-issues — Ledger inbox check passed: 8 pending request(s), 485 applied; guard passed, 423 rows
• npx vitest run tests/document-viewer-page-virtualization.dom.test.tsx — Tests 9 passed (9), before and after the change
• Negative proof that the new diagnostic fires, by temporarily forcing the requestIdleCallback stub to drop callbacks

Verification not run: npm run verify:pr-local — its constituent gates for this scope (lint, typecheck, full unit suite, format) were each run directly and are listed above; the wrapper would only repeat them on unchanged content.

UI verification not run: the diff contains no production UI, routing, styling, or browser behaviour — the only source-tree change is a test helper's failure message.

Risk and rollout

• Risk: Very low. One test-helper failure message and one additive docs inbox record. No production code path, no schema, no dependency, no workflow change. The helper's success path is byte-for-byte unchanged; only the timeout branch is new, and it converts an opaque failure into a named one without altering what passes.
• Rollback: git revert either commit independently; they are separate and unrelated in effect.
• Provider or production effects: None.
• RAG impact: none

Notes

The five failures remain open and unclassified as to root cause. This PR does not claim to have fixed them — it records what is now known and makes two of them fail legibly if they recur. The decisive missing evidence is the assertion text from the Windows workstation:

npx vitest run tests/hosted-migration-role-guard.test.ts tests/codex-cloud-setup.test.ts

One lead worth checking first on that machine: validateRepository() grades untracked, non-ignored files, because repositoryEntries() runs git ls-files --cached --others --exclude-standard. Any stray file under scripts/, supabase/migrations/, .github/workflows/, or the guarded exact paths whose name or content matches the reserved role turns that test red while git status still looks clean enough to call the tree empty — as would a nested git worktree directory under the repo root, since readFileSync on a directory entry throws EISDIR. It also SHA-256s the on-disk bytes of the pinned immutable migration, so CRLF in the working tree would break it, though .gitattributes* text=auto eol=lf should prevent that and the bytes hash correctly on Linux.

Also worth correcting in any local notes: the previously known Windows-local failures (tests/session-start-hook.test.ts, worker-observability) passed in the reported run, so that "known environmental failures" note is stale.

Run npm run issues:reconcile from a serialized ledger branch after this lands.

---

Generated by Claude Code

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your current included review allowance is based on your included PR review attempts over the past 7 days.

Next review available in:48 minutes

Limit details: You’ve used the included review currently available. Your 88 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a6e96902-4671-4beb-a25d-14dce49dc257

📥 Commits

Reviewing files that changed from the base of the PR and between 1155041 and 8a1ab15.

📒 Files selected for processing (2)

• docs/outstanding-issues-inbox/67bf71cf-25cb-40d9-a8a2-bbf993bf6b29.json
• tests/document-viewer-page-virtualization.dom.test.tsx

---

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