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__'insrc/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 migration20260619214747). - Sidebar hide-when-off gate:
SIDEBAR_RENDER_GATESinsrc/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 viaSUPERMAIL_QUICK_FIND_OPEN, which REUSES the notification-open path (foreground the main window + emitPLUGIN_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/notificationPLUGIN_DEEPLINKpath above, this one DOES route through the generic deep-link parser + router (open-supermail-thread→openSupermailDeepLink), so it is also a recognized destination inGET /deep-link/resolve. Theagentmc://supermail/authsibling (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 onisSupermailAuthDeepLink). 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-agnosticmask-imageinindex.css), with a plain "…" fallback on engines withoutmask-imageand 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 inthread-list.tsx), reduced-motion-aware, and timed to finish exactly as the store removes the row (EXIT_ANIMATION_MS, kept in sync betweenthread-list.tsxandinbox-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+Kcommand 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
xkey (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.
Sidebar: pinned vs overlay (Superhuman-style)
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 (PersistentNavSidebarinAmcSupermailSidebarApp). 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 transientoverlayOpenflag, mountingOverlayNavDrawer(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.overlayOpenis 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.emailis mailbox data, never an identity. It can't resolve, create, or mutate another account; themailboxes_ownerRLSWITH CHECKenforces 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 siblingloginWithImap(publicPOST /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 inauth-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.pollfirst-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 (oro) to collapse it back to its row. Every message carries the same neutral grey initials avatar the thread list uses. Both states live inmessage-view.tsx(the collapsed early-return row + the expanded card); only-latest-expanded is seeded inconversation-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+ thechromePinnedreading pref; the dock is wrapped intriage-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
supermailTriageActionOrdersetting (CLI-controllable). Built infeatures/triage-bar/triage-bar.tsxandtriage-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
Zshortcut 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
readingLayoutWidthClassinreading-prefs-store.ts, applied in boththread-view.tsxandcompose-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
composecontext 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 incompose-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 namedsupermail-compose:<window token>while the keep-warmactiveflag is on (HostActiveContext, set inapp.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, whichComposeRouteSyncroutes to/compose. Astorageevent from another window triggers a rescan. A window shown again whose snapshot was claimed elsewhere (matched by the snapshot'ssavedAt) resets its composer. Without Web Locks it falls back to adopting the newest snapshot. The snapshot writer isflushSnapshot()inuse-compose-persistence.ts(debounce timer,pagehide,beforeunload, and the composer's unmount). Tests:compose-draft-restore.test.tsx,use-compose-persistence.test.ts.
Related
The overview, the other parts, and everything else worth reading next all sit on Supermail.
Last verified 2026-10-06