Omniscio

Supermail (part 2)

Three refinements to the inbox list (the first two apply to the dense single-line rows shown when the reading pane is off): Soft edge fade instead of a trailing "…". When a row's text is too long for one line it now fades out softly at the right edge rather than ending in a "…".

On this page

What it is

This is part 2 of the Supermail page. It carries the next stretch of the material on that page, moved here because a single page is capped at 40,000 characters.

Where to find it

Reach this part through Supermail — it lists every part and explains where the feature lives in the product. Everything below is reached from the same place.

Where it is wired in Omniscio

  • Sidebar registration: src/shared/integrations/supermail.ts (id: 'supermail', featureFlag: 'supermailEnabled') + src/renderer/src/integrations/ui-registry.ts (icon + lazy panel, panelOwnsLayout: true).
  • Virtual-project sentinel: SUPERMAIL_PLUGIN_PROJECT_ID = '__supermail__' in src/shared/virtual-project-ids.ts (the native __supermail__ form is used so the boot-loop seeder doesn't filter it out as a marketplace-plugin shim; the legacy __plugin_supermail__ rows were RETIRED by migration 20260619214747).
  • Sidebar hide-when-off gate: SIDEBAR_RENDER_GATES in src/renderer/src/stores/project-visibility.ts.
  • Panel host (Omniscio glue): src/renderer/src/features/supermail/SupermailPanel.tsx.
  • Settings toggle + search: sections/supermail/SupermailSettings.tsx (supermailEnabled + supermailInboxEnabled).
  • Find Email Quick Launch tab (Supermail mode): when supermailEnabled, that tab searches Supermail's backend (SUPERMAIL_SEARCH → hosted /search, JWT stays in Main: src/main/services/supermail/supermail-search-service.ts) and opens the pick in Supermail via SUPERMAIL_QUICK_FIND_OPEN, which REUSES the notification-open path (foreground the main window + emit PLUGIN_DEEPLINK /thread/<id> → openSupermailDeepLink) — no deep-link-router change and no vendored-UI edit. Handlers: src/main/ipc/supermail-quick-find-handlers.ts. See quick-launch-modal.md (the Find Email tab).
  • Protocol deep-link (omniscio://supermail/thread/<id>): a clickable/shareable link that opens a specific email. Unlike the quick-find/notification PLUGIN_DEEPLINK path above, this one DOES route through the generic deep-link parser + router (open-supermail-thread → openSupermailDeepLink), so it is also a recognized destination in GET /deep-link/resolve. The agentmc://supermail/auth sibling (the backend's primary auth scheme; omniscio:// accepted as an alias) stays a main-process OAuth-credential callback, never a navigation (both entry points gate on isSupermailAuthDeepLink). See deep-links.md.

How it behaves

Everything below is the behaviour, detail and edge cases that belong to this stretch of the Supermail page.

Inbox rows: soft edges + optional hover actions

Three refinements to the inbox list (the first two apply to the dense single-line rows shown when the reading pane is off):

  • Soft edge fade instead of a trailing "…". When a row's text is too long for one line it now fades out softly at the right edge rather than ending in a "…". The old ellipsis inherited the weight of whatever it cut — a bold subject gave heavy dots, the thin preview gave light ones — so the trailing dots looked inconsistent from row to row, and an essentially-empty row could still show them. The fade is uniform across read/unread and a row with no preview text shows nothing. Pure CSS (.sm-edge-fade, a background-agnostic mask-image in index.css), with a plain "…" fallback on engines without mask-image and the fade on the start edge under RTL.
  • "Show quick actions on hover" (Settings → General → Personalization, ON by default). The Mark Done / Remind Me buttons that appear on the right of a row on hover can be turned off for a cleaner list. Off hides the whole strip — the message time stays visible on hover (no blank edge) and the E (Done) / H (Remind me) keyboard shortcuts still work. It is the single discoverable switch; the finer-grained Settings → Reading → Toolbar buttons → Message rows controls (Mark done / Snooze) still apply on top of it. Device-local (supermail:row-hover-actions, features/settings/row-hover-actions-setting.ts). Invariants: .claude/memory/contracts/supermail-toolbar-controls-contract.md (master-row-hover-actions-toggle/row-single-line-truncation).
  • Archiving glides the row out instead of snapping shut. Mark Done / archive (and trash / mute) now fade the row while collapsing its height, so the rows below glide up to fill the gap — a subtle, quick exit rather than the row sliding hard off-screen and the list then snapping shut. Applies to every list row (dense and preview). Pure CSS (grid-template-rows: 1fr → 0fr + opacity in thread-list.tsx), reduced-motion-aware, and timed to finish exactly as the store removes the row (EXIT_ANIMATION_MS, kept in sync between thread-list.tsx and inbox-store-mutators.ts).
  • Snoozed rows show a clock + "Snoozed until <time>". A snoozed thread used to look identical to any other email — you could only tell from the Snoozed folder it listed under. Snoozed rows now carry a small clock glyph, with the wake time next to it (compact in the dense layout's date slot, full in the preview layout and on hover); when the wake time hasn't loaded yet only the clock shows, and once the time passes the marker disappears (the existing amber "woke up" reminder dot takes over). Pure rendering — the snooze store already tracked the wake time, rows just never read it (thread-list-item-icons.tsx, thread-row-format.ts).

Toolbar buttons (make each control optional)

Every action button in Supermail's toolbars is optional, so you can tighten the UI to exactly what you use. In Settings → Reading → Toolbar buttons each control has a three-way choice:

  • Shown (default) — the button is visible and its keyboard shortcut / Ctrl/Cmd+K command work, exactly as today.
  • Keyboard only — the button is hidden, but its keyboard shortcut and command-palette entry still work.
  • Off — the button is hidden AND its keyboard shortcut + command-palette entry are disabled.

Everything defaults to Shown, so an untouched install is unchanged; hiding buttons reflows the toolbars cleanly so the UI genuinely tightens up. The controls are grouped by where they live:

  • Reading pane — Reply, Filter like these, Focus mode.
  • Message rows — Star, Mark done, Snooze. Mark done + Snooze are per-row hover actions; the star is a persistent accent-coloured indicator at the row's left edge (fills when starred; a hollow outline reveals on hover / keyboard focus). The list is hotkey-first: row selection is the x key (there is no hover checkbox), the keyboard-focused row shows a bold accent "cursor" highlight (tint + inset ring), and a ? button in the inbox header opens the keyboard-shortcuts drawer (the same one the ? key opens). These same actions — plus Mark read/unread and "Filter messages like these" — are also on a right-click context menu for any message row; the menu respects these same per-action toggles (a control set to Off is dropped from the menu too).

A control governs an action, so one setting applies everywhere that button appears. The inbox toolbar's own view prefs (sort · group · unread) are NOT here — they moved to the always-present View options menu (above). And Compose + Search were removed entirely as toolbar buttons (reachable only via c / / + Ctrl/Cmd+K), so they are no longer listed either. The already-adjustable surfaces are left as-is: the bottom triage bar keeps its own "Customize actions", and the sidebar / reading pane / contact pane keep their own toggles.

Device-local (supermail:toolbar-controls), like the other display prefs, so it doesn't sync to the mail.jls.dev web client. "Off" hides the button, and with it the palette entry — but it does NOT disable the keyboard shortcut. The palette entry goes through each action's isAvailable, backed by isActionEnabled(); that helper's own doc says it "gates only those VISIBLE surfaces … it does NOT gate the keyboard shortcut, which always fires". app-shortcuts.tsx binds the handler unconditionally — a hidden button never disables its hotkey, never by touching the shared keyboard core. Store + settings UI: features/settings/toolbar-controls-setting.ts + features/settings/settings-page.tsx. Invariants: .claude/memory/contracts/supermail-toolbar-controls-contract.md.

The Supermail nav has two modes, driven by the in-app Settings → General → Personalization → "Show sidebar" toggle (Supermail's own settings page, not Omniscio's). The flag is the hidden field of features/layout/sidebar-store.ts (hidden = !pinned); it persists to supermail:nav-hidden and defaults to overlay mode so a fresh install matches Superhuman.

  • Pinned ("Show sidebar" on, hidden=false): the nav is an always-visible column rendered in Omniscio's sub-sidebar slot (PersistentNavSidebar in AmcSupermailSidebarApp). Still collapsible to the 44px icon rail.
  • Overlay ("Show sidebar" off, the default, hidden=true): the sub-sidebar slot is empty and the mail panel spans full width with a hamburger top-left. Clicking it sets the transient overlayOpen flag, mounting OverlayNavDrawer (in the panel tree, AppInner) — a drawer that slides in over a dimmed list. It tucks away on mouse-leave (220ms grace), backdrop click, or Escape. overlayOpen is never persisted (resting state is always the hamburger).

Both modes share NavMenuBody (one flat, header-less folder list). The account row at its top opens the command-palette-style account selector (features/auth/account-switcher.tsx, opened via useAccountSwitcherStore or the "Switch Account" palette command); it replaces the old dropdown, shows the active mailbox with a check + Alt N hint, and an "Add account" row. Quick-switch is Alt+1..9. "Add account" opens the chooser described just below rather than jumping straight to Google. Below the folders, a Settings row (gear glyph → /settings) sits directly in the nav — a visible entry, not tucked away — while the header's ⋯ overflow menu now holds only Hide sidebar + Sign out.

Adding a second mailbox — Google or IMAP

All three "Add account" entry points (the account selector, the account menu, and the add-account palette command) open one shared dialog, features/auth/add-account-modal.tsx, held open by useAddAccountModalStore and mounted once in AppInner. Step 1 offers Google or Other (IMAP); step 2 renders the existing <ImapForm> — the same component the signed-out sign-in screen uses, with its ISPDB autoconfig — behind a back button. Google still calls authStore.addAccount() unchanged.

The IMAP side is not the sign-in route. authStore.linkImapMailbox() posts to the authenticated POST /auth/mailboxes/imap, which attaches the mailbox to the user its bearer token identifies and returns no session:

  • body.email is mailbox data, never an identity. It can't resolve, create, or mutate another account; the mailboxes_owner RLS WITH CHECK enforces the same boundary a layer down.
  • Adding a mailbox never changes who you are signed in as — the action writes no user / jwt / status. Its sibling loginWithImap (public POST /auth/imap) deliberately does replace the session; reusing it here would have signed the user out of their Gmail. Both halves of that contrast are pinned by tests in auth-store.test.ts.
  • Both hosts pass the shared SSRF guard and a live IMAP and SMTP probe before anything is written, so a bad credential leaves no half-configured mailbox. The probe code lives once in backend/src/shared/mail/imap/probe.ts, shared with the sign-in route.
  • Re-linking an address already connected over IMAP refreshes its credentials in place. Re-linking one already connected through Google is refused with a 409 — never silently converted, which would orphan that mailbox's OAuth tokens. The 409 is load-bearing: it is the only one this route emits, and the UI keys on it to show the refusal verbatim instead of humanizing it (the message contains "connected", which would otherwise be rewritten as unrelated advice about the server address).
  • The new mailbox becomes primary and an imap.poll first-sync is enqueued fire-and-forget, so the UI reports that mail is on its way rather than showing an empty inbox with no explanation.

GET /auth/me resolves the account kind from the primary mailbox (desc(isPrimary), asc(id), limit 1). It previously read an unordered single row, so a user holding both a Gmail and an IMAP mailbox got whichever the planner happened to return.

The sidebar footer carries the sync-status line, the account/sign-out menu, and — between them — an always-visible "Reconnect" button (features/sync-status/reconnect-session-button.tsx → authStore.reconnectMailbox(), the same re-OAuth the conditional sync-status/reconnect-banner.tsx uses). It is present in every signed-in state (not gated on needsReconnect() or user), so a stuck/dead session is one click from recovered without hunting for the account-menu "Sign out" (which is gated on user and can vanish exactly when it's needed).

Reading pane — theming, glass, and Focus mode

The open-conversation reader follows Omniscio's active theme AND any custom theme automatically. Its message cards render on the app's panel tokens (--panel-bg / --panel-border / --panel-blur, bridged into .supermail-scope in index.css), so the pane is glassy under a glass theme (e.g. Glassmorphism — a one-tap built-in theme) and flat under a flat one, with no hardcoded per-component colour. There is no separate colour/theme picker inside Supermail — choose a theme (or a custom theme) in Settings → Appearance and the reader follows it. Designed-HTML ("isolated") emails render in a white-canvas iframe (they're authored for light); in dark mode they're smart-inverted to match the pane — driven by the app's REAL dark state (Omniscio's own theme in-app, NOT the OS prefers-color-scheme), with an auto-skip that leaves an already-dark email alone and a per-email "Show original (light)" toggle. Full behavior + invariants: supermail-email-render-contract.md.

  • Nested thread (Superhuman-style). A thread opens with only the latest message expanded; every older message collapses to a single scannable row — avatar · sender · one-line snippet · time — so a long thread reads as a compact stack, not a wall of full-height cards. Click a row (or o) to expand it; click an expanded message's header (or o) to collapse it back to its row. Every message carries the same neutral grey initials avatar the thread list uses. Both states live in message-view.tsx (the collapsed early-return row + the expanded card); only-latest-expanded is seeded in conversation-store.ts.
  • Centered, pinned subject. The subject sits centered above the email frame, aligned to the email's own reading width, and stays pinned to the top as you scroll a long thread (it never scrolls away with the body). In Full View the header reserves side space so the subject clears the floating hamburger and the corner controls. Built in thread-view.tsx.
  • Toolbars are on screen. The top bar carries Reply and, inside Omniscio, the Start a session and Send to session icon buttons. The bottom is a floating icon dock. Both are visible by default and reachable by keyboard (Tab) the moment a thread opens. Focus mode is the one thing that holds them back, and there hover or keyboard focus still peeks them in, and Keep toolbars visible (a dock/menu action) keeps them out. Every keyboard shortcut keeps working the whole time (the reveal is purely visual). Reveal logic: use-chrome-reveal.ts + the chromePinned reading pref; the dock is wrapped in triage-reveal-zone.tsx.
  • The dock and "pin what you want". The dock shows icons only; hover one to see its name and key. Its last button, ⋯ All actions, lists every reading action — Done, Remind me, Follow up, Mark unread, Label, Trash, Mark spam, Reply, Forward, Previous, Next, Create task, Filter like these, Focus mode and Keep toolbars visible. Click a row to run it, or click its pin to put it on the dock (click again, or right-click the row, to take it off). Right-click a dock icon and choose Unpin from toolbar to remove it. Reorder toolbar… at the bottom of the menu changes the order. Out of the box the dock holds Done, Remind me, Trash, Previous and Next; a saved choice is kept. On a phone the dock shows up to six icons and ⋯ opens a bottom sheet. The pinned list is the supermailTriageActionOrder setting (CLI-controllable). Built in features/triage-bar/triage-bar.tsx and triage-dock-menu.tsx.
  • Always-visible "Start a session". One icon button stays put in the top-right (inside Omniscio) to spin up a Claude session seeded with the whole thread — see "Start a session" above.
  • Attachment chips show just the file size at rest; the old "✓ Ready" badge is gone (a static attachment is not a task). Images still preview as thumbnails when fetchable; an in-flight download shows "Downloading…", a server-rejected one "Failed".
  • Focus mode (hide chrome, keyboard-first). Toggle it with the Z shortcut or the Focus mode action (in the dock's ⋯ menu, or pinned to the dock); while it is on, an Exit focus mode button stays in the top-right. It hides the pane's OWN chrome — the triage bar, the right-hand contact rail, and the team comment bar — for a distraction-free read; every reading-pane shortcut stays live so you can work entirely by hotkey. It does NOT touch Omniscio's outer chrome. Device-local (supermail-reading-prefs, off by default). Store: features/layout/reading-prefs-store.ts.
  • Reading layout. Settings → General → Personalization → Reading layout picks how the open email's reading column is sized: Standard (a wider column), Centered (narrower), or Editorial (narrowest). It sizes the message BODY column — the subject lives in the pinned header (above), so the heading style no longer varies by layout. The reply composer opens at this SAME width, so a reply is never wider than the email it answers (shared readingLayoutWidthClass in reading-prefs-store.ts, applied in both thread-view.tsx and compose-page.tsx). Device-local (supermail-reading-prefs, Standard by default).

Compose — keep moving through mail with a draft open (desktop)

Opening a reply / reply-all / forward on desktop no longer traps the keyboard. The inbox navigation keys — J/K + arrows, plus W/S when left-handed nav is on — save the draft (autosave) and jump to the previous/next email instead of being swallowed by the composer, so a draft never blocks triage.

  • Navigate mode on desktop. To free the bare keys, a desktop reply opens WITHOUT the body auto-grabbing the caret — press Enter (or click) to start typing and Esc to step back out to navigation. Touch devices keep tap-to-type autofocus (no physical keyboard to navigate with), detected via isCoarsePointer.
  • Typing still types. The nav keys are registered in the compose context and fire only when the caret is NOT in a compose field (the global keyboard listener drops bare keys while a text input is focused), so typing j/k/w/s INTO the draft still types.
  • Safe by construction. No-ops at the first/last email and for a brand-new (non-thread) message; the draft is flushed to autosave before the composer closes.
  • When a Gmail draft is minted. Autosave needs a recipient AND a subject (the backend rejects less) — and for a reply / reply-all, which opens with both already filled from the source message, it ALSO needs typed body text. Opening a reply and backing out (Esc, Back, or clicking away) leaves nothing behind; before this gate an untouched reply minted an empty Gmail draft on the thread, which other mail clients showed as a blank message from you. An untouched rich-text editor holds <br />, so tags are stripped before the blank check. A forward opens with its subject already filled, so it counts as written only once it has a recipient or body text. Code: features/compose/authored-content.ts (hasAuthoredDraftContent), shared by autosave and the local snapshot below.
  • Code: features/compose/use-compose-thread-nav.ts (+ is-coarse-pointer.ts), wired in compose-page.tsx; the Shortcuts drawer lists it (shortcut-catalog.ts). Invariants are locked by the sub-app's own vitest tests (use-compose-thread-nav.test.ts) — the vendored app is outside Omniscio's contract system by design.

Compose — an unsent draft is never lost when its window closes

Close a Supermail window (Ctrl+W, the X, or quitting the app) with a half-written email and it closes right away — the draft is kept, and it reopens in the composer the next time Supermail is shown, in any window: the main panel, a pop-out, or a single-email window.

  • Saved the moment you stop. Everything you type is written to this computer's local storage within a fraction of a second, and again the instant the window closes, the app quits, or you leave the composer. In the shared-Google-sign-in mode Gmail drafts are not created at all, so this local copy is the only copy — it is what keeps a draft safe.
  • It follows the window you are looking at. A draft belongs to the window where Supermail is showing. When that window closes or Supermail is hidden in it (you switched to another view, or popped Supermail out), the draft is saved and released, and the next window where Supermail is showing picks it up and opens the composer with it. A draft is never open in two windows at once; a window shown again after its draft moved closes its stale copy.
  • Only real drafts come back. A reply or forward you opened but never typed in is not saved and does not reopen. A single-email window only reopens a draft for that email. Discarding follows the same line: a draft holding nothing of yours closes at once, and one with typed text, a recipient you added or an attached file asks first.
  • Signing out wipes saved drafts from every screen; sending or discarding clears that draft. Saved drafts expire after 30 days, at most four are kept per account, and attachments are not part of the saved copy.
  • How it works. features/compose/compose-draft-restore.tsx (mounted once in the router's signed-in shell, before the page content) restores this window's own snapshot in a layout effect — so a reload on the compose screen keeps the composer — and holds a Web Lock named supermail-compose:<window token> while the keep-warm active flag is on (HostActiveContext, set in app.tsx), saving the snapshot before letting go. For every other window's snapshot it waits on that window's lock; when the lock is released (window closed, crashed, or Supermail hidden there) it claims the snapshot — moving it onto its own window token in one write — and opens the composer, which ComposeRouteSync routes to /compose. A storage event from another window triggers a rescan. A window shown again whose snapshot was claimed elsewhere (matched by the snapshot's savedAt) resets its composer. Without Web Locks it falls back to adopting the newest snapshot. The snapshot writer is flushSnapshot() in use-compose-persistence.ts (debounce timer, pagehide, beforeunload, and the composer's unmount). Tests: compose-draft-restore.test.tsx, use-compose-persistence.test.ts.

The overview, the other parts, and everything else worth reading next all sit on Supermail.

Last verified 2026-10-06