# JMAP Webmail - Architecture Reference

> Implementation details, file locations, and feature documentation.
> Last verified: 2026-03-16

## Settings Integration Status

All settings are properly wired to their functionality:

| Setting | Store Location | UI Control | Integration |
|---------|---------------|------------|-------------|
| deleteAction | settings-store.ts:26 | email-settings.tsx | Moves to trash or permanently deletes |
| showPreview | settings-store.ts:27 | email-settings.tsx | Conditionally renders preview in email list |
| externalContentPolicy | settings-store.ts:29 | email-settings.tsx | Controls external content blocking (ask/block/allow) |
| debugMode | settings-store.ts:40 | advanced-settings.tsx | Conditional logging via lib/debug.ts |
| animationsEnabled | settings-store.ts:17 | appearance-settings.tsx | Works via CSS variable |
| markAsReadDelay | settings-store.ts:25 | email-settings.tsx | Fully integrated |

## Email Features

### Drag-and-Drop
- Native HTML5 DnD API — drag emails to mailbox folders in sidebar
- Files: `contexts/drag-drop-context.tsx`, `hooks/use-email-drag.ts`, `hooks/use-mailbox-drop.ts`
- Multi-select support, permission validation, visual feedback

### Context Menus
- Right-click on email list items
- Files: `components/ui/context-menu.tsx`, `components/email/email-context-menu.tsx`, `hooks/use-context-menu.ts`
- Reply, Forward, Move to, Color tags, Delete — supports batch operations

### Mobile Responsive
- Adaptive single/multi-pane layout with CSS-first breakpoints (no JS layout lag)
- Files: `stores/ui-store.ts`, `hooks/use-media-query.ts`, `components/layout/mobile-header.tsx`
- Mobile bottom action bar: `components/email/mobile-action-bar.tsx` (reply, archive, delete, more)
- Long-press context menu: `hooks/use-long-press.ts` (300ms, vibration, scale feedback)
- Touch-friendly submenu: tap-to-expand on `pointer: coarse` devices
- Hamburger menu navigation, view switching, safe area support

### Keyboard Shortcuts
- Hook: `hooks/use-keyboard-shortcuts.ts`
- Modal: `components/keyboard-shortcuts-modal.tsx`
- Navigation: j/k or arrows (next/prev email), Enter/o (open), Esc (close)
- Actions: r (reply), R/a (reply all), f (forward), s (star), e (archive), #/Del (delete), u (unread)
- Global: c (compose), / (search), ? (help), Shift+G (refresh), Ctrl+A (select all)
- Threads: x (expand/collapse thread)
- Disabled when typing in inputs or when composer is open

### Email Threading
- Gmail-style inline expansion (desktop), full-screen conversation view (mobile)
- Files:
  - `lib/thread-utils.ts` — Thread grouping utilities
  - `lib/jmap/types.ts` — ThreadGroup interface
  - `lib/jmap/client.ts` — getThread(), getThreadEmails() methods
  - `stores/email-store.ts` — Thread expansion state
  - `components/email/thread-list-item.tsx` — Collapsed/expanded thread view
  - `components/email/thread-email-item.tsx` — Compact email within thread
  - `components/email/thread-conversation-view.tsx` — Full-screen mobile conversation view
  - `components/email/email-list.tsx` — Groups emails by threadId

### Sandboxed Email Rendering
- Rich HTML emails (tables, stylesheets) rendered in sandboxed iframe for CSS isolation
- Simple HTML/plain text rendered inline via DOMPurify (faster, no iframe overhead)
- Decision function: `lib/email-sanitization.ts` (`needsIframeRendering()`)
- Iframe component: `components/email/sandboxed-email-frame.tsx` (auto-height, link interception)
- Applied in both `email-viewer.tsx` and `thread-conversation-view.tsx`
- DOMPurify remains the security boundary; iframe provides CSS containment only

### Dark Mode Email Readability
- Intelligent color transformation during HTML sanitization
- Files: `lib/color-transform.ts`, `components/email/email-viewer.tsx`
- Iframe path: uses `prefers-color-scheme` media query via `generateIframeStylesheet()`
- Luminance < 0.4 (very dark): Inverted and brightened
- Luminance 0.4-0.6 (medium): Lightened by 40-50%
- Luminance > 0.6 (light): Preserved as-is

### Newsletter Unsubscribe (RFC 2369)
- Files: `lib/validation.ts`, `lib/email-headers.ts`, `components/email/unsubscribe-banner.tsx`
- URL validation blocks XSS vectors, two-step confirmation, localStorage persistence
- Supports both HTTP (one-click) and mailto methods

### Email Layout & Blocked Content Fix
- Removed `width: max-content` / `display: inline-block` from email content wrappers
- Files: `app/globals.css`, `lib/email-sanitization.ts`, `components/email/email-viewer.tsx`
- Blocked images: walks up DOM to collapse empty containers

## Identity Management & Sub-Addressing
- Full CRUD: `stores/identity-store.ts`, `lib/jmap/client.ts` (Identity/get, Identity/set)
- Components: `components/identity/identity-manager-modal.tsx`, `components/identity/identity-form.tsx`
- Sub-addressing: `lib/sub-addressing.ts` (parse, generate, suggest)
- Visual badges: `components/email/email-identity-badge.tsx`

## Calendar Integration

