feat: add multi-fact supporting facts citation support

[bensonwong]

Summary

• Adds hierarchical parent-child citation model for compound claims (e.g., legal court orders with multiple verifiable facts)
• Supporting facts render as chip pills inside the parent citation popover, each with independent verification status
• Parent badge reflects worst-child-wins status (isMiss > isPending > isPartialMatch > isVerified)
• Zero server changes — children are flattened client-side before verification API call, then reassembled
• Includes parser support for LLM-emitted children array (compact key c), prompt additions, and i18n (en, es, fr, vi)

Key design decisions

• SupportingFactsPills.tsx extracted to break circular dependency (Citation → DefaultPopoverContent → Citation)
• parentInstanceId prop suppresses announceActivePopover pub/sub so parent stays open when child popover opens
• Child citation keys: sha1(parentKey + "|child|" + childIndex).slice(0, 16) — deterministic, collision-resistant
• Nested children defense: parser strips children from child objects to prevent garbage propagation

New public API exports

• SupportingFact type, getChildCitationKey(), childCitationFromFact()
• expandSupportingFactsForVerification(), getSupportingFactVerifications(), ParentChildKeyMap
• computeCompositeStatus()

Test plan

• 2577 tests passing across 100 files (including 30 new tests for supporting facts)
• Build clean, lint clean (0 errors)
• Manual browser verification: child popover portals, Esc closes child first, status dots
• Cross-page and cross-document supporting facts scenarios
• Integration with consuming app (Phase 5 — documented separately)

[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	May 4, 2026 5:08am
deepcitation-langchain-rag-chat	Ignored	Preview	May 4, 2026 5:08am
mastra-rag-deepcitation	Ignored	Preview	May 4, 2026 5:08am
nextjs-ai-sdk-deepcitation	Ignored	Preview	May 4, 2026 5:08am

[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: 25302116090

[claude]

Code Review — PR #449: Multi-fact supporting facts citation support

Great feature addition overall. The architecture is well thought out — zero server changes, clean circular-dependency break via SupportingFactsPills.tsx, and solid test coverage for the core logic. Below are issues worth addressing before merge.

---

Bugs / Correctness

1. computeCompositeStatus — semantically confusing return for partial match

src/utils/worstChildStatus.ts:1311:

if (hasPartial) return { isVerified: true, isMiss: false, isPartialMatch: true, isPending: false };

The PR description says the priority is isMiss > isPending > isPartialMatch > isVerified, implying these are mutually exclusive states. But this return has isVerified: true alongside isPartialMatch: true. The test confirms this is intentional, but the JSDoc comment should explicitly state that isPartialMatch can co-exist with isVerified: true — otherwise maintainers will be surprised. Consider aligning the comment with the actual semantics: "partial match is a sub-state of verified."

2. childCitationFromFact — unsafe as Citation cast

src/utils/supportingFactExpansion.ts:1279:

} as Citation;

The spread of parentWithoutChildren followed by overrides may not satisfy all discriminated union constraints on Citation (e.g., AudioVideoCitation requires timestamps). If the parent is an AV citation, the child loses timestamps, creating an invalid state at the type level that the cast suppresses. Either add explicit handling for AV parents or add a runtime guard.

3. AV citations silently receive supportingFacts

src/parsing/citationParser.ts:669:

...(supportingFacts && { supportingFacts }),
} as AudioVideoCitation;

The as AudioVideoCitation cast hides that AudioVideoCitation may not have supportingFacts in its type. Does AudioVideoCitation actually support the multi-fact pattern? If not, drop the spread for the AV branch. If it does, AudioVideoCitation should extend CitationBase which already has supportingFacts? — verify the type hierarchy is correct here.

4. childIndex / array-position coupling is fragile

