PR #144 (`31da384`, 2026-06-13) shipped a runtime
`ReferenceError: useFocusTrap is not defined` to production because
the component called the hook without importing it. The sibling
`enable-no-undef-eslint-rule` convoy closes that bug class at LINT
time. This PR locks the same regression at RENDER time so the bug
would still fail CI even if the lint rule were dropped or disabled.
## What changes
- `test/components/ScanDisambiguationDialog.test.js` — 8 tests:
1. `renders without crashing (PR #144 regression-lock)` — the
direct lock-in. Mutation-tested: commenting out the
`useFocusTrap` import causes all 8 tests to fail with the same
`ReferenceError` shape that hit prod.
2. `returns null when disambiguation is falsy`
3. ARIA shape (`role`, `aria-modal`, `aria-labelledby`)
4. One button per candidate with accessible labels
5. `onPick` callback receives the selected candidate
6. Vision-hint branch renders when provided
7. Submitting state disables the "send for review" button
8. `onCancel` callback fires on Cancel click
## Why vitest + jsdom and not Playwright smoke
| Path | Catches PR #144 | Setup | Runtime |
|------|-----------------|-------|---------|
| Playwright smoke | ✓ if disambiguation mounts in the smoke run | High (auth bypass, stable multi-candidate fixture image) | ~10s + browser |
| Vitest render | ✓ directly — render-throw → test fail | Low | <100ms |
Re-scoped the queued `scanner-disambiguation-smoke-test` task to the
vitest shape because a render test catches the exact same bug class
at 1/100th the cost and matches the existing `test/components/*.test.js`
pattern (`Modal.test.js`, `ScannedCardItem.test.js`, etc.). A Playwright
disambiguation smoke is still useful as integration-layer coverage and
is queued as `scanner-disambiguation-playwright-smoke`.
## Verification
- [x] `npm run test:run` — 26 files / 131 tests pass (up from 25/123)
- [x] Mutation test: with `useFocusTrap` import commented out, all 8
tests fail with `ReferenceError`. With import restored, all pass.
## Test plan
- [ ] CI on this PR green
- [ ] Squash + merge
- [ ] Smoke test post-merge: scan a card that triggers disambiguation
in prod and confirm no console errors (the original PR #144 bug
shape)
## Convoy doc
`.convoys/scanner-disambiguation-render-test.md` documents D1 (cover
the early-return branch explicitly), D2 (`fireEvent` not `userEvent`),
D3 (do NOT mock `useFocusTrap` — the missing-hook is exactly what
we're locking), and the two queued follow-ups
(`add-component-render-smoke-pattern`, `scanner-disambiguation-playwright-smoke`).
Co-authored-by: Cursor <cursoragent@cursor.com>
237870c17e