perf(desktop): high-membership channel-switch benchmark

desktop/src/app/navigation/commitGuardedNavigation.test.mjs

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { commitGuardedNavigation } from "./commitGuardedNavigation.ts";
+
+const route = (href) => ({ kind: "route", href });
+
+test("an accepted navigation consults the guard before navigating", async () => {
+  const order = [];
+  const committed = await commitGuardedNavigation(
+    {
+      currentHref: "/channels/aaaa",
+      nextHref: "/channels/bbbb",
+      guardedTarget: route("/channels/bbbb"),
+      navigate: async () => {
+        order.push("navigate");
+      },
+    },
+    {
+      allow: () => {
+        order.push("guard");
+        return true;
+      },
+    },
+  );
+  assert.equal(committed, true);
+  assert.deepEqual(order, ["guard", "navigate"]);
+});
+
+test("a same-destination no-op never reaches the guard", async () => {
+  const order = [];
+  const committed = await commitGuardedNavigation(
+    {
+      currentHref: "/channels/aaaa",
+      nextHref: "/channels/aaaa",
+      guardedTarget: route("/channels/aaaa"),
+      navigate: async () => {
+        order.push("navigate");
+      },
+    },
+    {
+      allow: () => {
+        order.push("guard");
+        return true;
+      },
+    },
+  );
+  assert.equal(committed, false);
+  assert.deepEqual(order, []);
+});
+
+test("force overrides the same-destination no-op but still runs the guard first", async () => {
+  const order = [];
+  const committed = await commitGuardedNavigation(
+    {
+      currentHref: "/channels/aaaa",
+      nextHref: "/channels/aaaa",
+      force: true,
+      guardedTarget: route("/channels/aaaa"),
+      navigate: async () => {
+        order.push("navigate");
+      },
+    },
+    {
+      allow: () => {
+        order.push("guard");
+        return true;
+      },
+    },
+  );
+  assert.equal(committed, true);
+  assert.deepEqual(order, ["guard", "navigate"]);
+});
+
+test("a same-destination navigation carrying router state still commits", async () => {
+  const order = [];
+  const committed = await commitGuardedNavigation(
+    {
+      currentHref: "/channels/aaaa",
+      nextHref: "/channels/aaaa",
+      guardedTarget: route("/channels/aaaa"),
+      hasStateUpdate: true,
+      navigate: async () => {
+        order.push("navigate");
+      },
+    },
+    {
+      allow: () => {
+        order.push("guard");
+        return true;
+      },
+    },
+  );
+  assert.equal(committed, true);
+  assert.deepEqual(order, ["guard", "navigate"]);
+});
+
+test("a refused navigation does not navigate", async () => {
+  // The guard's whole purpose: an unsaved thread edit blocks the switch.
+  // Asserting only that the guard is CONSULTED is not enough — consulting it
+  // and discarding the answer passes every ordering test in this file.
+  const order = [];
+  const committed = await commitGuardedNavigation(
+    {
+      currentHref: "/channels/aaaa",
+      nextHref: "/channels/bbbb",
+      guardedTarget: route("/channels/bbbb"),
+      navigate: async () => {
+        order.push("navigate");
+      },
+    },
+    {
+      allow: () => {
+        order.push("guard");
+        return false;
+      },
+    },
+  );
+  assert.equal(committed, false);
+  assert.deepEqual(order, ["guard"]);
+});
+
+test("a refused forced navigation does not navigate either", async () => {
+  // force defeats the same-destination skip, never the guard.
+  const order = [];
+  const committed = await commitGuardedNavigation(
+    {
+      currentHref: "/channels/aaaa",
+      nextHref: "/channels/aaaa",
+      force: true,
+      guardedTarget: route("/channels/aaaa"),
+      navigate: async () => {
+        order.push("navigate");
+      },
+    },
+    { allow: () => false },
+  );
+  assert.equal(committed, false);
+  assert.deepEqual(order, []);
+});

desktop/src/app/navigation/commitGuardedNavigation.ts

@@ -0,0 +1,40 @@
+import {
+  allowNavigation,
+  type GuardedNavigation,
+} from "@/app/navigation/navigationGuard";
+
+/**
+ * commitGuardedNavigation runs the shared commit flow for app navigations:
+ * skip same-destination no-ops, consult the navigation guard, then navigate.
+ * `force` and `hasStateUpdate` both defeat the no-op skip — a same-href
+ * navigation that writes router state (setting or clearing the search
+ * highlight) must commit, or the state never lands. Returns whether the
+ * navigation was performed. `deps` exists for unit tests.
+ */
+export async function commitGuardedNavigation(
+  input: {
+    currentHref: string;
+    nextHref: string;
+    force?: boolean;
+    guardedTarget: GuardedNavigation;
+    hasStateUpdate?: boolean;
+    navigate: () => Promise<unknown>;
+  },
+  deps: {
+    allow?: typeof allowNavigation;
+  } = {},
+): Promise<boolean> {
+  const allow = deps.allow ?? allowNavigation;
+  if (
+    input.currentHref === input.nextHref &&
+    !input.force &&
+    !input.hasStateUpdate
+  ) {
+    return false;
+  }
+  if (!allow(input.guardedTarget)) {
+    return false;
+  }
+  await input.navigate();
+  return true;
+}

