# Fix the visual regression agent timing out waiting for Thai font load

## TL;DR

Thai webfonts load slowly and the agent's font wait is too short, so wait for document fonts explicitly with a generous timeout. Screenshots taken before the font arrives show fallback rendering and false diffs. Use document.fonts.ready with a Thai specific wait, then screenshot.

## The error

```text
Visual regression agent: timeout waiting for font load, Thai text
screenshots show tofu or fallback glyphs
```

## Fix it

### Step 1: Confirm the font is the problem

```bash
node -e "console.log('screenshot shows boxes or wrong glyphs on Thai text only')"
```

Expected: The failure is font-specific.

### Step 2: Wait for fonts explicitly before screenshotting

```bash
node -e "console.log('await page.evaluate(() => document.fonts.ready), with a 30s timeout for Thai font subsets')"
```

Expected: The screenshot waits for the real glyphs.

### Step 3: Subset or preload the Thai font

```bash
node -e "console.log('preload the Thai unicode range so it arrives with the page, not after')"
```

Expected: The font is there earlier.

### Step 4: Re-run the visual checks

```bash
node scripts/visual-qa.js --locale th | tail -3
```

Expected: Thai screenshots render correctly.

## When to use this

- Visual regression times out or shows tofu on Thai text
- Font loading is slow for complex scripts

## When NOT to use this

- The font loads but shaping is wrong, check the shaper
- All languages show tofu, the font failed entirely

## Tool and version compatibility

- document.fonts.ready, webfont loading
- Thai script rendering

## Variant phrasings

### same issue with Arabic or Devanagari

Same fix. Complex scripts have big fonts that load late, wait explicitly.

### font loads but screenshots still flaky

Font display swap can change metrics mid-render. Wait for fonts.ready plus one frame.

## Why it happens

Thai needs a large glyph set that often ships as a separate subset loaded lazily. The agent screenshots on page load, before the subset arrives, capturing fallback glyphs that then diff against the correct baseline.

## Edge cases

- document.fonts.ready resolves when initial fonts load, late subsets need explicit waits
- Self-host the font, CDN latency is the usual killer
- Tofu in CI but not locally means the CI font cache is cold, warm it

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_H97b9X6S-UIKrzooPANjLw