feat(circulation): Circulation of Love — anonymous, time-bound letter sharing

[TrainTravel]

Summary

Inspired by Train's grandfather's idea of the circulation of love. An opt-in, anonymous, time-bound sharing layer where users release a short (≤500 char) letter in their primary language. It rides a 14-day current — visible to other opted-in users in the same primary language — then quietly archives. The only reaction is Hold this for a moment (silent, idempotent, private to the author).

🟡 What it is NOT (locked at spec time): not a social network, not cross-lingual, not public outside the app, not viral, not search-indexed.

What ships (5 phases bundled)

Phase	Surface	Files
1	Spec + migration + types	docs/specs/love-circulation.md, supabase/migrations/20260613113018_…sql, types.ts regen
2	Edge fns	moderate-letter, circulate-letters
3	Hooks + 3 screens + HomeScreen tile	usePseudonym, useCirculationSettings, useLoveLetters; LettersInCirculationScreen, ShareALetterScreen, CirculationSettingsScreen
4	Drift animation + Lovable visual prompt	animate-letter-drift keyframe in index.css, docs/launch/lovable-circulation-display.md
5	Tests + changelog	11 new unit tests + 5 new E2E specs + CHANGELOG entry

Hard constraints honored

• Moderation cannot be bypassed. Client cannot insert a row with moderated_status != 'pending' (RLS); the moderate-letter edge fn inserts with the verdict baked in using service role. Gateway errors fail closed (softfail, never auto-publish).
• RLS strict. Other users see only passed + live + matching language + their own receive_letters = true. Holds require the same gate + non-own letter. Authors always retain access to their own letters (Object Permanence per CLAUDE.md).
• Idempotent reactions. letter_holdings PK = (letter_id, holder_id). Tapping twice = 1 hold. code 23505 treated as success.
• Distinct cron secret. circulate-letters uses CIRCULATION_CRON_SECRET, not a user JWT — leaked user token can't trigger archival.
• prefers-reduced-motion respected for the new drift animation.
• Bilingual coverage for every new chrome string across en/fr/es/ja/zh-Hans/zh-Hant.

Defaults applied (open questions from the spec)

Marathon-mode build. Applied the spec's recommended defaults:

1. Share via own flow only (not on JournalEntry).
2. Silent reactions (author sees count only when they visit).
3. Default TTL: 14 days.
4. Drift teaser via the same screen shell for non-opted-in users (Join CTA replaces the feed).
5. Cross-language: no, primary language only.

Override any of these before merge if needed.

Deploy notes

After merge, run these in Supabase:

supabase secrets set CIRCULATION_CRON_SECRET=$(openssl rand -hex 32)
supabase functions deploy moderate-letter
supabase functions deploy circulate-letters
# Then schedule circulate-letters daily at 03:00 UTC via the Supabase
# dashboard (or pg_cron) with header: Authorization: Bearer <secret>

The migration is the only required infrastructure piece — everything else gracefully degrades (the feed shows the empty/error state if the tables don't yet exist).

Test plan

• npm test → 359 vitest pass (+11 new)
• npm run test:e2e -- circulation.spec.ts → 5 specs pass
• npx tsc --noEmit → 0 errors
• Manual: opt in via HomeScreen tile → settings → release a passing letter → see it in the current → hold it
• Manual: release a letter containing "tonight I will" → see softfail/block note with crisis line reference
• Manual: switch to fr profile → confirm en letters are not visible (RLS language filter)
• Manual: in prefers-reduced-motion, confirm letter cards don't drift

End-goal artifact

docs/launch/lovable-circulation-display.md is the Lovable update prompt Train asked for last conversation — paste it into Lovable's chat once this PR lands. Hands off the visual elevation (paper texture, varied drift duration, ghost-letter hint behind CTA) to Lovable while keeping the data + hooks + testids frozen.

🤖 Generated with Claude Code