desktop/src/app/navigation/useAppNavigation.ts

@@ -6,10 +6,10 @@ import {
   useRouter,
 } from "@tanstack/react-router";
 
+import { commitGuardedNavigation } from "@/app/navigation/commitGuardedNavigation";
 import type { SearchHighlightNavigation } from "@/app/navigation/searchHighlightNavigation";
 import { openSearchHitWithNavigation } from "@/app/navigation/searchHitNavigation";
 import {
-  allowNavigation,
   type GuardedNavigation,
   traverseHistory,
 } from "@/app/navigation/navigationGuard";
@@ -43,30 +43,22 @@ export function useAppNavigation() {
       guardedTarget?: GuardedNavigation,
     ) => {
       const nextLocation = router.buildLocation(next as never);
-      const hasStateUpdate = next.state !== undefined;
-
-      if (
-        location.href === nextLocation.href &&
-        !behavior.force &&
-        !hasStateUpdate
-      ) {
-        return false;
-      }
-
-      if (
-        !allowNavigation(
-          guardedTarget ?? { kind: "route", href: nextLocation.href },
-        )
-      ) {
-        return false;
-      }
-
-      await navigate({
-        ...next,
-        replace: behavior.replace,
-        resetScroll: behavior.resetScroll,
-      } as never);
-      return true;
+      return commitGuardedNavigation({
+        currentHref: location.href,
+        force: behavior.force,
+        guardedTarget: guardedTarget ?? {
+          kind: "route",
+          href: nextLocation.href,
+        },
+        hasStateUpdate: next.state !== undefined,
+        navigate: () =>
+          navigate({
+            ...next,
+            replace: behavior.replace,
+            resetScroll: behavior.resetScroll,
+          } as never),
+        nextHref: nextLocation.href,
+      });
     },
     [location.href, navigate, router],
   );

desktop/src/features/channels/ui/ChannelScreen.tsx

@@ -1,6 +1,5 @@
 // biome-ignore-all format: line-count ratchet requires compact forwarding in this legacy component
 import * as React from "react";
-import { useQueryClient } from "@tanstack/react-query";
 import { useAppShell } from "@/app/AppShellContext";
 import { useAppNavigation } from "@/app/navigation/useAppNavigation";
 import { useActiveChannelHeader } from "@/features/channels/useActiveChannelHeader";
@@ -49,11 +48,6 @@ import {
   getThreadReference,
   isThreadReply,
 } from "@/features/messages/lib/threading";
-import { hasPersistedHydratedChannel } from "@/features/messages/lib/channelHeadCache";
-import {
-  resolveTimelineLoadingLatch,
-  selectTimelineLoadingState,
-} from "@/features/messages/lib/timelineLoadingState";
 import { useFetchOlderMessages } from "@/features/messages/useFetchOlderMessages";
 import { useIndependentThreadPanel } from "@/features/messages/useIndependentThreadPanel";
 import { useThreadReplies } from "@/features/messages/useThreadReplies";
@@ -71,6 +65,7 @@ import { useHuddleReadMarker } from "@/features/channels/ui/useHuddleReadMarker"
 import { useHuddleThreadIsolation } from "@/features/channels/ui/useHuddleThreadIsolation";
 import { AgentSessionProvider } from "@/shared/context/AgentSessionContext";
 import { ProfilePanelProvider } from "@/shared/context/ProfilePanelContext";
+import { useChannelTimelineLoading } from "@/features/channels/useChannelTimelineLoading";
 import { useMainInsetRef } from "@/shared/layout/MainInsetContext";
 import { channelContentTopPaddingMeasurement } from "@/shared/layout/chromeLayout";
 import { useMeasuredCssVariable } from "@/shared/layout/useMeasuredCssVariable";
