@agenticmail/api 0.7.8 → 0.7.11

package/public/js/api.js

@@ -0,0 +1,25 @@
+// Tiny fetch wrapper that injects the auth header. Every API call goes
+// through here so the master key (or per-agent key) is applied
+// consistently and errors surface as plain Error throws.
+import { state, API_URL } from './state.js';
+
+export async function apiGet(path, opts = {}) {
+  const r = await fetch(`${API_URL}/api/agenticmail${path}`, {
+    headers: { Authorization: `Bearer ${opts.agentKey ?? state.masterKey}` },
+  });
+  if (!r.ok) throw new Error(`${r.status} ${path}`);
+  return await r.json();
+}
+
+export async function apiPost(path, body, opts = {}) {
+  const r = await fetch(`${API_URL}/api/agenticmail${path}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${opts.agentKey ?? state.masterKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!r.ok) throw new Error(`${r.status} ${path}`);
+  return await r.json();
+}

package/public/js/app.js

@@ -0,0 +1,228 @@
+// Main entry — wires the modules, runs auth, and drives the
+// hash-based router.
+//
+// Routes:
+//   #/inbox    → folder list view (active folder lives in state)
+//   #/m/:uid   → single-message view
+import { state, API_URL } from './state.js';
+import { toast } from './utils.js';
+import { apiGet } from './api.js';
+import { isBridgeAgent } from './avatar.js';
+import { renderProfile, toggleProfileMenu, closeProfileMenu } from './profile.js';
+import { renderSidebar } from './sidebar.js';
+import { loadList, renderList, clearSearch } from './list-view.js';
+import { openMessage } from './message-view.js';
+import { populateComposeFrom, openCompose, closeCompose, sendCompose } from './compose.js';
+import { subscribeToAllAgents, maybeRequestNotificationPermission } from './sse.js';
+import { icon } from './icons.js';
+
+// Hydrate every `data-icon="name"` placeholder in the static HTML
+// with the corresponding inline SVG. Done once on load so we don't
+// keep emojis around as fallback.
+function hydrateIcons(root = document) {
+  root.querySelectorAll('[data-icon]').forEach(el => {
+    const name = el.dataset.icon;
+    const size = el.dataset.iconSize ? Number(el.dataset.iconSize) : undefined;
+    el.innerHTML = icon(name, size ? { size } : {});
+  });
+}
+hydrateIcons();
+
+// ─── Auth ────────────────────────────────────────────────────────────
+const authApiUrl = document.getElementById('auth-api-url');
+if (authApiUrl) authApiUrl.textContent = API_URL;
+
+async function signIn() {
+  const key = document.getElementById('auth-key').value.trim();
+  if (!key) return showAuthErr('Master key is required.');
+  try {
+    const resp = await fetch(`${API_URL}/api/agenticmail/accounts`, {
+      headers: { Authorization: `Bearer ${key}` },
+    });
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    localStorage.setItem('agenticmail.masterKey', key);
+    state.masterKey = key;
+    document.getElementById('auth').style.display = 'none';
+    document.getElementById('app').style.display = 'grid';
+    await bootstrap();
+  } catch (err) {
+    showAuthErr(`Sign-in failed: ${err.message}. Check the key and that the API is running on ${API_URL}.`);
+  }
+}
+function showAuthErr(msg) {
+  const e = document.getElementById('auth-err');
+  e.textContent = msg; e.style.display = 'block';
+}
+function signOut() {
+  localStorage.removeItem('agenticmail.masterKey');
+  location.reload();
+}
+
+document.getElementById('auth-submit').addEventListener('click', signIn);
+document.getElementById('auth-key').addEventListener('keydown', e => {
+  if (e.key === 'Enter') signIn();
+});
+document.getElementById('signout-link').addEventListener('click', signOut);
+
+// ─── Bootstrap ───────────────────────────────────────────────────────
+async function bootstrap() {
+  try {
+    const data = await apiGet('/accounts');
+    const all = (data.agents ?? data ?? []);
+    // Bridge agent pinned to top of switcher; everyone else alphabetical.
+    all.sort((a, b) => {
+      const aBridge = isBridgeAgent(a) ? 0 : 1;
+      const bBridge = isBridgeAgent(b) ? 0 : 1;
+      if (aBridge !== bBridge) return aBridge - bBridge;
+      return a.name.localeCompare(b.name);
+    });
+    state.agents = all;
+    const initial = state.agents.find(isBridgeAgent) ?? state.agents[0];
+    if (initial) await selectAgent(initial);
+    renderProfile();
+    populateComposeFrom();
+    subscribeToAllAgents();
+    maybeRequestNotificationPermission();
+    if (!location.hash) location.hash = '#/inbox';
+    else route();
+  } catch (err) {
+    toast(`Failed to load agents: ${err.message}`, true);
+  }
+}
+
+async function selectAgent(agent) {
+  state.selectedAgent = agent;
+  state.selectedUid = null;
+  state.currentMessage = null;
+  renderSidebar(onFolderSelect);
+  renderProfile();
+  await loadList(agent, state.selectedFolder);
+}
+
+function onFolderSelect(folder) {
+  state.selectedFolder = folder;
+  renderSidebar(onFolderSelect);
+  location.hash = '#/inbox';   // any folder uses the list route
+  if (state.selectedAgent) loadList(state.selectedAgent, folder);
+  // On mobile (the only viewport where the sidebar is over-canvas),
+  // close it after a folder pick so the user sees the list.
+  document.getElementById('main')?.classList.remove('sidebar-open');
+}
+
+// ─── Hash router ─────────────────────────────────────────────────────
+function route() {
+  const hash = location.hash || '#/inbox';
+  const msgMatch = hash.match(/^#\/m\/(\d+)$/);
+  if (msgMatch) {
+    openMessage(Number(msgMatch[1]));
+  } else if (state.selectedAgent) {
+    loadList(state.selectedAgent, state.selectedFolder);
+  }
+}
+window.addEventListener('hashchange', route);
+
+// ─── Top bar wiring ──────────────────────────────────────────────────
+// Hamburger toggles the sidebar on mobile. On desktop the sidebar
+// is always visible; the class only changes anything below 800 px,
+// where the CSS slides it off-canvas by default.
+function toggleSidebar() {
+  const main = document.getElementById('main');
+  main?.classList.toggle('sidebar-open');
+}
+document.getElementById('menu-btn').addEventListener('click', toggleSidebar);
+document.getElementById('sidebar-backdrop').addEventListener('click', () => {
+  document.getElementById('main')?.classList.remove('sidebar-open');
+});
+
+document.getElementById('refresh-btn').addEventListener('click', async () => {
+  if (state.selectedAgent) {
+    await loadList(state.selectedAgent, state.selectedFolder);
+    toast('Refreshed.');
+  }
+});
+document.getElementById('compose-btn').addEventListener('click', openCompose);
+document.getElementById('profile-btn').addEventListener('click', toggleProfileMenu);
+document.getElementById('profile-menu').addEventListener('click', e => {
+  e.stopPropagation();
+  const item = e.target.closest('.profile-menu-item');
+  if (!item) return;
+  const agent = state.agents.find(a => a.id === item.dataset.id);
+  if (agent && agent.id !== state.selectedAgent?.id) selectAgent(agent);
+  closeProfileMenu();
+});
+document.addEventListener('click', e => {
+  const menu = document.getElementById('profile-menu');
+  const btn = document.getElementById('profile-btn');
+  if (!menu || !btn) return;
+  if (!menu.contains(e.target) && !btn.contains(e.target)) closeProfileMenu();
+});
+
+// ─── Compose modal wiring ────────────────────────────────────────────
+document.getElementById('compose-close').addEventListener('click', closeCompose);
+document.getElementById('compose-cancel').addEventListener('click', closeCompose);
+document.getElementById('compose-send').addEventListener('click', sendCompose);
+document.getElementById('compose-bg').addEventListener('click', e => {
+  if (e.target.id === 'compose-bg') closeCompose();
+});
+
+// ─── Search (debounced, Esc clears) ─────────────────────────────────
+let searchDebounce = null;
+const searchInput = document.getElementById('search-input');
+searchInput.addEventListener('input', e => {
+  const v = e.target.value;
+  e.target.classList.toggle('has-query', v.length > 0);
+  document.getElementById('search-clear').classList.toggle('show', v.length > 0);
+  if (searchDebounce) clearTimeout(searchDebounce);
+  searchDebounce = setTimeout(() => {
+    state.searchQuery = v;
+    renderList();
+  }, 80);
+});
+searchInput.addEventListener('keydown', e => {
+  if (e.key === 'Escape') { e.preventDefault(); clearSearch(); }
+});
+document.getElementById('search-clear').addEventListener('click', clearSearch);
+
+// ─── Keyboard shortcuts (Gmail-style) ───────────────────────────────
+//   r  refresh current inbox
+//   c  compose new
+//   /  focus the search box
+//
+// IMPORTANT: every shortcut bails when ANY modifier key is held
+// (Cmd / Ctrl / Alt / Meta) — otherwise Cmd+C "copy" was opening
+// the compose modal, Cmd+R was overriding browser refresh, etc.
+// Plain unmodified single-key shortcuts only.
+document.addEventListener('keydown', e => {
+  if (document.getElementById('compose-bg').style.display !== 'none') return;
+  if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') return;
+  if (e.metaKey || e.ctrlKey || e.altKey) return;  // never hijack OS shortcuts
+  if (e.key === 'r') document.getElementById('refresh-btn').click();
+  else if (e.key === 'c') openCompose();
+  else if (e.key === '/') {
+    e.preventDefault();
+    searchInput.focus();
+  }
+});
+
+// ─── Boot ───────────────────────────────────────────────────────────
+(() => {
+  // Accept `?key=...` from the CLI's `agenticmail web` command, then
+  // strip it from the URL so it doesn't leak via Referer / history /
+  // screen shares. Safe because the URL is loopback-only.
+  try {
+    const params = new URL(location.href).searchParams;
+    const urlKey = params.get('key');
+    if (urlKey) {
+      localStorage.setItem('agenticmail.masterKey', urlKey);
+      history.replaceState({}, '', location.pathname + location.hash);
+    }
+  } catch {}
+
+  const saved = localStorage.getItem('agenticmail.masterKey');
+  if (saved) {
+    state.masterKey = saved;
+    document.getElementById('auth').style.display = 'none';
+    document.getElementById('app').style.display = 'grid';
+    bootstrap();
+  }
+})();

package/public/js/avatar.js

@@ -0,0 +1,43 @@
+// Agent identity + avatar helpers.
+//
+// The bridge agent (default name "claudecode") is the host's identity
+// inside AgenticMail. We render it with the OFFICIAL Claude starburst
+// mark (sourced from the public Wikipedia SVG, served as a static
+// asset under /branding/claude-mark.svg) and a green verified-tick so
+// the host inbox is recognisable at a glance vs. teammate sub-agents.
+import { escapeHtml } from './utils.js';
+import { icon } from './icons.js';
+
+// Official Claude mark, served as a static asset under /branding/.
+// Using <img src=...> rather than inlining the path keeps the SVG
+// out of every avatar render and lets the browser cache the asset.
+const CLAUDE_MARK_URL = '/branding/claude-mark.svg';
+
+export function isBridgeAgent(agent) {
+  if (!agent) return false;
+  const name = (agent.name ?? '').toLowerCase();
+  const role = (agent.role ?? '').toLowerCase();
+  return name === 'claudecode' || name === 'claude' || role === 'bridge';
+}
+
+// Deterministic colour per agent name — keeps teammate colours stable
+// across sessions and reloads.
+const AVATAR_PALETTE = [
+  '#ec4899', '#8b5cf6', '#3b82f6', '#06b6d4',
+  '#10b981', '#f59e0b', '#ef4444', '#84cc16',
+];
+function avatarColorFor(name) {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) hash = (hash * 31 + name.charCodeAt(i)) >>> 0;
+  return AVATAR_PALETTE[hash % AVATAR_PALETTE.length];
+}
+
+export function avatarHtml(agent, size = '') {
+  const cls = `avatar ${size}`.trim();
+  if (isBridgeAgent(agent)) {
+    return `<span class="${cls} avatar-host"><img src="${CLAUDE_MARK_URL}" alt="Claude" class="avatar-img" /><span class="avatar-check">${icon('check', { size: 10 })}</span></span>`;
+  }
+  const initial = (agent.name ?? '?').slice(0, 1).toUpperCase();
+  const color = avatarColorFor(agent.name ?? '');
+  return `<span class="${cls}" style="background:${color}">${escapeHtml(initial)}</span>`;
+}

package/public/js/compose.js

@@ -0,0 +1,81 @@
+// Gmail-style bottom-right compose popup. Handles both new-message
+// and reply flows. `wake` is the AgenticMail selective-wake hint.
+import { state } from './state.js';
+import { escapeHtml, toast } from './utils.js';
+import { apiPost } from './api.js';
+import { loadList } from './list-view.js';
+
+export function populateComposeFrom() {
+  const sel = document.getElementById('compose-from');
+  sel.innerHTML = state.agents
+    .map(a => `<option value="${a.id}">${escapeHtml(a.name)} &lt;${escapeHtml(a.email)}&gt;</option>`)
+    .join('');
+}
+
+export function openCompose() {
+  state.composeReplyContext = null;
+  document.getElementById('compose-title').textContent = 'New message';
+  if (state.selectedAgent) document.getElementById('compose-from').value = state.selectedAgent.id;
+  ['compose-to', 'compose-cc', 'compose-wake', 'compose-subject', 'compose-body']
+    .forEach(id => { document.getElementById(id).value = ''; });
+  showModal();
+  setTimeout(() => document.getElementById('compose-to').focus(), 50);
+}
+
+export function openReply(replyAll) {
+  if (!state.currentMessage) return;
+  const msg = state.currentMessage;
+  state.composeReplyContext = { uid: msg.uid, agent: state.selectedAgent, replyAll };
+  document.getElementById('compose-title').textContent =
+    `Reply${replyAll ? ' all' : ''}: ${msg.subject ?? '(no subject)'}`;
+  document.getElementById('compose-from').value = state.selectedAgent.id;
+  const fromAddr = msg.from?.[0]?.address ?? '';
+  let toAddr = fromAddr;
+  if (replyAll) {
+    const all = [fromAddr, ...(msg.to ?? []).map(a => a.address), ...(msg.cc ?? []).map(a => a.address)]
+      .filter(Boolean).filter((v, i, a) => a.indexOf(v) === i)
+      .filter(addr => addr !== state.selectedAgent.email);
+    toAddr = all.join(', ');
+  }
+  document.getElementById('compose-to').value = toAddr;
+  document.getElementById('compose-cc').value = '';
+  document.getElementById('compose-wake').value = '';
+  document.getElementById('compose-subject').value =
+    (msg.subject ?? '').startsWith('Re:') ? msg.subject : `Re: ${msg.subject ?? ''}`;
+  const quoted = (msg.text ?? '').split('\n').map(l => `> ${l}`).join('\n');
+  const stub = `\n\nOn ${msg.date}, ${fromAddr} wrote:\n${quoted}`;
+  document.getElementById('compose-body').value = stub;
+  showModal();
+  setTimeout(() => document.getElementById('compose-body').focus(), 50);
+}
+
+export function closeCompose() {
+  document.getElementById('compose-bg').style.display = 'none';
+}
+
+function showModal() {
+  document.getElementById('compose-bg').style.display = 'flex';
+}
+
+export async function sendCompose() {
+  const agentId = document.getElementById('compose-from').value;
+  const agent = state.agents.find(a => a.id === agentId);
+  if (!agent) return toast('Pick an agent to send from.', true);
+  const to = document.getElementById('compose-to').value.trim();
+  const subject = document.getElementById('compose-subject').value.trim();
+  const text = document.getElementById('compose-body').value;
+  const cc = document.getElementById('compose-cc').value.trim();
+  const wakeRaw = document.getElementById('compose-wake').value.trim();
+  if (!to || !subject) return toast('To and Subject are required.', true);
+  const body = { to, subject, text };
+  if (cc) body.cc = cc;
+  if (wakeRaw) body.wake = wakeRaw.split(',').map(s => s.trim()).filter(Boolean);
+  try {
+    await apiPost('/mail/send', body, { agentKey: agent.apiKey });
+    closeCompose();
+    toast('Sent.');
+    if (state.selectedAgent?.id === agent.id) await loadList(agent, state.selectedFolder);
+  } catch (err) {
+    toast(`Send failed: ${err.message}`, true);
+  }
+}

package/public/js/icons.js

@@ -0,0 +1,56 @@
+// Tiny SVG icon library — inline so there are no extra HTTP requests
+// and icons inherit `color` via `fill="currentColor"`.
+//
+// Paths are 24x24 Material-Symbols-style outlines. Single-source so
+// every emoji in the UI can be swapped for a proper vector glyph.
+//
+// Usage:
+//   icon('inbox')                 // 24x24 default
+//   icon('search', { size: 20 })  // override pixel size
+//   icon('star', { class: 'starred' })  // extra class on the <svg>
+
+const PATHS = {
+  // ─── Navigation / chrome ─────────────────────────────────────────
+  menu:    'M3 6h18v2H3V6zm0 5h18v2H3v-2zm0 5h18v2H3v-2z',
+  search:  'M15.5 14h-.79l-.28-.27a6.5 6.5 0 1 0-.7.7l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0A4.5 4.5 0 1 1 14 9.5 4.5 4.5 0 0 1 9.5 14z',
+  refresh: 'M17.65 6.35A7.95 7.95 0 0 0 12 4a8 8 0 1 0 7.73 10h-2.08A6 6 0 1 1 12 6a5.88 5.88 0 0 1 4.22 1.78L13 11h7V4l-2.35 2.35z',
+  close:   'M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z',
+  back:    'M20 11H7.83l5.59-5.59L12 4l-8 8 8 8 1.41-1.41L7.83 13H20v-2z',
+  caret:   'M7 10l5 5 5-5H7z',
+
+  // ─── Actions ────────────────────────────────────────────────────
+  compose:    'M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25zM20.71 7.04a1 1 0 0 0 0-1.41l-2.34-2.34a1 1 0 0 0-1.41 0l-1.83 1.83 3.75 3.75 1.83-1.83z',
+  send:       'M2.01 21 23 12 2.01 3 2 10l15 2-15 2z',
+  reply:      'M10 9V5l-7 7 7 7v-4.1c5 0 8.5 1.6 11 5.1-1-5-4-10-11-11z',
+  replyAll:   'M7 8V5l-7 7 7 7v-3l-4-4 4-4zm6 1V5l-7 7 7 7v-4.1c5 0 8.5 1.6 11 5.1-1-5-4-10-11-11z',
+  mailUnread: 'M20 4H4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2zm0 4-8 5-8-5V6l8 5 8-5v2z',
+  attachment: 'M16.5 6v11.5a4 4 0 0 1-8 0V5a2.5 2.5 0 0 1 5 0v10.5a1 1 0 0 1-2 0V6H10v9.5a2.5 2.5 0 0 0 5 0V5a4 4 0 0 0-8 0v12.5a5.5 5.5 0 0 0 11 0V6h-1.5z',
+
+  // ─── Stars ──────────────────────────────────────────────────────
+  starOutline: 'M22 9.24l-7.19-.62L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21 12 17.27 18.18 21l-1.64-7.03L22 9.24zM12 15.4l-3.76 2.27 1-4.28-3.32-2.88 4.38-.38L12 6.1l1.71 4.04 4.38.38-3.32 2.88 1 4.28L12 15.4z',
+  starFilled:  'M12 17.27 18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21 12 17.27z',
+
+  // ─── Sidebar folders ────────────────────────────────────────────
+  inbox:   'M19 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2zm0 12h-4c0 1.66-1.35 3-3 3s-3-1.34-3-3H5V5h14v10z',
+  sent:    'M2.01 21 23 12 2.01 3 2 10l15 2-15 2z',
+  drafts:  'M19 3H4.99c-1.11 0-1.98.9-1.98 2L3 19a2 2 0 0 0 2 2h14c1.1 0 2-.9 2-2v-7l-8 5-8-5V5l8 5 8-5v2h2V5a2 2 0 0 0-2-2z',
+  allMail: 'M22 4h-2v9.38l-2.79-2.79L16 12l4 4 4-4-1.21-1.21L22 13.38V4zM4 4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8h-2v10H4V6h12V4H4z',
+  spam:    'M12 2 1 21h22L12 2zm1 14h-2v-2h2v2zm0-4h-2V8h2v4z',
+  trash:   'M6 19a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2V7H6v12zM19 4h-3.5l-1-1h-5l-1 1H5v2h14V4z',
+
+  // ─── Branding glyph (bow) ───────────────────────────────────────
+  // Stylised pink bow, used in place of the 🎀 emoji.
+  bow:     'M12 12c-2-3-5-5-8-5-1 0-2 1-2 2s1 2 2 2c2 0 4 1 5 2-1 1-3 2-5 2-1 0-2 1-2 2s1 2 2 2c3 0 6-2 8-5 2 3 5 5 8 5 1 0 2-1 2-2s-1-2-2-2c-2 0-4-1-5-2 1-1 3-2 5-2 1 0 2-1 2-2s-1-2-2-2c-3 0-6 2-8 5zm0 2a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3z',
+
+  // ─── Status / dots ──────────────────────────────────────────────
+  dot:     'M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8z',
+  check:   'M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41L9 16.17z',
+};
+
+export function icon(name, opts = {}) {
+  const path = PATHS[name];
+  if (!path) return '';
+  const size = opts.size ?? 20;
+  const cls = `icon-svg ${opts.class ?? ''}`.trim();
+  return `<svg class="${cls}" width="${size}" height="${size}" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="${path}"/></svg>`;
+}

package/public/js/list-view.js

@@ -0,0 +1,160 @@
+// Gmail-style message-list view. One row per email; click to open in
+// the message view. Search filters and inline highlighting run here.
+import { state } from './state.js';
+import { escapeHtml, toast } from './utils.js';
+import { formatDate } from './time.js';
+import { parseSearch, matchesSearch, highlightTerm } from './search.js';
+import { apiGet } from './api.js';
+import { FOLDERS } from './sidebar.js';
+import { icon } from './icons.js';
+
+/**
+ * Defensive flag check. The API's IMAP layer returns `flags` as an
+ * array of strings most of the time (`['\\Seen', '\\Flagged']`) but
+ * some envelopes come back with a Set-like serialisation or even an
+ * object map. Without this guard, calling `.includes()` on a non-
+ * array crashed the list with "(m.flags ?? []).includes is not a
+ * function". Coerce everything we don't recognise to an empty list.
+ */
+function flagsHas(flags, name) {
+  if (Array.isArray(flags)) return flags.includes(name);
+  if (flags && typeof flags === 'object') {
+    // `{Seen: true, Flagged: false}` shape — try both with and
+    // without the leading backslash since callers can mean either.
+    const key = name.replace(/^\\/, '');
+    return flags[name] === true || flags[key] === true;
+  }
+  return false;
+}
+
+// Map sidebar folder ids to the actual IMAP folder names the API
+// expects on `/mail/folders/:folder`. `inbox` is special — the API
+// has a dedicated `/mail/inbox` endpoint with extra enrichment, so
+// we use that. Other folders go through the generic listing.
+//
+// Stalwart uses the standard IMAP names: INBOX, Sent, Drafts, Junk
+// Mail (a.k.a. "Spam"), Trash. We use the canonical IMAP capitalisation.
+const FOLDER_TO_IMAP = {
+  inbox:   { endpoint: '/mail/inbox' },
+  sent:    { endpoint: '/mail/folders/Sent' },
+  drafts:  { endpoint: '/mail/folders/Drafts' },
+  spam:    { endpoint: '/mail/folders/Junk%20Mail' },
+  trash:   { endpoint: '/mail/folders/Trash' },
+  all:     { endpoint: '/mail/folders/All%20Mail' },
+  // Starred is not a folder — it's the IMAP \Flagged flag, surfaced
+  // by client-side filtering over the inbox listing (Gmail-style).
+  starred: { endpoint: '/mail/inbox', clientFilter: 'flagged' },
+};
+
+export async function loadList(agent, folder) {
+  const root = document.getElementById('content');
+  root.innerHTML = `
+    <div class="list-header">
+      <span class="folder-title">${escapeHtml(folderTitle(folder))}</span>
+      <span class="count-text" id="list-count"></span>
+    </div>
+    <div class="list-rows" id="list-rows"><div class="empty">Loading…</div></div>
+  `;
+  const route = FOLDER_TO_IMAP[folder] ?? FOLDER_TO_IMAP.inbox;
+  try {
+    const sep = route.endpoint.includes('?') ? '&' : '?';
+    const data = await apiGet(`${route.endpoint}${sep}limit=50&offset=0`, { agentKey: agent.apiKey });
+    state.messages = data.messages ?? [];
+    renderList();
+  } catch (err) {
+    // Empty folder is a normal state; "no such folder" lands here
+    // too. Show a friendly empty message rather than a raw HTTP error.
+    const msg = String(err.message ?? err);
+    document.getElementById('list-rows').innerHTML = msg.includes('404')
+      ? `<div class="empty">${escapeHtml(folderTitle(folder))} is empty.</div>`
+      : `<div class="empty">Failed to load: ${escapeHtml(msg)}</div>`;
+  }
+}
+
+function folderTitle(folder) {
+  const f = FOLDERS.find(x => x.id === folder);
+  return f ? f.label : 'Inbox';
+}
+
+export function renderList() {
+  const root = document.getElementById('list-rows');
+  if (!root) return;
+  const q = state.searchQuery.trim();
+  const filters = q ? parseSearch(q) : null;
+  let filtered = filters ? state.messages.filter(m => matchesSearch(m, filters)) : state.messages;
+
+  // Client-side folder filtering for the folders the API doesn't
+  // distinguish for us yet. Starred uses the IMAP \Flagged flag.
+  // Flags may come back as an array OR an object map ({Seen: true})
+  // depending on the IMAP path — always coerce before .includes().
+  if (state.selectedFolder === 'starred') {
+    filtered = filtered.filter(m => flagsHas(m.flags, '\\Flagged'));
+  }
+
+  const hlTerm = filters?.subject || filters?.from || filters?.text || '';
+
+  // Footer count + search hint
+  const hintEl = document.getElementById('search-hint');
+  if (q && hintEl) {
+    hintEl.textContent = `${filtered.length}/${state.messages.length}`;
+    hintEl.classList.add('show');
+  } else if (hintEl) {
+    hintEl.classList.remove('show');
+  }
+  const countEl = document.getElementById('list-count');
+  if (countEl) countEl.textContent = `${filtered.length} of ${state.messages.length}`;
+
+  if (filtered.length === 0) {
+    root.innerHTML = q
+      ? `<div class="empty">No messages match "${escapeHtml(q)}".</div>`
+      : `<div class="empty"><div class="big">${icon('inbox', { size: 48 })}</div>Nothing here yet.</div>`;
+    return;
+  }
+
+  root.innerHTML = filtered.map(m => {
+    const unread = !flagsHas(m.flags, '\\Seen');
+    const starred = flagsHas(m.flags, '\\Flagged');
+    const fromAddr = m.from?.[0]?.address ?? '?';
+    const fromName = m.from?.[0]?.name || fromAddr;
+    const subject = m.subject ?? '(no subject)';
+    const date = formatDate(m.date);
+    const starIcon = icon(starred ? 'starFilled' : 'starOutline', { size: 18 });
+    return `
+      <div class="list-row ${unread ? 'unread' : ''}" data-uid="${m.uid}">
+        <span class="star ${starred ? 'starred' : ''}" data-action="star">${starIcon}</span>
+        <span class="dot"></span>
+        <span class="from">${highlightTerm(fromName, hlTerm)}</span>
+        <span class="subject-cell">
+          <span class="subject">${highlightTerm(subject, hlTerm)}</span>
+          <span class="preview">${highlightTerm((m.preview ?? '').slice(0, 160), hlTerm)}</span>
+        </span>
+        <span class="date">${escapeHtml(date)}</span>
+      </div>
+    `;
+  }).join('');
+
+  root.querySelectorAll('.list-row').forEach(el => {
+    el.addEventListener('click', (e) => {
+      if (e.target.closest('[data-action="star"]')) {
+        e.stopPropagation();
+        toast('Starring not wired through API yet.');
+        return;
+      }
+      const uid = Number(el.dataset.uid);
+      location.hash = `#/m/${uid}`;
+    });
+  });
+}
+
+export function clearSearch() {
+  const input = document.getElementById('search-input');
+  if (input) {
+    input.value = '';
+    input.classList.remove('has-query');
+  }
+  state.searchQuery = '';
+  document.getElementById('search-clear')?.classList.remove('show');
+  document.getElementById('search-hint')?.classList.remove('show');
+  renderList();
+  input?.focus();
+}