highlight search terms in results and messages

desktop/src/app/AppShell.tsx

@@ -648,8 +648,8 @@ export function AppShell() {
   );
 
   const handleOpenSearchResult = React.useCallback(
-    (hit: SearchHit) => {
-      void openSearchHit(hit);
+    (hit: SearchHit, query: string) => {
+      void openSearchHit(hit, { query });
     },
     [openSearchHit],
   );

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

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+const { createSearchHighlightNavigation, parseSearchHighlightNavigation } =
+  await import("./searchHighlightNavigation.ts");
+
+test("creates trimmed transient state with a unique activation id", () => {
+  const first = createSearchHighlightNavigation("message", "  Mentions  ");
+  const second = createSearchHighlightNavigation("message", "Mentions");
+
+  assert.deepEqual(
+    { messageId: first.messageId, query: first.query },
+    { messageId: "message", query: "Mentions" },
+  );
+  assert.notEqual(first.activationId, second.activationId);
+});
+
+test("does not create highlight state for an empty query", () => {
+  assert.equal(createSearchHighlightNavigation("message", "  "), undefined);
+  assert.equal(
+    createSearchHighlightNavigation("message", undefined),
+    undefined,
+  );
+});
+
+test("parses only complete highlight navigation state", () => {
+  const state = {
+    activationId: "activation",
+    messageId: "message",
+    query: "mentions",
+  };
+
+  assert.deepEqual(parseSearchHighlightNavigation(state), state);
+  assert.equal(
+    parseSearchHighlightNavigation({ messageId: "message", query: "mentions" }),
+    null,
+  );
+  assert.equal(parseSearchHighlightNavigation(null), null);
+});

desktop/src/app/navigation/searchHighlightNavigation.ts

@@ -0,0 +1,47 @@
+export type SearchHighlightNavigation = {
+  activationId: string;
+  messageId: string;
+  query: string;
+};
+
+export function createSearchHighlightNavigation(
+  messageId: string,
+  query: string | undefined,
+): SearchHighlightNavigation | undefined {
+  const trimmedQuery = query?.trim();
+  if (!trimmedQuery) {
+    return undefined;
+  }
+
+  return {
+    activationId: crypto.randomUUID(),
+    messageId,
+    query: trimmedQuery,
+  };
+}
+
+export function parseSearchHighlightNavigation(
+  value: unknown,
+): SearchHighlightNavigation | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const candidate = value as Partial<SearchHighlightNavigation>;
+  if (
+    typeof candidate.activationId !== "string" ||
+    candidate.activationId.length === 0 ||
+    typeof candidate.messageId !== "string" ||
+    candidate.messageId.length === 0 ||
+    typeof candidate.query !== "string" ||
+    candidate.query.length === 0
+  ) {
+    return null;
+  }
+
+  return {
+    activationId: candidate.activationId,
+    messageId: candidate.messageId,
+    query: candidate.query,
+  };
+}

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

@@ -51,13 +51,53 @@ test("search-hit navigation preserves forced message routing while active", asyn
       options: {
         force: true,
         messageId: "message",
+        searchHighlight: undefined,
         threadRootId: "thread-root",
       },
     },
   ]);
   assert.equal(getCachedSearchHitEvent("message")?.id, "message");
 });
 