@@ -104,7 +99,6 @@ export function ChannelScreen({
   targetMessageEvents, targetMessageId,
   ...searchTarget
 }: ChannelScreenProps) {
-  const queryClient = useQueryClient();
   const { goHome } = useAppNavigation();
   const { activeCommunity } = useCommunities();
   const {
@@ -615,30 +609,10 @@ export function ChannelScreen({
       setThreadReplyTargetId,
       setThreadScrollTargetId,
     });
-  const settledChannelIdRef = React.useRef<string | null>(null);
-  const hasSettledThisChannel =
-    activeChannelId !== null && settledChannelIdRef.current === activeChannelId;
-  const timelineLoadingNow =
-    activeChannel !== null &&
-    activeChannel.channelType !== "forum" &&
-    selectTimelineLoadingState(
-      {
-        isPending: messagesQuery.isPending,
-        isFetching: messagesQuery.isFetching,
-        isPlaceholderData: messagesQuery.isPlaceholderData,
-        dataLength: messagesQuery.data?.length ?? null,
-      },
-      hasSettledThisChannel ||
-        (activeChannelId !== null &&
-          hasPersistedHydratedChannel(queryClient, activeChannelId)),
-    );
-  const { settledChannelId, isLoading: isTimelineLoading } =
-    resolveTimelineLoadingLatch(
-      settledChannelIdRef.current,
-      activeChannelId,
-      timelineLoadingNow,
-    );
-  settledChannelIdRef.current = settledChannelId;
+  const isTimelineLoading = useChannelTimelineLoading(
+    activeChannel,
+    messagesQuery,
+  );
   const { welcomeKickoffStage, welcomeKickoffSettingUp } =
     useWelcomeKickoffStagePresence(
       activeChannel,

desktop/src/features/channels/useChannelTimelineLoading.ts

@@ -0,0 +1,55 @@
+import * as React from "react";
+import { useQueryClient } from "@tanstack/react-query";
+
+import { hasPersistedHydratedChannel } from "@/features/messages/lib/channelHeadCache";
+import {
+  resolveTimelineLoadingLatch,
+  selectTimelineLoadingState,
+} from "@/features/messages/lib/timelineLoadingState";
+import type { Channel } from "@/shared/api/types";
+
+/**
+ * Latches the timeline loading state per channel, so a channel that has
+ * already settled once does not flash its skeleton again while an
+ * authoritative refresh is in flight.
+ */
+export function useChannelTimelineLoading(
+  activeChannel: Channel | null,
+  messagesQuery: {
+    data: readonly unknown[] | undefined;
+    isFetching: boolean;
+    isPending: boolean;
+    isPlaceholderData: boolean;
+  },
+): boolean {
+  const queryClient = useQueryClient();
+  const activeChannelId = activeChannel?.id ?? null;
+  const settledChannelIdRef = React.useRef<string | null>(null);
+  const hasSettledThisChannel =
+    activeChannelId !== null && settledChannelIdRef.current === activeChannelId;
+  const timelineLoadingNow =
+    activeChannel !== null &&
+    activeChannel.channelType !== "forum" &&
+    selectTimelineLoadingState(
+      {
+        isPending: messagesQuery.isPending,
+        isFetching: messagesQuery.isFetching,
+        isPlaceholderData: messagesQuery.isPlaceholderData,
+        dataLength: messagesQuery.data?.length ?? null,
+      },
+      // A persisted head only counts as hydrated when it has rows to paint
+      // (channelHeadCache.ts), so this bypass never settles onto an empty
+      // placeholder while the authoritative refresh is still in flight.
+      hasSettledThisChannel ||
+        (activeChannelId !== null &&
+          hasPersistedHydratedChannel(queryClient, activeChannelId)),
+    );
+  const { settledChannelId, isLoading: isTimelineLoading } =
+    resolveTimelineLoadingLatch(
+      settledChannelIdRef.current,
+      activeChannelId,
+      timelineLoadingNow,
+    );
+  settledChannelIdRef.current = settledChannelId;
+  return isTimelineLoading;
+}

desktop/src/features/projects/ui/ProjectsView.tsx

@@ -172,6 +172,15 @@ export function ProjectsView() {
     snapshotProjects,
     activeCommunity?.reposDir,
   );
+  // Switch-perf hydration marker (shell commits long before the fan loads).
+  // isLoading: first load only — warm refetches/disabled queries stay false.
+  const projectsHydrating =
+    projectsQuery.isLoading ||
+    projectsWorkItemsQuery.isLoading ||
+    repoSnapshotsQuery.isLoading ||
+    activitySummariesQuery.isLoading ||
+    repositoryActivitySummariesQuery.isLoading ||
+    localRepositoriesQuery.isLoading;
   const memberChannelIds = useMemberChannelIds();
   const repositoryUnavailableReasonFor = useRepositoryUnavailableReasonFor(
     repoSnapshotsQuery.data?.unavailable,
@@ -722,6 +731,7 @@ export function ProjectsView() {
         data-project-context-detached={
           isNarrowProjectsLayout ? undefined : "true"
         }
+        data-projects-hydrating={projectsHydrating ? "true" : undefined}
         data-testid="projects-overview-layout"
       >
         <ProjectsWorkspaceChrome