src/utils/supportingFactExpansion.ts and src/react/SupportingFactsPills.tsx both assume supportingFacts[i].childIndex === i. This holds today because mapChildrenToSupportingFacts sets childIndex from the map index. But getSupportingFactVerifications returns results indexed by array position, and SupportingFactsPills looks them up via supportingFactVerifications?.[fact.childIndex]. If supportingFacts is ever reordered by a consumer (sort, filter), verification lookups will silently misalign. Consider making this invariant explicit — either add an assertion in expandSupportingFactsForVerification or document it prominently on SupportingFact.childIndex.

---

Performance

5. SupportingFactsPills is not memoized

src/react/SupportingFactsPills.tsx — the component is un-memoized but its parent DefaultPopoverContent re-renders on every popover state change (blink, scroll, etc.). Each re-render of SupportingFactsPills also creates new childCitationFromFact(fact, parentCitation) objects inline, which defeats any memoization in child CitationComponent. Wrap in memo and memoize the citation objects:

export const SupportingFactsPills = memo(function SupportingFactsPills({ ... }) {
  const childCitations = useMemo(
    () => supportingFacts.map(fact => childCitationFromFact(fact, parentCitation)),
    [supportingFacts, parentCitation],
  );
  // ...
});

---

Naming / API Clarity

6. parentInstanceId vs parentCitationInstanceId inconsistency

• CitationComponent prop: parentInstanceId
• DefaultPopoverContent + SupportingFactsPills props: parentCitationInstanceId

These refer to the same value but have different names across 3 files. Pick one and use it consistently. Given the existing prop is on the public CitationComponentProps interface, parentInstanceId is the better canonical name.

7. "Recursively" comment in expandCompactKeys is misleading

src/parsing/citationParser.ts:612:

// Recursively expand children array — each child uses the same compact keys

This is only one level deep by design (children of children are stripped). The comment should say "one-level expansion" or "shallow expansion" to avoid maintainers expecting full recursion.

---

Test Gaps

8. No component tests for SupportingFactsPills.tsx

The PR adds 30 new unit tests for utility functions but nothing tests the rendered pills: that child CitationComponents receive the right parentInstanceId, that verification is looked up by childIndex, or that the aria-label renders correctly. Given the naming discrepancy above (point 6), a component test would catch that kind of wiring error.

9. Missing edge case: computeCompositeStatus with partial parent + all-verified children

computeCompositeStatus({ status: "found_source_match_only" }, [{ status: "found" }])

Should return isPartialMatch: true. This combination (partial parent, verified children) is not covered — the existing partial test only has the partial in a child.

---

Minor

• src/parsing/citationParser.ts:612: The check (KEY_ALIAS_MAP[key] || COMPACT_KEY_MAP[key] || key) === "children" duplicates logic already in normalizeKeyValue. A small cleanup: call normalizeKeyValue(key, value)?.fullKey === "children" instead.
• src/react/DefaultPopoverContent.tsx:1027: const parentKey = useMemo(() => getCitationKey(citation), [citation]) — getCitationKey on a stable citation object is already cheap (sha1 of a small string). The useMemo adds more overhead than it saves. Consider dropping it.
• The 3-level prop drilling of parentCitationInstanceId through Citation → PopoverContentRenderer → DefaultPopoverContent → SupportingFactsPills is acceptable but worth a short comment explaining why a context wasn't used (to avoid coupling child pills to a context they shouldn't need to know about).

---

Summary

Category	Status
Architecture	✅ Clean, well-scoped
Type safety	⚠️ Two as casts hide potential issues (AV + childCitationFromFact)
Correctness	⚠️ childIndex/array-position coupling needs documentation or a guard
Performance	⚠️ SupportingFactsPills needs memo
Naming	⚠️ parentInstanceId inconsistency across 3 files
Tests	⚠️ No component tests; 2 missing unit cases
i18n	✅ All 4 locales covered
Security	✅ isSafeKey + createSafeObject + nested children stripping all correct

The core logic is sound. Addressing the memo gap, the naming inconsistency, and the as Citation cast are the highest-priority items before merge.