+test("search-hit navigation carries trimmed highlight state and forces repeated activations", async () => {
+  clearSearchHitEventCache();
+  const calls = [];
+
+  await openSearchHitWithNavigation(plainMessage, {
+    goChannel: async (channelId, options) => {
+      calls.push({ channelId, options });
+      return true;
+    },
+    goForumPost: async () => false,
+    query: "  Mentions  ",
+  });
+
+  assert.equal(calls[0].options.force, true);
+  assert.equal(calls[0].options.searchHighlight.messageId, "message");
+  assert.equal(calls[0].options.searchHighlight.query, "Mentions");
+  assert.match(calls[0].options.searchHighlight.activationId, /.+/);
+});
+
+test("forum-post search navigation carries transient same-route activation state", async () => {
+  clearSearchHitEventCache();
+  const forumPost = { ...forumComment, eventId: "post", kind: 45001 };
+  const calls = [];
+
+  await openSearchHitWithNavigation(forumPost, {
+    goChannel: async () => false,
+    goForumPost: async (channelId, postId, options) => {
+      calls.push({ channelId, postId, options });
+      return true;
+    },
+    query: "mentions",
+  });
+
+  assert.equal(calls[0].options.force, true);
+  assert.equal(calls[0].options.searchHighlight.messageId, "post");
+  assert.equal(calls[0].options.searchHighlight.query, "mentions");
+  assert.match(calls[0].options.searchHighlight.activationId, /.+/);
+});
+
 test("cancelled search-hit navigation cannot repopulate cache or route", async () => {
   clearSearchHitEventCache();
   let resolveLookup;

desktop/src/app/navigation/searchHitNavigation.ts

@@ -1,21 +1,28 @@
 import { resolveSearchHitDestination } from "@/app/navigation/resolveSearchHitDestination";
+import { createSearchHighlightNavigation } from "@/app/navigation/searchHighlightNavigation";
 import { cacheSearchHitEvent } from "@/app/navigation/searchHitEventCache";
 import type { SearchHit } from "@/shared/api/types";
 
 type SearchHitNavigationActions = {
   force?: boolean;
+  query?: string;
   goChannel: (
     channelId: string,
     options?: {
       force?: boolean;
       messageId?: string;
+      searchHighlight?: ReturnType<typeof createSearchHighlightNavigation>;
       threadRootId?: string | null;
     },
   ) => Promise<unknown>;
   goForumPost: (
     channelId: string,
     postId: string,
-    options?: { force?: boolean; replyId?: string },
+    options?: {
+      force?: boolean;
+      replyId?: string;
+      searchHighlight?: ReturnType<typeof createSearchHighlightNavigation>;
+    },
   ) => Promise<unknown>;
   signal?: AbortSignal;
 };
@@ -30,6 +37,10 @@ export async function openSearchHitWithNavigation(
   }
 
   const isLifecycleBound = Boolean(actions.signal);
+  const searchHighlight = createSearchHighlightNavigation(
+    hit.eventId,
+    actions.query,
+  );
   if (!isLifecycleBound) {
     cacheSearchHitEvent(hit);
   }
@@ -47,14 +58,16 @@ export async function openSearchHitWithNavigation(
 
   if (destination.kind === "forum-post") {
     return actions.goForumPost(destination.channelId, destination.postId, {
-      force: actions.force,
+      force: actions.force || Boolean(searchHighlight),
       replyId: destination.replyId,
+      searchHighlight,
     });
   }
 
   return actions.goChannel(destination.channelId, {
-    force: actions.force,
+    force: actions.force || Boolean(searchHighlight),
     messageId: destination.messageId,
+    searchHighlight,
     threadRootId: destination.threadRootId,
   });
 }

desktop/src/app/navigation/useAppNavigation.ts

@@ -6,6 +6,7 @@ import {
   useRouter,
 } from "@tanstack/react-router";
 
+import type { SearchHighlightNavigation } from "@/app/navigation/searchHighlightNavigation";
 import { openSearchHitWithNavigation } from "@/app/navigation/searchHitNavigation";
 import {
   allowNavigation,
@@ -32,14 +33,23 @@ export function useAppNavigation() {
         to: string;
         params?: Record<string, string>;
         search?: Record<string, string | undefined>;
-        state?: Record<string, unknown>;
+        state?:
+          | Record<string, unknown>
+          | ((
+              previousState: Record<string, unknown>,
+            ) => Record<string, unknown>);
       },
       behavior: NavigationBehavior = {},
       guardedTarget?: GuardedNavigation,
     ) => {
       const nextLocation = router.buildLocation(next as never);
+      const hasStateUpdate = next.state !== undefined;
 
-      if (location.href === nextLocation.href && !behavior.force) {
+      if (
+        location.href === nextLocation.href &&
+        !behavior.force &&
+        !hasStateUpdate
+      ) {
         return false;
       }
 
@@ -265,6 +275,9 @@ export function useAppNavigation() {
          * silently swallowed (block/buzz#3509). */
         force?: boolean;
         messageId?: string;
+        /** Preserve an active search highlight; ordinary navigation clears it. */
+        preserveSearchHighlight?: boolean;
+        searchHighlight?: SearchHighlightNavigation;
         replace?: boolean;
         /** Open this thread panel directly without waiting for a timeline row. */
         thread?: string;
@@ -290,6 +303,12 @@ export function useAppNavigation() {
             ...(options?.thread ? { thread: options.thread } : {}),
             ...(options?.autoSend ? { autoSend: options.autoSend } : {}),
           },
+          state: options?.preserveSearchHighlight
+            ? undefined
+            : (previousState: Record<string, unknown>) => ({
+                ...previousState,
+                searchHighlight: options?.searchHighlight ?? null,
+              }),
         },
         {
           force: options?.force,
@@ -329,6 +348,9 @@ export function useAppNavigation() {
         force?: boolean;
         replace?: boolean;
         replyId?: string;
+        /** Preserve an active search highlight; ordinary navigation clears it. */
+        preserveSearchHighlight?: boolean;
+        searchHighlight?: SearchHighlightNavigation;
       },
     ) => {
       return commitNavigation(
@@ -338,7 +360,15 @@ export function useAppNavigation() {
             channelId,
             postId,
           },
-          search: options?.replyId ? { replyId: options.replyId } : {},
+          search: {
+            ...(options?.replyId ? { replyId: options.replyId } : {}),
+          },
+          state: options?.preserveSearchHighlight
+            ? undefined
+            : (previousState: Record<string, unknown>) => ({
+                ...previousState,
+                searchHighlight: options?.searchHighlight ?? null,
+              }),
         },
         {
           force: options?.force,
@@ -406,6 +436,8 @@ export function useAppNavigation() {
          * Used by desktop-notification activation so a click is never
          * silently swallowed (block/buzz#3509). */
         force?: boolean;
+        /** Search text to highlight after opening this result. */
+        query?: string;
         /** Stop notification-driven routing when its owning lifecycle ends. */
         signal?: AbortSignal;
       },
@@ -414,6 +446,7 @@ export function useAppNavigation() {
         force: behavior?.force,
         goChannel,
         goForumPost,
+        query: behavior?.query,
         signal: behavior?.signal,
       }),
     [goChannel, goForumPost],