feat: add capture date display and user goals documentation

[bensonwong]

Summary

• Add temporal context to citation UX: show "Verified [date]" for document citations and "Retrieved [date+time]" for URL citations in popovers and the citation drawer
• Document the progressive disclosure user goals in AGENTS.md to guide future UX decisions
• Add formatCaptureDate utility and register it in CLAUDE.md canonical locations

Changes

Capture Date Display (src/react/dateUtils.ts, CitationComponent.tsx, CitationDrawer.tsx)

• New formatCaptureDate() utility using Intl.DateTimeFormat — same-year dates omit the year, URL citations include time, tooltip provides full ISO 8601 for audit hover
• CaptureTimestamp sub-component inserted into all three popover states (success, partial/miss, fallback) between the proof image and verification log
• Citation drawer shows "Retrieved [date]" for URL citations with crawledAt

User Goals Documentation (AGENTS.md)

Documents WHY users interact with citations at each progressive disclosure level:

• Level 0 (inline indicator): "Is this real?"
• Level 1 (popover): source attribution, temporal validity, visual proof, quote reuse
• Level 2 (verification log): audit trail
• Level 3 (image overlay): deep verification
• Level 4 (drawer): holistic source review
• Temporal context design rules for URL vs document citations

Tests (src/__tests__/dateUtils.test.ts, CaptureTimestamp.test.tsx)

• 18 unit tests for formatCaptureDate: null/invalid handling, year logic, showTime, edge cases (leap day, future dates, 1970, date-only strings)
• 6 component tests for CaptureTimestamp: asserts rendered DOM content via popover interaction — verifies labels, date format, title attributes, crawledAt preference

Test plan

• bun test — 1052 tests pass (0 failures)
• npm run build — ESM, CJS, DTS, CSS all succeed
• npm run size — ~340 bytes added to react bundle (pre-existing size limit overage, not caused by this PR)
• npm run test:ct — Playwright snapshot tests (expect diffs on popovers with date fields in verification fixtures)

[claude]

Code Review: Capture Date Display Feature

Overall Assessment

✅ High quality implementation with excellent documentation, comprehensive test coverage, and thoughtful UX design. The code follows the project's conventions and the progressive disclosure documentation in AGENTS.md is particularly valuable.

---

Strengths

1. Excellent Documentation

• The AGENTS.md additions provide clear user-centered design rationale
• Progressive disclosure levels are well-articulated with specific user questions each level answers
• Temporal context design rules are explicit and justified

2. Comprehensive Test Coverage

• 18 unit tests for formatCaptureDate: covers null handling, year logic, time display, edge cases
• 6 component tests for CaptureTimestamp: verifies DOM rendering, labels, date formats, title attributes
• Edge cases well covered: leap days, future dates, old dates (1970), date-only strings

3. Type Safety

• Proper TypeScript usage with union types (Date | string | null | undefined)
• Graceful null handling throughout
• Return type { display: string; tooltip: string } | null is clear and predictable

4. Clean Code Structure

• formatCaptureDate has single responsibility
• CaptureTimestamp component is simple and focused
• Integration points are consistent across popover states

---

Issues & Recommendations

🔴 Critical: Inconsistent Date Type Handling

Location: src/types/verification.ts:89 and src/types/verification.ts:124

verifiedAt?: Date;           // Line 89
crawledAt?: Date | string | null;  // Line 124

Problem: verifiedAt only accepts Date, while crawledAt accepts Date | string | null. This inconsistency is confusing:

• Why does verifiedAt not accept strings when formatCaptureDate handles both?
• The component code treats them identically, suggesting they should have the same type

Impact:

• Potential runtime errors if API returns ISO strings for verifiedAt
• Code assumes verifiedAt can be a string (see formatCaptureDate usage)
• Type checking may miss bugs

Recommendation:

// Make types consistent
verifiedAt?: Date | string | null;
crawledAt?: Date | string | null;

Or add a comment explaining why they differ.

---

🟡 Minor: Hardcoded Locale

Location: src/react/dateUtils.ts:27, src/react/dateUtils.ts:30

new Intl.DateTimeFormat("en-US", dateFormatOptions).format(parsed);

Issue: Hardcoded "en-US" locale means international users see dates in American format regardless of their locale.

Recommendation:

// Use browser locale for date formatting
new Intl.DateTimeFormat(undefined, dateFormatOptions).format(parsed);
// or
new Intl.DateTimeFormat(navigator.language, dateFormatOptions).format(parsed);

Trade-off: Using user locale may make snapshots less stable, but improves UX for international users.

---

🟡 Minor: Missing Test for Timezone Edge Cases

Location: src/__tests__/dateUtils.test.ts

Missing coverage:

• No tests verify that display uses local timezone while tooltip uses UTC
• No tests for dates near daylight saving time transitions
• No tests with different TZ environment variables

Recommendation:

it("display uses local timezone, tooltip uses UTC", () => {
  const result = formatCaptureDate("2026-01-15T23:30:00Z");
  expect(result\!.tooltip).toContain("23:30"); // UTC time preserved
  // Display time depends on TZ, but we can verify it's formatted
  expect(result\!.display).toMatch(/Jan\s+(15|16)/); // Could be 15 or 16 depending on TZ
});

---

🟢 Nitpick: Component Placement Consistency

Location: src/react/CitationComponent.tsx:1148, 1229, 1293

The CaptureTimestamp component is placed in three different states (success, partial/miss, fallback). While this is correct, the fallback state (line 1293) places it after the page number, while the other two place it after the proof image.

Current structure:

• Success: [Image] → [Timestamp] → [VerificationLog]
• Partial/Miss: [Content] → [Timestamp] → [VerificationLog]
• Fallback: [Header] → [PageNumber] → [Timestamp]

This is probably fine since fallback has no image, but worth noting for future consistency.

---

🟢 Nitpick: Test Timeout Magic Number

Location: src/__tests__/CaptureTimestamp.test.tsx:22

await new Promise((r) => setTimeout(r, 50));

Consider extracting this to a named constant:

const POPOVER_SETTLE_TIME_MS = 50;
await new Promise((r) => setTimeout(r, POPOVER_SETTLE_TIME_MS));

---

Security & Performance

✅ No security concerns - only formatting display values, no XSS vectors
✅ Performance is fine - Intl.DateTimeFormat is well-optimized
✅ No external dependencies added

---

Compliance with CLAUDE.md

✅ Canonical location registered in CLAUDE.md table
✅ No variable re-exports (follows "No Variable Re-Exports" rule)
✅ Imports from canonical locations
✅ JSDoc comments present and helpful

---

Recommended Actions

1. Fix type inconsistency between verifiedAt and crawledAt (critical)
2. Consider using browser locale instead of hardcoded "en-US" (minor UX improvement)
3. Add timezone-specific tests for documentation purposes (low priority)

---

Conclusion

This is a well-crafted PR that adds valuable UX context to citations. The documentation is exemplary and will help future maintainers. The only critical issue is the type inconsistency in Verification, which should be addressed before merge.

Recommendation: Approve with minor changes (fix type consistency, consider locale improvements)

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