feat(citation): add ≈ approximate-match marker and popover polish

[bensonwong]

Summary

• Adds a ≈ marker to citation highlights, keyhole strips, and drawer items when the model's inline display text (claimText) differs from the matched source text (sourceMatch) — surfaces approximate citation matches visually without hiding them
• Renames i18n key popover.displayedAs → popover.claimedAs and updates copy to "claimed as …" across all locales (en, es, fr, vi)
• Replaces amber ≈ hover effect in HighlightedSourceContext using a Tailwind group/anchor pattern so the marker dims at rest and turns amber on hover/focus
• Flattens claim block styles in markdownToHtml report shell: removes border-radius from cowork notice, removes border-radius + border-left primary color accent from the claim block (uses --dc-foreground instead), and drops the unused tier2Open progressive-disclosure flag
• Removes scroll-lock RAF logic from usePopoverPosition and EvidenceTray in favor of overscroll-behavior: contain
• Adds capture-snapshot.ts and template.ts to examples/basic-verification for one-shot snapshot capture and local re-render of verified output (debugging/dev aid); exports shared step helpers from shared.ts
• Removes 29 now-redundant usePopoverViewState unit tests that duplicated integration-level coverage

Test plan

• Open a citation whose claimText differs from sourceMatch — confirm ≈ appears beside the highlight in the popover and keyhole strip, and "claimed as …" annotation appears below
• Open a citation whose claimText equals sourceMatch — confirm no ≈ marker appears anywhere
• Hover/focus the highlight span — confirm ≈ turns amber; move away — confirm it returns to subtle
• Open a citation in the drawer — confirm ≈ and "claimed as …" appear in the drawer item footer when applicable
• Run markdownToHtml report output and confirm claim block has no rounded corners and uses foreground accent color
• Confirm all locales (es, fr, vi) show translated "claimed as" text instead of old "displayed as" copy
• Run npm test — all remaining tests pass

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

4 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
agui-chat-deepcitation	Ignored	Preview	Apr 15, 2026 6:46pm
deepcitation-langchain-rag-chat	Ignored	Preview	Apr 15, 2026 6:46pm
mastra-rag-deepcitation	Ignored	Preview	Apr 15, 2026 6:46pm
nextjs-ai-sdk-deepcitation	Ignored	Preview	Apr 15, 2026 6:46pm

[github-actions]

✅ Playwright Test Report

Status: Tests passed

📊 Download Report & Snapshots (see Artifacts section)

What's in the Visual Snapshots

The gallery includes visual snapshots for:

• 🖥️ Desktop showcase (all variants × all states)
• 📱 Mobile showcase (iPhone SE viewport)
• 📟 Tablet showcase (iPad viewport)
• 🔍 Popover states (verified, partial, not found)
• 🔗 URL citation variants

---

Run ID: 24472095998

[claude]

Code Review

Overall this is a clean, well-scoped PR. The approximate-match marker idea is solid, the Tailwind group/anchor pattern is idiomatic, and replacing the JS scroll-lock RAF with overscroll-behavior: contain is the right direction. A few things worth addressing before merge:

---

Bug: text-md is not a valid Tailwind class

src/react/DefaultPopoverContent.tsx, line ~599

<span aria-hidden="true" className="mr-1 text-amber-500 dark:text-amber-400 text-md">
  ≈
</span>

text-md is not a Tailwind utility — the correct class is text-base (or a specific size like text-sm). Without a valid size class the ≈ character will inherit the container font-size rather than the intended one. The same glyph in HighlightedSourceContext and CitationDrawer doesn't have this issue, so the inconsistency is only here.

---

Locale semantic mismatch

The English key was renamed from popover.displayedAs → popover.claimedAs and the copy changed from "(displayed as …)" to "claimed as …" — a meaningful semantic shift. The non-English overrides were updated to use the new key, but the translated strings still say "displayed as" (mostrado como / affiché comme / hiển thị là). That's inconsistent with the English intent. Either update the translations or leave a TODO comment so translators know a re-translation is needed.

---

overscroll-behavior: contain may not fully replace the scroll lock

The previous acquireScrollLock() prevented the body from scrolling while the popover was in expanded-page view. overscroll-behavior: contain only stops scroll chaining (momentum overflow) — it doesn't block body scroll when the popover content is shorter than its container and therefore not itself scrolling. On mobile Safari in particular, if the user swipes past the top/bottom of the popover content without triggering its own scroll, the body will still scroll. This may be acceptable given the complexity trade-off, but it should be called out in the test plan so QA knows to validate on real devices.

---

Missing API key guard in capture-snapshot.ts

const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY! });

The non-null assertion silences TypeScript but passes undefined to the constructor at runtime if the env var is absent. The script already validates the fixture path and PDF — add the same check here for consistency and a better DX:

const apiKey = process.env.DEEPCITATION_API_KEY;
if (!apiKey) {
  console.error("❌ DEEPCITATION_API_KEY is not set — add it to .env");
  process.exit(1);
}
const dc = new DeepCitation({ apiKey });

---

--md= path not existence-checked in template.ts

: readFileSync(resolve(mdOverride), "utf-8")

If the user passes a --md= path that doesn't exist, readFileSync throws a raw Node error rather than the styled fail() message used everywhere else. A quick guard keeps the UX consistent:

if (!existsSync(resolve(mdOverride))) fail(`--md file not found: ${mdOverride}`);

---

Hardcoded portal URL in shared.ts

const portalUrl = `https://deepcitation.com/verifications/${report.id}`;

If the API response already has a shareUrl field (it did before this change), constructing the URL from a hardcoded host breaks staging/dev environments. If the field was intentionally removed from the API response, fine — but worth a comment explaining why the URL is being built locally rather than reading it from the response.

---

Minor: isApproximate computed three times

!!claimText && !!sourceMatch && claimText !== sourceMatch appears independently in PopoverFallbackView, DefaultPopoverContent, and CitationDrawerItemComponent. The logic is trivial so this isn't a blocker, but it's the kind of thing that diverges when one site adds a trim/normalize step and the others don't. A shared one-liner helper (or computing it one level up and passing it down) would keep it DRY.

---

The scroll-lock removal and overscrollBehavior: contain placement in the popover inline style are otherwise clean. The group/anchor Tailwind pattern for the hover-amber effect is exactly right.