+
+ )
+}
diff --git a/web/src/app/(shell)/inbox/[folder]/page.tsx b/web/src/app/(shell)/inbox/[folder]/page.tsx
new file mode 100644
index 0000000..b7ad6ec
--- /dev/null
+++ b/web/src/app/(shell)/inbox/[folder]/page.tsx
@@ -0,0 +1,62 @@
+import { notFound, redirect } from 'next/navigation'
+import { InboxScreen } from '../../../../components/InboxScreen'
+import { listConversations } from '../../../../lib/api'
+import { isAppFolder } from '../../../../lib/folders'
+
+/**
+ * The inbox list — a server component: the API call (and its Bearer token)
+ * happens here, and the client screen receives plain data. `open` is a
+ * legacy alias that redirects to `unassigned` (its default view). `?cursor=`
+ * pages older conversations via the API's opaque keyset cursor (spec §3a),
+ * for the Closed and Spam folders only — the other five derive their view
+ * from a flat `open` fetch (Unassigned/Mine/Assigned split by `assignee`;
+ * Starred/Drafts filter an `open`+`closed` fetch against localStorage).
+ */
+export default async function InboxPage({
+ params,
+ searchParams,
+}: {
+ params: Promise<{ folder: string }>
+ searchParams: Promise<{ cursor?: string }>
+}) {
+ const { folder } = await params
+ if (folder === 'open') redirect('/inbox/unassigned')
+ if (!isAppFolder(folder)) notFound()
+
+ switch (folder) {
+ case 'unassigned':
+ case 'mine':
+ case 'assigned': {
+ const page = await listConversations({ folder: 'open', limit: 50 })
+ return
+ }
+
+ case 'starred':
+ case 'drafts': {
+ const [openPage, closedPage] = await Promise.all([
+ listConversations({ folder: 'open', limit: 50 }),
+ listConversations({ folder: 'closed', limit: 50 }),
+ ])
+ const conversations = [...openPage.conversations, ...closedPage.conversations].sort(
+ (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
+ )
+ return
+ }
+
+ case 'closed':
+ case 'spam': {
+ const { cursor } = await searchParams
+ const page = await listConversations({
+ folder,
+ ...(cursor !== undefined ? { cursor } : {}),
+ })
+ return (
+
+ )
+ }
+ }
+}
diff --git a/web/src/app/(shell)/layout.tsx b/web/src/app/(shell)/layout.tsx
new file mode 100644
index 0000000..75567e2
--- /dev/null
+++ b/web/src/app/(shell)/layout.tsx
@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react'
+import { FolderNav } from '../../components/FolderNav'
+import { loadFolderCounts } from '../../lib/folder-counts'
+
+/**
+ * The app shell shared by the inbox and conversation routes: the persistent
+ * folder rail on the warm-paper canvas, with each screen as the elevated
+ * work surface beside it (the design system's layer model). The rail's
+ * counts and support address are fetched here (server-side, with the
+ * Bearer token) and handed to the client `FolderNav` as props.
+ */
+export default async function ShellLayout({ children }: { children: ReactNode }) {
+ const counts = await loadFolderCounts()
+ const supportAddress = process.env.HELPTHREAD_SUPPORT_ADDRESS ?? 'support@dev.localhost'
+
+ return (
+
+
+ {children}
+
+ )
+}
diff --git a/web/src/app/dashboard/page.tsx b/web/src/app/dashboard/page.tsx
new file mode 100644
index 0000000..bb0ac49
--- /dev/null
+++ b/web/src/app/dashboard/page.tsx
@@ -0,0 +1,14 @@
+import { DashboardScreen } from '../../components/DashboardScreen'
+import { loadFolderCounts } from '../../lib/folder-counts'
+
+/**
+ * /dashboard — a plain top-level route (no folder rail; the design puts the
+ * mailbox overview outside the shell, same as `/settings`). The wordmark
+ * and the top bar's Mailbox tab both land here.
+ */
+export default async function DashboardPage() {
+ const counts = await loadFolderCounts()
+ const supportAddress = process.env.HELPTHREAD_SUPPORT_ADDRESS ?? 'support@dev.localhost'
+
+ return
+}
diff --git a/web/src/app/error.tsx b/web/src/app/error.tsx
new file mode 100644
index 0000000..187d7ca
--- /dev/null
+++ b/web/src/app/error.tsx
@@ -0,0 +1,20 @@
+'use client'
+
+/**
+ * Top-level route error boundary — the fallback for any route NOT inside a
+ * more specific boundary (notably `/dashboard`, which lives outside the
+ * `(shell)` group). Routes a 401 (tagged via `error.digest`) to the designed
+ * AuthFailure screen, like the segment boundaries do. It does NOT catch errors
+ * thrown by the ROOT LAYOUT itself (only a global-error boundary can) — but the
+ * layout is now resilient (its one fetch is swallowed on failure), so nothing
+ * there throws, and the errors that reach here come from page components.
+ */
+
+import { AppError } from '../components/AppError'
+
+export default function RootError(props: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ return
+}
diff --git a/web/src/app/layout.tsx b/web/src/app/layout.tsx
new file mode 100644
index 0000000..fb614ce
--- /dev/null
+++ b/web/src/app/layout.tsx
@@ -0,0 +1,77 @@
+import type { Metadata } from 'next'
+import type { ReactNode } from 'react'
+import '../theme/helpthread.css'
+import { ShortcutsProvider } from '../components/ShortcutsProvider'
+import { ThemeProvider } from '../components/ThemeProvider'
+import { ToasterProvider } from '../components/Toaster'
+import { TopBar } from '../components/TopBar'
+import { listConversations } from '../lib/api'
+import type { ConversationSummary } from '../lib/api-types'
+import { THEME_INIT_SCRIPT } from '../lib/theme'
+
+export const metadata: Metadata = {
+ title: 'Helpthread',
+ description: 'Helpthread Agent Inbox',
+}
+
+/**
+ * The app shell: the accent-filled top bar — the design system's ONE colored
+ * surface — carrying the wordmark (plain text, serif, muted dot; there is no
+ * logo) and the Mailbox/Manage/Notifications/Agent menus (`TopBar`), over the
+ * warm-paper canvas everything else sits on. Stays a server component: the
+ * Notifications panel's data (6 most recent open conversations) is fetched
+ * here, with the Bearer token, and handed to the client `TopBar` as props.
+ */
+export default async function RootLayout({ children }: { children: ReactNode }) {
+ // The notifications bell is non-critical chrome. Its fetch MUST NOT be able
+ // to take down the whole app: an error thrown here (e.g. a bad token
+ // surfacing as 401) would escape ABOVE every route error boundary — the
+ // boundaries live under this layout — so the designed AuthFailure screen
+ // would never render and the app would hard-crash instead. Swallowing it to
+ // an empty bell lets the SAME 401 resurface from the page-level fetch, which
+ // the route error boundaries DO catch and route to AuthFailure.
+ let recentOpen: ConversationSummary[] = []
+ try {
+ recentOpen = (await listConversations({ folder: 'open', limit: 6 })).conversations
+ } catch {
+ // Empty bell; the real error surfaces (and is handled) at the page level.
+ }
+
+ return (
+ // suppressHydrationWarning: the inline script below sets `data-theme` on
+ // this element BEFORE React hydrates (that's the whole point — it avoids
+ // a flash of the wrong theme), so the attribute React sees during
+ // hydration legitimately differs from what it server-rendered. This is
+ // the standard fix for this exact pattern (see e.g. next-themes); it
+ // only suppresses the warning for this one element's own attributes; it
+ // has no effect on children.
+
+
+ {/* biome-ignore lint/security/noDangerouslySetInnerHtml: pre-hydration
+ theme apply, must run standalone before any bundle loads — see
+ lib/theme.ts */}
+
+
+
+
+
+
+
+ {children}
+
+
+
+
+
+ )
+}
diff --git a/web/src/app/not-found.tsx b/web/src/app/not-found.tsx
new file mode 100644
index 0000000..9374e11
--- /dev/null
+++ b/web/src/app/not-found.tsx
@@ -0,0 +1,32 @@
+import Link from 'next/link'
+import { EmptyState } from '../components/ds/core/EmptyState'
+
+/**
+ * Global 404 (fidelity checklist). Root-level so it also catches an
+ * unmatched route; a `notFound()` thrown inside `(shell)` (e.g. an unknown
+ * folder) bubbles up here too, since that segment has no not-found of its
+ * own — which also means the folder rail doesn't render alongside it.
+ */
+export default function NotFound() {
+ return (
+
+
+
+
+ Back to inbox
+
+
+
+ )
+}
diff --git a/web/src/app/page.tsx b/web/src/app/page.tsx
new file mode 100644
index 0000000..c0aaf40
--- /dev/null
+++ b/web/src/app/page.tsx
@@ -0,0 +1,6 @@
+import { redirect } from 'next/navigation'
+
+/** The inbox IS the app — land in the open folder. */
+export default function Home() {
+ redirect('/inbox/open')
+}
diff --git a/web/src/app/settings/error.tsx b/web/src/app/settings/error.tsx
new file mode 100644
index 0000000..8bd0c7f
--- /dev/null
+++ b/web/src/app/settings/error.tsx
@@ -0,0 +1,11 @@
+'use client'
+
+import { AppError } from '../../components/AppError'
+
+/** Error boundary for /settings. See `AppError`. */
+export default function SettingsError(props: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ return
+}
diff --git a/web/src/app/settings/page.tsx b/web/src/app/settings/page.tsx
new file mode 100644
index 0000000..730e4fd
--- /dev/null
+++ b/web/src/app/settings/page.tsx
@@ -0,0 +1,19 @@
+import { SettingsScreen } from '../../components/SettingsScreen'
+
+/**
+ * Settings — a plain top-level route (no folder rail; the design deliberately
+ * puts it outside the shell). The Deployment card is read-only display: this
+ * app has no API affordance for these values (they're engine-side deploy
+ * config, spec's `mailDomain`/`supportAddress` deps), so this server
+ * component reads them from its own env — falling back to the same dev
+ * defaults the local harness uses (`scripts/dev-api.ts`) when unset.
+ */
+export default function SettingsPage() {
+ const deployment = {
+ productName: 'Helpthread',
+ supportAddress: process.env.HELPTHREAD_SUPPORT_ADDRESS ?? 'support@dev.localhost',
+ mailDomain: process.env.HELPTHREAD_MAIL_DOMAIN ?? 'mail.dev.localhost',
+ }
+
+ return
+}
diff --git a/web/src/components/AppError.tsx b/web/src/components/AppError.tsx
new file mode 100644
index 0000000..f1fda52
--- /dev/null
+++ b/web/src/components/AppError.tsx
@@ -0,0 +1,60 @@
+'use client'
+
+/**
+ * Shared body for the route error boundaries (`app/(shell)/error.tsx`,
+ * `app/settings/error.tsx`). A 401 from `lib/api.ts` is tagged with
+ * `error.digest === AUTH_ERROR_DIGEST` — the channel that survives Next.js's
+ * production sanitization of Server Component errors (which strips `message`)
+ * — and that selects the AuthFailure screen instead of the generic fallback
+ * below. The `unauthorized:` message prefix is a dev-only fallback.
+ */
+
+import { AUTH_ERROR_DIGEST } from '../lib/auth-error'
+import { AuthFailure } from './AuthFailure'
+import { Button } from './ds/core/Button'
+
+export function AppError({
+ error,
+ reset,
+}: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ if (error.digest === AUTH_ERROR_DIGEST || error.message.startsWith('unauthorized:')) {
+ return
+ }
+
+ return (
+
+
+
The inbox couldn't load.
+
+ {error.message}
+
+
+
+
+
+
+ )
+}
diff --git a/web/src/components/AuthFailure.tsx b/web/src/components/AuthFailure.tsx
new file mode 100644
index 0000000..740349c
--- /dev/null
+++ b/web/src/components/AuthFailure.tsx
@@ -0,0 +1,95 @@
+'use client'
+
+/**
+ * Full-screen auth-failure state (fidelity checklist). Rendered by
+ * `AppError` when a thrown `ApiError` carries the auth-failure `error.digest`
+ * (see `lib/api.ts` and `lib/auth-error.ts`). `position: fixed; inset: 0` so it covers the
+ * whole viewport regardless of where in the tree it's rendered — a broken
+ * service token means nothing else on the page (folder rail included) is
+ * usable anyway.
+ */
+
+import { Button } from './ds/core/Button'
+
+export function AuthFailure() {
+ return (
+
+
+ helpthread.
+
+
+ Helpthread can’t reach your inbox
+
+
+ Every request is signed with this deployment’s service token, and the API just
+ rejected it. There’s nothing to sign into — this is configuration, not a login.
+
+
+ HELPTHREAD_API_TOKEN
+
+
+ Update the token in your deployment settings, redeploy, and reload this page.
+
+
+
+
+
+ )
+}
diff --git a/web/src/components/ConversationScreen.tsx b/web/src/components/ConversationScreen.tsx
new file mode 100644
index 0000000..fd249ee
--- /dev/null
+++ b/web/src/components/ConversationScreen.tsx
@@ -0,0 +1,1713 @@
+'use client'
+
+/**
+ * One conversation: toolbar (back, reply/note/delete, tags, star, more,
+ * assignee/status/position — subject/#number/status pill on a wrapped
+ * second row), a SUMMONED composer (hidden by default; opens via the
+ * toolbar Reply/Note buttons, the `r`/`n` keys, or automatically when a
+ * saved draft exists), and the thread as full-bleed MessageBands
+ * newest-first (design-system rule: bands, not chat bubbles).
+ *
+ * The composer implements spec §4a's client contract faithfully:
+ * - ONE Idempotency-Key per logical send, minted when the draft starts and
+ * reused verbatim on every retry — a 409 `retry_in_progress` or a network
+ * failure never mints a new key (that would risk a duplicate send). A
+ * `400 validation_failed` DOES mint a new key — the original attempt never
+ * reached the send path, so there is nothing to safely replay.
+ * - `send_failed` (502) keeps the draft and says exactly what is true:
+ * nothing reached the customer, with a "Retry send" action that reuses
+ * the same key.
+ * - Only a SUCCESS clears the draft and rotates the key.
+ *
+ * This screen also owns its own keyboard shortcuts (j/k conversation nav,
+ * r/n to open the composer, ⌘/Ctrl+↵ to send, and a cascading Escape) — see
+ * the keydown effect below, coordinated with `ShortcutsProvider`'s overlay.
+ */
+
+import { useRouter } from 'next/navigation'
+import type { CSSProperties } from 'react'
+import { useEffect, useRef, useState, useTransition } from 'react'
+import {
+ deleteConversationAction,
+ postNoteAction,
+ putAssigneeAction,
+ putTagsAction,
+ sendReplyAction,
+ setStatusAction,
+} from '../lib/actions'
+import type { ConversationDetail, ConversationStatus, ThreadView } from '../lib/api-types'
+import { clearDraft, getDraft, writeDraft } from '../lib/drafts'
+import { messageTime, nameFromEmail, relativeTime, shortDate } from '../lib/format'
+import { useStarred } from '../lib/starred'
+import { Avatar } from './ds/core/Avatar'
+import { Button } from './ds/core/Button'
+import { DropdownMenu } from './ds/core/DropdownMenu'
+import { IconButton } from './ds/core/IconButton'
+import { MenuItem } from './ds/core/MenuItem'
+import { StatusPill } from './ds/core/StatusPill'
+import { TagChip } from './ds/core/TagChip'
+import { TextInput } from './ds/core/TextInput'
+import { MessageBand } from './ds/inbox/MessageBand'
+import { ToolbarBand } from './ds/inbox/ToolbarBand'
+import { SanitizedHtml } from './SanitizedHtml'
+import { useShortcutsOverlay } from './ShortcutsProvider'
+import { useToast } from './Toaster'
+
+const MAX_REPLY_LENGTH = 5000
+const MAX_TAG_LENGTH = 40
+const DELETE_DISARM_MS = 3500
+const DRAFT_SAVE_DEBOUNCE_MS = 300
+
+/** Reply-mode formatting is honestly reported only when the Agent actually
+ * used the toolbar — checked by tag presence, not by diffing markup. */
+function hasRichFormatting(el: HTMLElement): boolean {
+ return el.querySelector('b, i, ul, a') !== null
+}
+
+/** contenteditable's `innerText` reports a trailing newline for the last
+ * (empty) line — trim only trailing whitespace, keep interior formatting. */
+function normalizedInnerText(el: HTMLElement): string {
+ return el.innerText.replace(/\s+$/, '')
+}
+
+function pillTabStyle(active: boolean): CSSProperties {
+ return {
+ border: 'none',
+ borderRadius: 999,
+ padding: '4px 12px',
+ fontSize: 12.5,
+ fontWeight: 700,
+ cursor: 'pointer',
+ background: active ? 'var(--ht-accent)' : 'var(--ht-surface-2)',
+ color: active ? 'var(--ht-on-accent)' : 'var(--ht-ink-muted)',
+ }
+}
+
+function counterStyle(length: number): CSSProperties {
+ const over = length > MAX_REPLY_LENGTH
+ return {
+ fontSize: 11.5,
+ fontVariantNumeric: 'tabular-nums',
+ fontWeight: over ? 700 : 400,
+ color: over ? 'var(--ht-critical)' : 'var(--ht-ink-dim)',
+ }
+}
+
+const WARN_BANNER_STYLE: CSSProperties = {
+ marginBottom: 10,
+ padding: '8px 12px',
+ borderRadius: 'var(--ht-radius-md)',
+ background: 'color-mix(in oklab, var(--ht-warn) 9%, var(--ht-surface))',
+ border: '1px solid color-mix(in oklab, var(--ht-warn) 30%, transparent)',
+ fontSize: 12.5,
+ color: 'var(--ht-ink-muted)',
+}
+
+const CRITICAL_BANNER_STYLE: CSSProperties = {
+ marginBottom: 10,
+ padding: '10px 14px',
+ borderRadius: 'var(--ht-radius-md)',
+ background: 'var(--ht-critical-soft)',
+ border: '1px solid color-mix(in oklab, var(--ht-critical) 28%, transparent)',
+}
+
+/** Plain borderless icon buttons on the format-toolbar row — the design has
+ * no grey pill/segmented group around them, just hover feedback. */
+const FORMAT_BUTTON_STYLE: CSSProperties = {
+ width: 26,
+ height: 26,
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ fontSize: 12.5,
+ fontWeight: 700,
+ color: 'var(--ht-ink-muted)',
+ background: 'none',
+ border: 'none',
+ borderRadius: 'var(--ht-radius-sm)',
+ cursor: 'pointer',
+}
+
+function onFormatButtonHover(event: { currentTarget: HTMLElement }): void {
+ event.currentTarget.style.background = 'var(--ht-surface-2)'
+}
+
+function onFormatButtonUnhover(event: { currentTarget: HTMLElement }): void {
+ event.currentTarget.style.background = 'none'
+}
+
+const CONTENT_EDITABLE_STYLE: CSSProperties = {
+ minHeight: 84,
+ outline: 'none',
+ fontSize: 14,
+ lineHeight: 1.6,
+ color: 'var(--ht-ink)',
+ whiteSpace: 'pre-wrap',
+ overflowWrap: 'break-word',
+}
+
+export interface ConversationNeighborPosition {
+ index: number
+ total: number
+ prevId: string | null
+ nextId: string | null
+}
+
+/** A prior conversation from the same customer — the context panel's
+ * "Previous conversations" section (design fix C5). */
+export interface PreviousConversationSummary {
+ id: string
+ subject: string
+ status: ConversationStatus
+ updatedAt: string
+}
+
+const STATUS_META: Record = {
+ active: { label: 'Active', fg: 'var(--ht-accent)', bg: 'var(--ht-accent-soft)' },
+ pending: {
+ label: 'Pending',
+ fg: 'var(--ht-warn)',
+ bg: 'color-mix(in oklab, var(--ht-warn) 12%, transparent)',
+ },
+ closed: { label: 'Closed', fg: 'var(--ht-ink-dim)', bg: 'var(--ht-surface-2)' },
+ spam: { label: 'Spam', fg: 'var(--ht-critical)', bg: 'var(--ht-critical-soft)' },
+}
+
+function ReplyIcon() {
+ return (
+
+ )
+}
+
+function NoteIcon() {
+ return (
+
+ )
+}
+
+function TrashIcon() {
+ return (
+
+ )
+}
+
+function TagIcon() {
+ return (
+
+ )
+}
+
+function StarIcon({ filled }: { filled: boolean }) {
+ return (
+
+ )
+}
+
+function PersonIcon() {
+ return (
+
+ )
+}
+
+function FlagIcon() {
+ return (
+
+ )
+}
+
+function GearIcon() {
+ return (
+
+ )
+}
+
+function MoreIcon() {
+ return (
+
+ )
+}
+
+function ChevronDownIcon() {
+ return (
+
+ )
+}
+
+function ChevronLeftIcon() {
+ return (
+
+ )
+}
+
+function ChevronRightIcon() {
+ return (
+
+ )
+}
+
+function BulletListIcon() {
+ return (
+
+ )
+}
+
+function LinkIcon() {
+ return (
+
+ )
+}
+
+function CloseIcon() {
+ return (
+
+ )
+}
+
+/** ⌄ per-message menu — Copy text / Show original. Positioned by the caller's wrapper div. */
+function MessageMenu({
+ open,
+ onToggle,
+ onClose,
+ onCopyText,
+ onShowOriginal,
+}: {
+ open: boolean
+ onToggle: () => void
+ onClose: () => void
+ onCopyText: () => void
+ onShowOriginal: () => void
+}) {
+ return (
+
+
+
+
+
+
+
+
+
+ )
+}
+
+/**
+ * Fixed centered modal: the raw source, exactly as it arrived, never
+ * rendered as HTML. Escape is handled by the parent's cascading Escape
+ * handler (this modal has top priority in that cascade), not locally — a
+ * single owner avoids two listeners racing to close the same state.
+ */
+function OriginalMessageModal({ thread, onClose }: { thread: ThreadView; onClose: () => void }) {
+ const bodyKind =
+ thread.bodyHtml !== null && thread.bodyText !== null && thread.bodyText !== ''
+ ? 'HTML + text'
+ : thread.bodyHtml !== null
+ ? 'HTML only'
+ : thread.bodyText !== null
+ ? 'Text only'
+ : 'Empty'
+
+ const source = thread.bodyHtml ?? thread.bodyText ?? ''
+
+ return (
+ <>
+
+
+
+ Original message
+
+
+
+
+
+
+ From
+
+ {thread.from}
+
+ Date
+
+ {new Date(thread.createdAt).toLocaleString()}
+
+ Body kind
+ {bodyKind}
+
+
+ {source}
+
+
+ Shown as source, never rendered — this is the untrusted message exactly as it arrived.
+
+
+
+ )
+}
+
+export function ConversationScreen({
+ conversation,
+ position,
+ previousConversations,
+}: {
+ conversation: ConversationDetail
+ position: ConversationNeighborPosition | null
+ previousConversations: PreviousConversationSummary[]
+}) {
+ const router = useRouter()
+ const showToast = useToast()
+ const { isStarred, toggle } = useStarred()
+ const { isOpen: isShortcutsOverlayOpen } = useShortcutsOverlay()
+
+ const [isPending, startTransition] = useTransition()
+
+ // The summoned composer — hidden by default (spec: opens via the toolbar,
+ // r/n, or automatically when a saved draft exists).
+ const [composerOpen, setComposerOpen] = useState(false)
+ const [composerMode, setComposerMode] = useState<'reply' | 'note'>('reply')
+ const [composerError, setComposerError] = useState(null)
+ const [sendFailed, setSendFailed] = useState(false)
+ const [replyTextLength, setReplyTextLength] = useState(0)
+ const [noteDraft, setNoteDraft] = useState('')
+ // Bumped by the per-conversation reset below so the DOM-population effect
+ // re-runs even when `composerOpen` itself doesn't change value (both
+ // conversations have a draft, so it's `true` on both sides of a j/k nav).
+ const [composerGeneration, setComposerGeneration] = useState(0)
+
+ const replyBodyRef = useRef(null)
+ const noteTextareaRef = useRef(null)
+ // Plain text loaded from localStorage for the CURRENT conversation, and
+ // the live in-session HTML once the Agent has actually typed (so toggling
+ // the composer closed/open again within the same visit keeps formatting —
+ // only localStorage itself is plain-text-only, per the draft contract).
+ const replyDraftTextRef = useRef('')
+ const replyBodyHtmlRef = useRef(null)
+ const draftSaveTimer = useRef | null>(null)
+ // One key per logical send (spec §4a) — rotated on success, and on a
+ // validation failure (the original attempt never reached the send path).
+ const idempotencyKey = useRef(crypto.randomUUID())
+
+ const [status, setLocalStatus] = useState(conversation.status)
+ const [tags, setTags] = useState(conversation.tags)
+ const [assignee, setAssignee] = useState<'me' | null>(conversation.assignee)
+
+ const [tagInput, setTagInput] = useState('')
+ const [tagsMenuOpen, setTagsMenuOpen] = useState(false)
+ const [assigneeMenuOpen, setAssigneeMenuOpen] = useState(false)
+ const [statusMenuOpen, setStatusMenuOpen] = useState(false)
+ const [moreMenuOpen, setMoreMenuOpen] = useState(false)
+ const [following, setFollowing] = useState(false)
+ const [previousConversationsOpen, setPreviousConversationsOpen] = useState(true)
+
+ const [deleteArmed, setDeleteArmed] = useState(false)
+ const deleteDisarmTimer = useRef | null>(null)
+
+ const [openMessageMenuId, setOpenMessageMenuId] = useState(null)
+ const [originalMessage, setOriginalMessage] = useState(null)
+
+ useEffect(() => {
+ return () => {
+ if (deleteDisarmTimer.current !== null) clearTimeout(deleteDisarmTimer.current)
+ if (draftSaveTimer.current !== null) clearTimeout(draftSaveTimer.current)
+ }
+ }, [])
+
+ // Per-conversation reset — this component instance is reused across
+ // conversations (j/k, prev/next chevrons navigate without remounting), so
+ // this can't be a one-time mount effect. Loads that conversation's saved
+ // draft and auto-opens the composer when one exists.
+ useEffect(() => {
+ const existingDraft = getDraft(conversation.id) ?? ''
+ replyDraftTextRef.current = existingDraft
+ replyBodyHtmlRef.current = null
+ setReplyTextLength(existingDraft.length)
+ setNoteDraft('')
+ setComposerError(null)
+ setSendFailed(false)
+ idempotencyKey.current = crypto.randomUUID()
+ setComposerGeneration((generation) => generation + 1)
+ if (existingDraft.length > 0) {
+ setComposerMode('reply')
+ setComposerOpen(true)
+ } else {
+ setComposerOpen(false)
+ }
+ }, [conversation.id])
+
+ // Populate the (uncontrolled) contenteditable whenever the reply composer
+ // becomes visible — never on every keystroke, so the caret stays put.
+ // biome-ignore lint/correctness/useExhaustiveDependencies: composerGeneration is the trigger, not read in the body
+ useEffect(() => {
+ if (!composerOpen || composerMode !== 'reply') return
+ const el = replyBodyRef.current
+ if (el === null) return
+ if (replyBodyHtmlRef.current !== null) {
+ el.innerHTML = replyBodyHtmlRef.current
+ } else {
+ el.textContent = replyDraftTextRef.current
+ }
+ setReplyTextLength(normalizedInnerText(el).length)
+ el.focus()
+ const range = document.createRange()
+ range.selectNodeContents(el)
+ range.collapse(false)
+ const selection = window.getSelection()
+ selection?.removeAllRanges()
+ selection?.addRange(range)
+ }, [composerOpen, composerMode, composerGeneration])
+
+ useEffect(() => {
+ if (composerOpen && composerMode === 'note') noteTextareaRef.current?.focus()
+ }, [composerOpen, composerMode])
+
+ function scheduleDraftSave(text: string): void {
+ if (draftSaveTimer.current !== null) clearTimeout(draftSaveTimer.current)
+ draftSaveTimer.current = setTimeout(() => {
+ writeDraft(conversation.id, text)
+ replyDraftTextRef.current = text
+ }, DRAFT_SAVE_DEBOUNCE_MS)
+ }
+
+ function onReplyBodyInput(): void {
+ const el = replyBodyRef.current
+ if (el === null) return
+ replyBodyHtmlRef.current = el.innerHTML
+ const text = normalizedInnerText(el)
+ setReplyTextLength(text.length)
+ setComposerError(null)
+ scheduleDraftSave(text)
+ }
+
+ // document.execCommand is deprecated, but it remains the only
+ // cross-browser way to drive a contenteditable's rich-text edits without
+ // pulling in a full editor library — exactly what the prototype does.
+ function applyFormat(command: 'bold' | 'italic' | 'insertUnorderedList'): void {
+ replyBodyRef.current?.focus()
+ document.execCommand(command)
+ onReplyBodyInput()
+ }
+
+ function applyLink(): void {
+ const url = window.prompt('Link URL')
+ if (url === null || url.trim().length === 0) return
+ replyBodyRef.current?.focus()
+ document.execCommand('createLink', false, url.trim())
+ onReplyBodyInput()
+ }
+
+ function openComposer(mode: 'reply' | 'note'): void {
+ setComposerMode(mode)
+ setComposerError(null)
+ setSendFailed(false)
+ setComposerOpen(true)
+ }
+
+ function closeComposer(): void {
+ setComposerOpen(false)
+ }
+
+ function switchComposerMode(mode: 'reply' | 'note'): void {
+ setComposerMode(mode)
+ setComposerError(null)
+ setSendFailed(false)
+ }
+
+ function sendReply(): void {
+ const el = replyBodyRef.current
+ const text = el !== null ? normalizedInnerText(el) : ''
+ if (text.trim().length < 1) {
+ setComposerError("Write a reply first — the message can't be empty.")
+ return
+ }
+ if (text.length > MAX_REPLY_LENGTH) {
+ setComposerError('Replies are limited to 5,000 characters.')
+ return
+ }
+ setComposerError(null)
+ setSendFailed(false)
+ const html = el !== null && hasRichFormatting(el) ? el.innerHTML : undefined
+ const wasClosedOrSpam = status === 'closed' || status === 'spam'
+ startTransition(async () => {
+ const result = await sendReplyAction(conversation.id, text, idempotencyKey.current, html)
+ if (result.ok) {
+ clearDraft(conversation.id)
+ replyDraftTextRef.current = ''
+ replyBodyHtmlRef.current = null
+ if (el !== null) el.innerHTML = ''
+ setReplyTextLength(0)
+ idempotencyKey.current = crypto.randomUUID()
+ setComposerOpen(false)
+ if (wasClosedOrSpam) {
+ setLocalStatus('active')
+ showToast({
+ title: 'Reply sent — conversation reopened',
+ detail: 'Replying to a closed conversation reopens it.',
+ })
+ } else {
+ showToast({ title: 'Reply sent' })
+ }
+ router.refresh()
+ return
+ }
+ // Honest failure copy per the design system's content rules; the
+ // draft is preserved in every outcome.
+ if (result.code === 'send_failed') {
+ setSendFailed(true)
+ return
+ }
+ if (result.code === 'retry_in_progress') {
+ setComposerError('This reply is already being sent. Give it a moment, then try again.')
+ return
+ }
+ if (result.code === 'validation_failed') {
+ // The original attempt never reached the send path — a replay key
+ // has nothing to safely replay, so mint a fresh one.
+ idempotencyKey.current = crypto.randomUUID()
+ }
+ setComposerError(result.message ?? 'Something went wrong. The draft is preserved.')
+ })
+ }
+
+ function sendNote(): void {
+ if (noteDraft.trim().length < 1) {
+ setComposerError("Write a note first — the note can't be empty.")
+ return
+ }
+ if (noteDraft.length > MAX_REPLY_LENGTH) {
+ setComposerError('Notes are limited to 5,000 characters.')
+ return
+ }
+ setComposerError(null)
+ startTransition(async () => {
+ const result = await postNoteAction(conversation.id, noteDraft)
+ if (result.ok) {
+ setNoteDraft('')
+ setComposerOpen(false)
+ showToast({ title: 'Note added', detail: 'Visible to Agents only — never emailed.' })
+ router.refresh()
+ return
+ }
+ setComposerError(result.message ?? 'Something went wrong.')
+ })
+ }
+
+ function sendActive(): void {
+ if (composerMode === 'reply') sendReply()
+ else sendNote()
+ }
+
+ // The screen's own shortcuts: j/k conversation nav, r/n open the
+ // composer, ⌘/Ctrl+↵ sends, Escape cascades (original-message modal → any
+ // open menu → composer, draft kept → back to the inbox). The shortcuts
+ // overlay's own Escape handler doesn't stop propagation, so this skips
+ // entirely while it's open — otherwise one Escape press would both close
+ // the overlay AND cascade through this screen's own close logic.
+ //
+ // Kept in a ref (the "latest closure" pattern) rather than the effect's
+ // dependency array: nearly every piece of UI state on this screen affects
+ // this handler, and the DOM listener itself doesn't need to churn on each
+ // one — only the closure it calls does.
+ const onKeyDownRef = useRef<(event: KeyboardEvent) => void>(() => {})
+ onKeyDownRef.current = (event: KeyboardEvent) => {
+ if (isShortcutsOverlayOpen) return
+
+ if ((event.metaKey || event.ctrlKey) && event.key === 'Enter' && composerOpen) {
+ event.preventDefault()
+ sendActive()
+ return
+ }
+
+ if (event.key === 'Escape') {
+ if (originalMessage !== null) {
+ setOriginalMessage(null)
+ return
+ }
+ if (
+ tagsMenuOpen ||
+ assigneeMenuOpen ||
+ statusMenuOpen ||
+ moreMenuOpen ||
+ openMessageMenuId !== null
+ ) {
+ setTagsMenuOpen(false)
+ setAssigneeMenuOpen(false)
+ setStatusMenuOpen(false)
+ setMoreMenuOpen(false)
+ setOpenMessageMenuId(null)
+ return
+ }
+ if (composerOpen) {
+ closeComposer()
+ return
+ }
+ router.push('/inbox/open')
+ return
+ }
+
+ const target = event.target as HTMLElement | null
+ const typing =
+ target !== null &&
+ (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable)
+ if (typing) return
+
+ if (event.key === 'j' || event.key === 'k') {
+ const targetId = event.key === 'j' ? position?.nextId : position?.prevId
+ if (targetId != null) {
+ event.preventDefault()
+ router.push(`/conversations/${targetId}`)
+ }
+ return
+ }
+ if (event.key === 'r') {
+ event.preventDefault()
+ openComposer('reply')
+ return
+ }
+ if (event.key === 'n') {
+ event.preventDefault()
+ openComposer('note')
+ }
+ }
+
+ useEffect(() => {
+ function onKeyDown(event: KeyboardEvent): void {
+ onKeyDownRef.current(event)
+ }
+ window.addEventListener('keydown', onKeyDown)
+ return () => window.removeEventListener('keydown', onKeyDown)
+ }, [])
+
+ function changeStatus(next: ConversationStatus): void {
+ setStatusMenuOpen(false)
+ startTransition(async () => {
+ const result = await setStatusAction(conversation.id, next)
+ if (result.ok) {
+ setLocalStatus(next)
+ showToast({ title: `Marked ${next}` })
+ router.refresh()
+ } else {
+ // Surface the failure like tags/assignee do — never leave a status
+ // change silently dropped.
+ showToast({ title: "Couldn't update the conversation", detail: 'Please try again.' })
+ }
+ })
+ }
+
+ async function updateTags(nextTags: string[]): Promise {
+ const previous = tags
+ setTags(nextTags)
+ const result = await putTagsAction(conversation.id, nextTags)
+ if (!result.ok) {
+ setTags(previous)
+ showToast({ title: "Couldn't update the tags", detail: 'Please try again.' })
+ }
+ }
+
+ function addTagFromInput(): void {
+ const value = tagInput.trim().toLowerCase()
+ if (value.length === 0 || value.length > MAX_TAG_LENGTH || tags.includes(value)) return
+ setTagInput('')
+ void updateTags([...tags, value])
+ }
+
+ function onTagInputKeyDown(event: { key: string; preventDefault: () => void }): void {
+ if (event.key !== 'Enter') return
+ event.preventDefault()
+ addTagFromInput()
+ }
+
+ async function updateAssignee(next: 'me' | null): Promise {
+ const previous = assignee
+ setAssigneeMenuOpen(false)
+ setAssignee(next)
+ const result = await putAssigneeAction(conversation.id, next)
+ if (!result.ok) {
+ setAssignee(previous)
+ showToast({ title: "Couldn't update the assignee", detail: 'Please try again.' })
+ }
+ }
+
+ function onDeleteClick(): void {
+ if (!deleteArmed) {
+ setDeleteArmed(true)
+ deleteDisarmTimer.current = setTimeout(() => setDeleteArmed(false), DELETE_DISARM_MS)
+ return
+ }
+ if (deleteDisarmTimer.current !== null) clearTimeout(deleteDisarmTimer.current)
+ setDeleteArmed(false)
+ startTransition(async () => {
+ const result = await deleteConversationAction(conversation.id)
+ if (result.ok) {
+ showToast({ title: 'Conversation deleted' })
+ router.push('/inbox/unassigned')
+ }
+ })
+ }
+
+ function toggleFollowing(): void {
+ setMoreMenuOpen(false)
+ const next = !following
+ setFollowing(next)
+ showToast({ title: next ? 'Following conversation' : 'Unfollowed conversation' })
+ }
+
+ const customerName = nameFromEmail(conversation.customerEmail)
+ const starred = isStarred(conversation.id)
+
+ // sameSpeakerAsPrev compares CHRONOLOGICALLY adjacent messages — computed
+ // here, before the list is reversed for newest-first presentation. The
+ // API itself stays oldest-first (this is a presentation-layer reorder).
+ const threadsWithMeta = conversation.threads.map((thread, index) => {
+ const prev = conversation.threads[index - 1]
+ return {
+ thread,
+ sameSpeakerAsPrev: prev !== undefined && prev.direction === thread.direction,
+ }
+ })
+ const threadsNewestFirst = [...threadsWithMeta].reverse()
+
+ return (
+
+
+ {/* Reply mode hosts the close button on the format-toolbar row
+ below (design: icons ... caption ... ×); Note mode has no
+ format row, so its close button stays up here. */}
+ {composerMode === 'note' && (
+
+
+
+ )}
+
+
+ {composerMode === 'note' && (
+
+ Internal note — visible to Agents only, never emailed to the customer.
+
+ Nothing reached the customer. The draft is preserved.
+
+
+
+
+
+ )}
+
+ {composerMode === 'reply' ? (
+ <>
+
+
+
+
+
+
+
+ Formatting is sent as HTML alongside plain text
+
+
+
+
+
+
+ {replyTextLength === 0 && (
+
+ Reply to {customerName}…
+
+ )}
+ {/* biome-ignore lint/a11y/useSemanticElements: rich-text
+ formatting (bold/italic/list/link via execCommand)
+ requires a contenteditable element — a