Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
refactor(email): scope target navigation with a machine (#6665)
teo74c39c0dcee8
diff --git a/apps/web/src/features/email-thread/primitives/email-thread-state.ts b/apps/web/src/features/email-thread/primitives/email-thread-state.tsindex cb03b35854..d594e26c62 100644--- a/apps/web/src/features/email-thread/primitives/email-thread-state.ts+++ b/apps/web/src/features/email-thread/primitives/email-thread-state.ts@@ -1,5 +1,5 @@import type { Accessor } from 'solid-js';-import { createEffect, createMemo, createSignal, untrack } from 'solid-js';+import { createEffect, createMemo, createSignal, on } from 'solid-js';import { createStore } from 'solid-js/store';import type { EmailRecipient } from '../../email-compose/core/email-recipient';import type { ReplyType } from '../../email-compose/core/reply-type';@@ -16,6 +16,9 @@ import { hiddenMessagesControl } from './scroll-to-message';import { createThreadDrafts } from './thread-drafts';import { createThreadRecipients } from './thread-recipients';import { createThreadSnapshot } from './thread-snapshot';++type NavigationTarget = { threadId: string; messageId: string | undefined };+export type EmailThreadState = {isScrollingToMessage: Accessor<boolean>;setIsScrollingToMessage: (value: boolean) => void;@@ -37,7 +40,7 @@ export type EmailThreadState = {unfiltered: Accessor<EmailMessage[]>;list: Accessor<EmailMessage[]>;targetMessageId: Accessor<string | undefined>;- setTargetMessageId: (id: string | undefined) => void;+ clearTargetMessage: () => void;focusedId: Accessor<string | undefined>;setFocused: (messageId: string | undefined) => void;hiddenChipFocused: Accessor<boolean>;@@ -98,7 +101,10 @@ export type EmailThreadState = {markSenderSignal: () => boolean;markSenderNoise: () => boolean;initialLoadComplete: Accessor<boolean>;- onInitialDataLoad: (callback: () => boolean) => void;+ onInitialDataLoad: (+ callback: () => void,+ onTargetChange: (target: NavigationTarget) => void+ ) => void;};export function createEmailThreadState(@@ -127,13 +133,26 @@ export function createEmailThreadState(const [expandedMessageBodyIds, setExpandedMessageBodyIds] = createStore<Record<string, boolean>>({});- const [targetMessageId, setTargetMessageId] = createSignal<string>();- const [hasHandledTarget, setHasHandledTarget] = createSignal(false);- createEffect(() => {- const target = host.targetMessageId?.();- setTargetMessageId(target);- setHasHandledTarget(false);- });+ // Identity distinguishes returning to a previously cleared deep link from+ // continuing to display it after its highlight has expired.+ const navigationTarget = createMemo(+ () => ({+ threadId: threadContext.source.id(),+ messageId: host.targetMessageId?.(),+ }),+ undefined,+ {+ equals: (a, b) =>+ a.threadId === b.threadId && a.messageId === b.messageId,+ }+ );+ const [clearedTarget, setClearedTarget] = createSignal<NavigationTarget>();+ const [handledTarget, setHandledTarget] = createSignal<NavigationTarget>();+ const targetMessageId = () =>+ clearedTarget() === navigationTarget()+ ? undefined+ : navigationTarget().messageId;+ const hasHandledTarget = () => handledTarget() === navigationTarget();const drafts = createThreadDrafts(selected);@@ -163,18 +182,33 @@ export function createEmailThreadState(setFocusedMessageId(messageId);};- const onInitialDataLoad = (callback: () => boolean) => {- createEffect(() => {- if (hasHandledTarget() || threadContext.source.isFetching()) return;- if (!messagesListRef()) return;- if (- (!messagesContainerRef() || !untrack(selected)?.db_id) &&- threadContext.source.hasMore()+ const onInitialDataLoad: EmailThreadState['onInitialDataLoad'] = (+ callback,+ onTargetChange+ ) => {+ let previousTarget: NavigationTarget | undefined;+ const ready = () =>+ !threadContext.source.isFetching() &&+ (!threadContext.isTouch() || host.isActive?.() !== false) &&+ !!messagesListRef() &&+ ((!!messagesContainerRef() && !!selected()?.db_id) ||+ !threadContext.source.hasMore());+ // One boundary from reactive route/query/DOM readiness into navigation.+ // Cancel the previous target even while fetching or hidden on mobile.+ createEffect(+ on(+ [navigationTarget, hasHandledTarget, ready],+ ([target, handled, ready]) => {+ if (target !== previousTarget) {+ previousTarget = target;+ onTargetChange(target);+ }+ if (handled || !ready) return;+ callback();+ setHandledTarget(target);+ })- return;-- setHasHandledTarget(callback());- });+ );};return {@@ -202,8 +236,8 @@ export function createEmailThreadState(setHiddenChipFocused,hovered: hoveredStop,setHovered: setHoveredStop,- targetMessageId: targetMessageId,- setTargetMessageId: setTargetMessageId,+ targetMessageId,+ clearTargetMessage: () => setClearedTarget(navigationTarget()),list: createMemo(() => selected()?.filtered ?? []),unfiltered: createMemo(() => selected()?.messages ?? []),// Google's CATEGORY_PERSONAL classification is inconsistent acrossdiff --git a/apps/web/src/features/email-thread/primitives/target-message-navigation.test.ts b/apps/web/src/features/email-thread/primitives/target-message-navigation.test.tsnew file mode 100644index 0000000000..ed2133cd46--- /dev/null+++ b/apps/web/src/features/email-thread/primitives/target-message-navigation.test.ts@@ -0,0 +1,35 @@+import { afterEach, expect, it, vi } from 'vitest';+import { createTargetMessageNavigation } from './target-message-navigation';++afterEach(() => vi.useRealTimers());++it.each(['load', 'position'])(+ 'releases a manually revealed target after an initial %s failure',+ async (failure) => {+ vi.useFakeTimers();+ const target = { threadId: 'thread', messageId: 'target' };+ const release = vi.fn();+ const navigation = createTargetMessageNavigation({+ load: async () => {+ if (failure === 'load') throw new Error('network unavailable');+ return true;+ },+ position: () => false,+ release,+ highlightMs: 800,+ onError: vi.fn(),+ });+ try {+ navigation.navigate(target);+ await vi.advanceTimersByTimeAsync(20);+ // The same target is reached later through keyboard navigation.+ navigation.highlight(target);+ await vi.advanceTimersByTimeAsync(799);+ expect(release).not.toHaveBeenCalled();+ await vi.advanceTimersByTimeAsync(1);+ expect(release).toHaveBeenCalledExactlyOnceWith(target);+ } finally {+ navigation.dispose();+ }+ }+);diff --git a/apps/web/src/features/email-thread/primitives/target-message-navigation.ts b/apps/web/src/features/email-thread/primitives/target-message-navigation.tsnew file mode 100644index 0000000000..8cfbc1535a--- /dev/null+++ b/apps/web/src/features/email-thread/primitives/target-message-navigation.ts@@ -0,0 +1,114 @@+import {+ createMachine,+ type MachineDef,+ type Transition,+} from '@macro-inc/machine';+import { match } from 'ts-pattern';++export type MessageTarget = { threadId: string; messageId: string };+type NavigationState =+ | { t: 'idle' }+ | { t: 'loading'; target: MessageTarget }+ | { t: 'positioning'; target: MessageTarget }+ | { t: 'highlighting'; target: MessageTarget };+type Event =+ | { t: 'navigate'; target: MessageTarget }+ | { t: 'cancel' | 'loaded' | 'positioned' | 'finished' }+ | { t: 'highlight'; target: MessageTarget };++const sameTarget = (a: MessageTarget, b: MessageTarget) =>+ a.threadId === b.threadId && a.messageId === b.messageId;++function transition(+ state: NavigationState,+ event: Event+): Transition<NavigationState, never> | undefined {+ return match(event)+ .with({ t: 'navigate' }, ({ target }) => ({+ state: { t: 'loading', target } as const,+ }))+ .with({ t: 'cancel' }, () =>+ state.t === 'idle' ? undefined : { state: { t: 'idle' } as const }+ )+ .with({ t: 'loaded' }, () =>+ state.t === 'loading'+ ? { state: { t: 'positioning', target: state.target } as const }+ : undefined+ )+ .with({ t: 'positioned' }, () =>+ state.t === 'positioning'+ ? { state: { t: 'highlighting', target: state.target } as const }+ : undefined+ )+ .with({ t: 'highlight' }, ({ target }) =>+ state.t === 'idle' || sameTarget(state.target, target)+ ? { state: { t: 'highlighting', target } as const }+ : undefined+ )+ .with({ t: 'finished' }, () => ({ state: { t: 'idle' } as const }))+ .exhaustive();+}++const definition: MachineDef<NavigationState, Event> = {+ idle: { on: transition },+ loading: { on: transition },+ positioning: { on: transition },+ highlighting: { on: transition },+};++/** One deep link owns its loading, layout callback, and highlight lifetime. */+export function createTargetMessageNavigation(options: {+ load: (target: MessageTarget, signal: AbortSignal) => Promise<boolean>;+ position: (target: MessageTarget) => boolean;+ release: (target: MessageTarget) => void;+ highlightMs: number;+ onError: (error: unknown) => void;+}) {+ const machine = createMachine<NavigationState, Event>({+ initial: { t: 'idle' },+ def: definition,+ scopes: {+ loading: ({ target }, dispatch) => {+ const controller = new AbortController();+ async function loadTarget() {+ try {+ const found = await options.load(target, controller.signal);+ if (!controller.signal.aborted)+ dispatch({ t: found ? 'loaded' : 'finished' });+ } catch (error) {+ if (controller.signal.aborted) return;+ options.onError(error);+ dispatch({ t: 'finished' });+ }+ }+ void loadTarget();+ return () => controller.abort();+ },+ positioning: ({ target }, dispatch) => {+ const frame = requestAnimationFrame(() => {+ dispatch({ t: options.position(target) ? 'positioned' : 'finished' });+ });+ return () => cancelAnimationFrame(frame);+ },+ highlighting: ({ target }, dispatch) => {+ const timer = setTimeout(() => {+ options.release(target);+ dispatch({ t: 'finished' });+ }, options.highlightMs);+ return () => clearTimeout(timer);+ },+ },+ });+ return {+ navigate: (target: MessageTarget) =>+ machine.dispatch({ t: 'navigate', target }),+ highlight: (target: MessageTarget) =>+ machine.dispatch({ t: 'highlight', target }),+ syncTarget: (target: MessageTarget | undefined) => {+ const state = machine.getState();+ if (state.t !== 'idle' && (!target || !sameTarget(state.target, target)))+ machine.dispatch({ t: 'cancel' });+ },+ dispose: machine.dispose,+ };+}diff --git a/apps/web/src/features/email-thread/primitives/thread-navigation-target.test.ts b/apps/web/src/features/email-thread/primitives/thread-navigation-target.test.tsnew file mode 100644index 0000000000..0736ca8722--- /dev/null+++ b/apps/web/src/features/email-thread/primitives/thread-navigation-target.test.ts@@ -0,0 +1,271 @@+import { createRoot, createSignal } from 'solid-js';+import { afterEach, expect, it, vi } from 'vitest';+import { createThreadContext, message, thread } from '../tests/fixtures';+import { createEmailThreadState } from './email-thread-state';+import { createThreadNavigation } from './thread-navigation';++afterEach(() => {+ vi.useRealTimers();+ vi.unstubAllGlobals();+});++function setup(+ target: string,+ ids: string[],+ older?: string[],+ fetchWait?: Promise<void>+) {+ vi.useFakeTimers();+ vi.stubGlobal('CSS', { escape: (value: string) => value });+ const container = document.createElement('div');+ container.scrollBy = vi.fn();+ const render = (ids: string[]) => {+ container.replaceChildren(+ ...ids.map((id) => {+ const element = document.createElement('div');+ element.dataset.messageBodyId = id;+ return element;+ })+ );+ };+ render(ids);+ document.body.append(container);+ const fixture = createRoot((dispose) => {+ const [threadId, setThreadId] = createSignal('thread');+ const [isFetching, setFetching] = createSignal(false);+ const [isTouch, setTouch] = createSignal(false);+ const [isActive, setActive] = createSignal(true);+ const [snapshot, setSnapshot] = createSignal(+ thread(ids.map((id) => message(id)))+ );+ const [hasMore, setHasMore] = createSignal(Boolean(older));+ const fetchOlder = vi.fn(async () => {+ await fetchWait;+ const next = [...(older ?? []), ...ids];+ render(next);+ setSnapshot(thread(next.map((id) => message(id))));+ setHasMore(false);+ });+ const source = createThreadContext({+ id: threadId,+ thread: snapshot,+ isFetching,+ hasMore,+ fetchOlder,+ });+ source.isTouch = isTouch;+ const [targetMessageId, setTarget] = createSignal<string | undefined>(+ target+ );+ const host = { targetMessageId, isActive };+ const state = createEmailThreadState(source, host);+ const navigation = createThreadNavigation(+ { threadId },+ state,+ source,+ host+ );+ state.registerMessagesList(container);+ state.registerMessagesContainer(container);+ return {+ state,+ navigation,+ fetchOlder,+ setTarget,+ setFetching,+ setTouch,+ setActive,+ setThreadId,+ setSnapshot,+ dispose,+ };+ });+ return {+ ...fixture,+ container,+ dispose: () => {+ fixture.dispose();+ container.remove();+ },+ };+}++it('expands and positions a loaded deep link, then releases its highlight', async () => {+ const fixture = setup('target', ['first', 'target', 'last']);+ try {+ await vi.advanceTimersByTimeAsync(20);+ expect(fixture.state.messages.expandedBodyIds.target).toBe(true);+ expect(fixture.state.messages.focusedId()).toBe('target');+ expect(fixture.container.scrollBy).toHaveBeenCalledOnce();+ expect(fixture.state.messages.targetMessageId()).toBe('target');+ await vi.advanceTimersByTimeAsync(250);+ expect(fixture.state.isScrollingToMessage()).toBe(false);+ await vi.advanceTimersByTimeAsync(800);+ expect(fixture.state.messages.targetMessageId()).toBeUndefined();+ expect(fixture.fetchOlder).not.toHaveBeenCalled();+ } finally {+ fixture.dispose();+ }+});++it('loads an older page before positioning an unloaded deep link', async () => {+ const fixture = setup('older', ['newest'], ['older']);+ try {+ expect(fixture.container.scrollBy).not.toHaveBeenCalled();+ await vi.advanceTimersByTimeAsync(100);+ expect(fixture.fetchOlder).toHaveBeenCalledOnce();+ expect(fixture.state.messages.focusedId()).toBe('older');+ expect(fixture.container.scrollBy).toHaveBeenCalledOnce();+ } finally {+ fixture.dispose();+ }+});++it('does not scroll when the target is absent from every available page', async () => {+ const fixture = setup('missing', ['newest'], ['older']);+ try {+ await vi.advanceTimersByTimeAsync(100);+ expect(fixture.fetchOlder).toHaveBeenCalledOnce();+ expect(fixture.container.scrollBy).not.toHaveBeenCalled();+ expect(fixture.state.messages.focusedId()).toBeUndefined();+ } finally {+ fixture.dispose();+ }+});++it('keeps the replacement target highlighted for its own full duration', async () => {+ const fixture = setup('target', ['first', 'target', 'last']);+ try {+ await vi.advanceTimersByTimeAsync(420);+ fixture.setTarget('last');+ await vi.advanceTimersByTimeAsync(420);+ expect(fixture.state.messages.focusedId()).toBe('last');+ expect(fixture.state.messages.targetMessageId()).toBe('last');+ await vi.advanceTimersByTimeAsync(500);+ expect(fixture.state.messages.targetMessageId()).toBeUndefined();+ } finally {+ fixture.dispose();+ }+});++it('cancels a queued layout callback when the thread unmounts', async () => {+ const fixture = setup('target', ['first', 'target', 'last']);+ await vi.advanceTimersByTimeAsync(0);+ fixture.dispose();+ await vi.advanceTimersByTimeAsync(1000);+ expect(fixture.container.scrollBy).not.toHaveBeenCalled();+});++it('ignores an older navigation result after a new target has been positioned', async () => {+ let resolveFetch!: () => void;+ const pending = new Promise<void>((resolve) => {+ resolveFetch = resolve;+ });+ const fixture = setup('older', ['first', 'next', 'last'], ['older'], pending);+ try {+ fixture.setTarget('next');+ await vi.advanceTimersByTimeAsync(20);+ expect(fixture.state.messages.focusedId()).toBe('next');+ resolveFetch();+ await vi.advanceTimersByTimeAsync(100);+ expect(fixture.state.messages.focusedId()).toBe('next');+ expect(fixture.container.scrollBy).toHaveBeenCalledOnce();+ } finally {+ fixture.dispose();+ }+});++it('ignores a page response after the thread unmounts', async () => {+ let resolveFetch!: () => void;+ const pending = new Promise<void>((resolve) => {+ resolveFetch = resolve;+ });+ const fixture = setup('older', ['newest'], ['older'], pending);+ fixture.dispose();+ resolveFetch();+ await vi.advanceTimersByTimeAsync(1000);+ expect(fixture.container.scrollBy).not.toHaveBeenCalled();+});++it('cancels a queued frame before a removed target can wait on a busy query', async () => {+ const fixture = setup('target', ['first', 'target', 'last']);+ try {+ await vi.advanceTimersByTimeAsync(0);+ fixture.setFetching(true);+ fixture.setTarget(undefined);+ await vi.advanceTimersByTimeAsync(1000);+ expect(fixture.container.scrollBy).not.toHaveBeenCalled();+ expect(fixture.state.messages.targetMessageId()).toBeUndefined();+ fixture.setFetching(false);+ expect(fixture.state.initialLoadComplete()).toBe(true);+ } finally {+ fixture.dispose();+ }+});++it('cancels the old highlight while a replacement waits for an inactive mobile view', async () => {+ const fixture = setup('target', ['first', 'target', 'last']);+ try {+ await vi.advanceTimersByTimeAsync(20);+ fixture.setTouch(true);+ fixture.setActive(false);+ fixture.setTarget('last');+ await vi.advanceTimersByTimeAsync(1000);+ expect(fixture.state.messages.targetMessageId()).toBe('last');+ expect(fixture.container.scrollBy).toHaveBeenCalledOnce();+ fixture.setActive(true);+ await vi.advanceTimersByTimeAsync(20);+ expect(fixture.state.messages.focusedId()).toBe('last');+ expect(fixture.container.scrollBy).toHaveBeenCalledTimes(2);+ } finally {+ fixture.dispose();+ }+});++it('resets navigation and hidden-message focus when the thread changes while loading', async () => {+ const fixture = setup('target', ['first', 'target', 'last']);+ try {+ await vi.advanceTimersByTimeAsync(0);+ fixture.navigation.setUserOpenedMiddle(true);+ fixture.state.messages.setHiddenChipFocused(true);+ fixture.setFetching(true);+ fixture.setThreadId('other');+ await vi.advanceTimersByTimeAsync(1000);+ expect(fixture.container.scrollBy).not.toHaveBeenCalled();+ expect(fixture.state.messages.hiddenChipFocused()).toBe(false);+ expect(fixture.state.initialLoadComplete()).toBe(false);+ fixture.setSnapshot(+ thread(+ ['first', 'target', 'last'].map((id) => message(id)),+ { db_id: 'other' }+ )+ );+ fixture.setFetching(false);+ await vi.advanceTimersByTimeAsync(20);+ expect(fixture.state.messages.focusedId()).toBe('target');+ expect(fixture.container.scrollBy).toHaveBeenCalledOnce();+ expect(fixture.state.initialLoadComplete()).toBe(true);+ } finally {+ fixture.dispose();+ }+});++it('does not restart a cleared target on a cache update, but supports opening it again', async () => {+ const fixture = setup('target', ['first', 'target', 'last']);+ try {+ await vi.advanceTimersByTimeAsync(1000);+ fixture.setSnapshot(+ thread(['first', 'target', 'last'].map((id) => message(id)))+ );+ await vi.advanceTimersByTimeAsync(20);+ expect(fixture.state.messages.targetMessageId()).toBeUndefined();+ expect(fixture.container.scrollBy).toHaveBeenCalledOnce();+ fixture.setTarget(undefined);+ fixture.setTarget('target');+ await vi.advanceTimersByTimeAsync(20);+ expect(fixture.state.messages.targetMessageId()).toBe('target');+ expect(fixture.container.scrollBy).toHaveBeenCalledTimes(2);+ } finally {+ fixture.dispose();+ }+});diff --git a/apps/web/src/features/email-thread/primitives/thread-navigation.ts b/apps/web/src/features/email-thread/primitives/thread-navigation.tsindex 9e214a51d1..e5bf404627 100644--- a/apps/web/src/features/email-thread/primitives/thread-navigation.ts+++ b/apps/web/src/features/email-thread/primitives/thread-navigation.ts@@ -1,12 +1,11 @@import type { ReplyType } from '@app/features/email-compose/core/reply-type';import type { EmailMessage } from '@app/features/email-message/core/email-message';import { createCallback } from '@solid-primitives/rootless';+import { debounce } from '@solid-primitives/scheduled';import {type Accessor,- createEffect,createMemo,createSignal,- on,onCleanup,onMount,untrack,@@ -42,6 +41,7 @@ import {threadMessageIsExpanded,} from '../primitives/scroll-to-message';import type { EmailThreadState } from './email-thread-state';+import { createTargetMessageNavigation } from './target-message-navigation';const TARGET_MESSAGE_HIGHLIGHT_MS = 800;/** List navigation — keep within the 300ms UI motion budget (improve-animations). */@@ -56,26 +56,31 @@ export function createThreadNavigation() {const isTouchDevice = threadContext.isTouch;const setIsScrollingToMessage = context.setIsScrollingToMessage;- let disposed = false;- const pendingWaits = new Set<() => void>();+ const finishScrolling = debounce(+ () => setIsScrollingToMessage(false),+ SCROLL_ANIMATION_MS+ );+ const markScrolling = () => {+ setIsScrollingToMessage(true);+ finishScrolling();+ };onCleanup(() => {- disposed = true;- for (const finish of pendingWaits) finish();+ finishScrolling.clear();+ setIsScrollingToMessage(false);});- /**- * Waits for the query to finish fetching- */- const waitForQueryLoad = (): Promise<void> => {++ const waitForQueryLoad = (signal: AbortSignal): Promise<void> => {+ if (signal.aborted || !context.query.isFetching()) return Promise.resolve();return new Promise((resolve) => {const finish = () => {clearInterval(checkInterval);- pendingWaits.delete(finish);+ signal.removeEventListener('abort', finish);resolve();};const checkInterval = setInterval(() => {- if (disposed || !context.query.isFetching()) finish();+ if (!context.query.isFetching()) finish();}, 50);- pendingWaits.add(finish);+ signal.addEventListener('abort', finish, { once: true });});};@@ -83,10 +88,11 @@ export function createThreadNavigation(* Loads messages until the target message is found or no more messages available*/const loadMessagesUntilFound = async (- targetMessageId: string+ targetMessageId: string,+ signal: AbortSignal): Promise<boolean> => {const ownerThreadId = props.threadId();- while (!disposed && props.threadId() === ownerThreadId) {+ while (!signal.aborted && props.threadId() === ownerThreadId) {const messages = context.messages.unfiltered();// Check if message exists in current batch@@ -101,22 +107,23 @@ export function createThreadNavigation(// Load next batch and waitawait context.query.fetchNextPage();- await waitForQueryLoad();+ await waitForQueryLoad(signal);if (context.messages.unfiltered().length <= messages.length) return false;}return false;};- const fetchNextPage = async () => {- if (context.query.hasMore() && !context.query.isFetching()) {- context.query.fetchNextPage();- await waitForQueryLoad();+ const fetchNextPage = async (signal: AbortSignal) => {+ if (+ !signal.aborted &&+ context.query.hasMore() &&+ !context.query.isFetching()+ ) {+ await context.query.fetchNextPage();+ await waitForQueryLoad(signal);}};- const canRunInitialEmailScroll = () =>- !isTouchDevice() || host.isActive?.() !== false;-const [keyboardSelecting, setKeyboardSelecting] = createSignal(false);const [listAnchor, setListAnchor] = createSignal<'title' | 'composer'>();let lastPointer = { x: Number.NaN, y: Number.NaN };@@ -174,14 +181,13 @@ export function createThreadNavigation(if (!messages || !container) return false;- setIsScrollingToMessage(true);-const success = scrollToMessage(messageId, messages, container, {behavior: opts.behavior,align: opts.align,});if (!success) {+ finishScrolling.clear();setIsScrollingToMessage(false);return false;}@@ -191,70 +197,61 @@ export function createThreadNavigation(context.messages.setFocused(messageId);}+ markScrolling();if (context.messages.targetMessageId() === messageId) {- setTimeout(() => {- context.messages.setTargetMessageId(undefined);- }, TARGET_MESSAGE_HIGHLIGHT_MS);+ targetNavigation.highlight({ threadId: props.threadId(), messageId });}- setTimeout(() => setIsScrollingToMessage(false), SCROLL_ANIMATION_MS);-return true;};- context.onInitialDataLoad(() => {- if (!canRunInitialEmailScroll()) return false;- if (!untrack(context.messagesListRef)) return false;-- const targetMessageId_ = context.messages.targetMessageId();- if (targetMessageId_ && typeof targetMessageId_ !== 'string') return true;- if (typeof targetMessageId_ === 'string') {- void revealTargetMessage(targetMessageId_);- }-- return true;- });-- async function revealTargetMessage(messageId: string) {- context.messages.setExpandedBodyId(messageId, true);- const messages = untrack(context.messages.list);- if (!messages) return;-- const initialIndex = messages.findIndex(- (message) => message.db_id === messageId- );-- if (initialIndex < 0) {- try {- const found = await loadMessagesUntilFound(messageId);- if (!found) return;- await fetchNextPage();- } catch (error) {- console.error('Error loading target message:', error);- return;+ const targetNavigation = createTargetMessageNavigation({+ highlightMs: TARGET_MESSAGE_HIGHLIGHT_MS,+ load: async ({ messageId, threadId }, signal) => {+ context.messages.setExpandedBodyId(messageId, true);+ const messages = untrack(context.messages.list);+ const initialIndex = messages.findIndex(+ (message) => message.db_id === messageId+ );+ if (initialIndex < 0) {+ if (!(await loadMessagesUntilFound(messageId, signal))) return false;+ await fetchNextPage(signal);+ } else if (initialIndex === 0) {+ await fetchNextPage(signal);}- } else if (initialIndex === 0) {- await fetchNextPage();- }-- requestAnimationFrame(() => {+ return !signal.aborted && props.threadId() === threadId;+ },+ position: ({ messageId }) =>performScrollToMessage(messageId, {behavior: 'instant',focus: true,align: 'start',- });- });- }-+ }),+ release: ({ messageId }) => {+ if (context.messages.targetMessageId() === messageId)+ context.messages.clearTargetMessage();+ },+ onError: (error) => console.error('Error loading target message:', error),+ });+ onCleanup(targetNavigation.dispose);const [userOpenedMiddle, setUserOpenedMiddle] = createSignal(false);- createEffect(- on(- () => context.thread()?.db_id,- () => {+ let previousThreadId: string | undefined;+ context.onInitialDataLoad(+ () => {+ const messageId = context.messages.targetMessageId();+ if (messageId)+ targetNavigation.navigate({ threadId: props.threadId(), messageId });+ },+ ({ threadId, messageId }) => {+ targetNavigation.syncTarget(+ messageId ? { threadId, messageId } : undefined+ );+ if (threadId !== previousThreadId) {+ previousThreadId = threadId;setUserOpenedMiddle(false);leaveHiddenChip();}- )+ });const showMiddleMessages = createMemo(() => {@@ -276,14 +273,9 @@ export function createThreadNavigation(let markdownDomRef!: HTMLDivElement;const tryKeyboardListScroll = leadingThrottle(KEYBOARD_SCROLL_MS);- const scrollListBy = (- list: HTMLElement,- top: number,- animationMs = SCROLL_ANIMATION_MS- ) => {+ const scrollListBy = (list: HTMLElement, top: number) => {if (top === 0) return false;- setIsScrollingToMessage(true);- setTimeout(() => setIsScrollingToMessage(false), animationMs);+ markScrolling();list.scrollBy({ top, behavior: listScrollBehavior() });return true;};@@ -291,8 +283,7 @@ export function createThreadNavigation(const keyboardScrollListBy = (list: HTMLElement, top: number) => {if (top === 0) return false;if (!tryKeyboardListScroll()) return true;- setIsScrollingToMessage(true);- setTimeout(() => setIsScrollingToMessage(false), KEYBOARD_SCROLL_MS);+ markScrolling();list.scrollBy({ top, behavior: listScrollBehavior() });return true;};diff --git a/docs/AGENT_GUIDE/surfaces.md b/docs/AGENT_GUIDE/surfaces.mdindex aeac627cdc..f274490afe 100644--- a/docs/AGENT_GUIDE/surfaces.md+++ b/docs/AGENT_GUIDE/surfaces.md@@ -332,7 +332,11 @@ Shift-click opens a standalone split at `/app/email/<thread-id>`, which remainsthe destination for direct links and legacy surfaces. Click a message header toexpand or collapse it; `Show N hidden messages` reveals the collapsed middle ofa longer conversation. A standalone link with-`?email_message_id=<message-id>` reveals that message.+`?email_message_id=<message-id>` loads older pages as needed, expands the target,+scrolls it into view, and briefly highlights it. For navigation regressions,+exercise both a recent message and one outside the first page. Open another+target while loading or highlighting: the previous request must not scroll the+new thread or clear its highlight. Closing the split cancels pending positioning.Collapsed thread cards use a compact text snippet; expanding mounts the messagebody and its attachments. On phones, messages form flat rows with horizontalseparators and 16px side gutters; collapsed previews show one line. Desktop