### Core
- JMAP Calendars: Full CalendarEvent CRUD with RFC 8984 types
- Files: `lib/jmap/types.ts`, `lib/jmap/client.ts`, `stores/calendar-store.ts`
- Capability detection: `urn:ietf:params:jmap:calendars` in auth-store.ts
- UI: `components/calendar/` (month-view, week-view, day-view, agenda-view, toolbar, event-modal, event-detail-popover, event-card, mini-calendar, calendar-sidebar-panel)
- Settings: `components/settings/calendar-settings.tsx`
- Keyboard: m (month), w (week), d (day), a (agenda), t (today), n (new event), arrows (navigate)

### Drag-and-Drop Rescheduling
- Week/day views: 15-min snap with visual indicator
- Month view: date move with blue ring highlight
- HTML5 DnD API with `application/x-calendar-event` payload

### Click-Drag to Create
- Pointer events, 5px movement threshold
- Shared hook: `hooks/use-time-grid-interactions.ts`

### Event Resize
- Drag bottom edge, 15-min snap, optimistic JMAP update
- `role="separator"` with aria-label

### Recurring Event Edit Scope
- "This event only" / "This and following" / "All events" dialog
- Files: `components/calendar/recurrence-scope-dialog.tsx`

### Event Detail Popover (Read-Only View)
- Click event → read-only popover (instead of edit form)
- Component: `components/calendar/event-detail-popover.tsx`
- Displays: title, calendar, date/time, location (URL-aware with `target="_blank" rel="noreferrer"`), virtual meeting link, participants with status badges, recurrence, reminder, description
- Actions: Edit (opens modal), Delete (with confirmation), Duplicate
- Quick note: inline input appends timestamped note to description
- RSVP bar for attendees (Accept/Tentative/Decline)
- Smart positioning: right → left → below → above, stays in viewport
- Portal-rendered, CSS transition entrance, dismisses on Escape/click-outside/scroll

### Double-Click Quick Create
- Inline title input, PT1H default, timer-based click disambiguation
- Component: `components/calendar/quick-event-input.tsx`

### iCalendar Import
- Files: `lib/jmap/client.ts` (parseCalendarEvents), `components/calendar/ical-import-modal.tsx`
- Multi-step flow: file select → preview list → calendar selector → import (5MB max)

## Email Filters & Sieve Rules (RFC 9661)
- Types: `lib/jmap/sieve-types.ts`
- Client: `lib/jmap/client.ts` (12 Sieve methods)
- Generator/Parser: `lib/sieve/generator.ts`, `lib/sieve/parser.ts`
- Store: `stores/filter-store.ts`
- UI: `components/settings/filter-settings.tsx`, `components/filters/filter-rule-modal.tsx`, `components/filters/sieve-editor-modal.tsx`
- Conditions: From, To, Cc, Subject, Custom Header, Size, Body
- Actions: Move, Copy, Forward, Mark read, Star, Label, Discard, Reject, Keep, Stop

## Email Templates
- Local storage via Zustand persist middleware
- Files: `lib/template-types.ts`, `stores/template-store.ts`, `lib/template-utils.ts`
- Components: `components/templates/` (template-manager-modal, template-form, template-picker, placeholder-fill-modal)
- Placeholder variables: `{{variable}}` syntax with auto-fill from composer context
- Composer shortcut: Ctrl+Shift+T

## Accessibility (WCAG 2.0 AA)
- Color contrast rules documented in CLAUDE.md
- All color via CSS variables or Tailwind classes
- ARIA roles on calendar grids, event cards, modals
- Focus trap in all modals, 44px mobile touch targets
- Reduced-motion media query, sr-only live region

## Dependency Versions (2026-02-16)
- next 16.1.6, react 19.2.4, next-intl 4.8.3, zustand 5.0.11, vitest 4.0.18
- @types/node 25, jsdom 28, lucide-react 0.564

## Feature Completeness Summary
- **Authentication**: Complete (Basic Auth + TOTP 2FA + OAuth2/OIDC with PKCE)
- **Email Operations**: Complete (threading, unsubscribe, templates)
- **Real-time Updates**: Complete (EventSource push)
- **UI**: Settings integrated, DnD, context menus, mobile, keyboard, WCAG AA
- **Identity Management**: Complete (CRUD, sub-addressing, signatures)
- **Contacts/Address Book**: Complete (groups, vCard, bulk ops)
- **Advanced Search**: Complete (JMAP filters, search chips)
- **Vacation Responder**: Complete (JMAP VacationResponse)
- **Calendar**: Phase 5 complete (event detail popover, quick notes, drag-create, resize, recurring scope, quick create, duplication, import, notifications)
- **Email Filters**: Complete (Sieve RFC 9661, visual + raw editor)
- **Security**: CSP Report-Only + all P0 headers, sandboxed iframe for HTML emails
- **API Robustness**: Exponential backoff retry (`lib/jmap/retry.ts`) for transient JMAP failures
- **Sidebar**: Tag counts section, empty folder (junk/trash), resizable width (`hooks/use-resize-handle.ts`)
- **Density**: Extra-compact option (28px desktop, 44px touch), persisted in settings
- **Sender Info**: Expandable panel in email viewer (`components/email/sender-info-panel.tsx`)
- **Security Tooltips**: Plain-language SPF/DKIM/DMARC explanations on hover
- **Testing**: 704 tests passing