feat(web): add basic past-session search (round 1)

2026-07-27 12:15:06 +08:00
parent 79eb3a9035
commit 891e9035e7
56 changed files with 1646 additions and 269 deletions
@@ -209,6 +209,22 @@
  padding-bottom: 12px;
 }

+.list > [role='treeitem'] + [role='treeitem'] {
+  margin-top: 4px;
+}
+
+.searchStatus,
+.searchWarning {
+  padding: 10px 12px;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.searchWarning {
+  color: var(--dsw-alias-label-secondary);
+}
+
 /* One workspace section: header row + expanded session run. Rows inside
   keep the former flat-list 4px gap as sibling margins; the inter-group
   breathing room (figma 133:7661 batch separator, 20px after an expanded
@@ -13,16 +13,20 @@ import {
  Button, IconCloseFill14, IconPersonalizationOutline16,
  IconProjectAddOutline16, IconSearchOutline16, Menu, Modal, Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  SessionSearchResultItem, WorkspaceId, WorkspaceView,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type { WorkspaceBrowserProps } from './contract/slots.ts'
 import type { SessionNode } from './tree.ts'
-import { deriveFlat, deriveGroups, UNGROUPED_KEY } from './tree.ts'
-import { ProjectRowItem, SessionNodeItem } from './rows/Rows.tsx'
+import { deriveFlat, deriveGroups, deriveSearchResults, UNGROUPED_KEY } from './tree.ts'
+import { ProjectRowItem, SearchResultItem, SessionNodeItem } from './rows/Rows.tsx'
 import { WorkspaceCreateFlow } from './WorkspacePicker.tsx'
 import css from './WorkspaceBrowser.module.css'

 /** Column slide length (--ds-transition-duration-slow): rail-search focus waits it out — focus() forces a synchronous layout and would jank the slide. */
 const EXPAND_SLIDE_MS = 300
+/** Pause between the latest keystroke and a Host content-search request. */
+const SEARCH_DEBOUNCE_MS = 250

 const GROUP_BY_ITEMS = [
  { type: 'label' as const, id: 'group-by', text: 'Group by' },
@@ -83,14 +87,12 @@ type SessionTreeProps = Pick<
  'useSessions' | 'startSession' | 'open' | 'insertSessionBefore'
 > & {
  workspaces: readonly WorkspaceView[]
-  /** Live search filter owned by the browser root (the query outlives the tree). */
-  query: string
  /** Open the browser-owned rename dialog for a real Workspace group. */
  onRenameRequest: (workspaceId: WorkspaceId, currentTitle: string) => void
 }

 /** The scrolling session tree; unmounting at collapse settle drops the sessions subscription and expansion state. */
-function SessionTree({ useSessions, startSession, open, workspaces, query, onRenameRequest, insertSessionBefore }: SessionTreeProps) {
+function SessionTree({ useSessions, startSession, open, workspaces, onRenameRequest, insertSessionBefore }: SessionTreeProps) {
  const list = useSessions((s) => s)
  const current = list.current
  const [expandedProjects, setExpandedProjects] = useState<string[]>([])
@@ -106,8 +108,8 @@ function SessionTree({ useSessions, startSession, open, workspaces, query, onRen
    setExpandedProjects((l) => (l.includes(currentGroup) ? l : [...l, currentGroup]))
  }, [current, currentGroup])
  const groups = useMemo(
-    () => deriveGroups(list, workspaces, { expandedProjects, expandedSessions, query }),
-    [list, workspaces, expandedProjects, expandedSessions, query],
+    () => deriveGroups(list, workspaces, { expandedProjects, expandedSessions }),
+    [list, workspaces, expandedProjects, expandedSessions],
  )
  const now = Date.now()

@@ -115,7 +117,7 @@ function SessionTree({ useSessions, startSession, open, workspaces, query, onRen
    <div className={clsx(css.treeBody, css.wide)}>
      <div className={css.list} role="tree" aria-label="Sessions">
        {groups.length === 0 && (
-          <div className={css.empty}>{query === '' ? 'No sessions yet' : 'No matches'}</div>
+          <div className={css.empty}>No sessions yet</div>
        )}
        {groups.map(group => (
          // Group section: header row + expanded session subtree. The
@@ -136,10 +138,10 @@ function SessionTree({ useSessions, startSession, open, workspaces, query, onRen
                  }}
            />
            {group.sessions.map((node, index) => {
-              // Draggable: real-workspace group roots outside search. The drag
+              // Draggable: real-workspace group roots. The drag
              // never leaves its group — rows of other groups show no markers
              // and reject drops (visual movement confined to this section).
-              const draggable = group.workspaceId !== undefined && query === ''
+              const draggable = group.workspaceId !== undefined
              const sameGroupDrag = drag !== null && drag.workspaceId === group.workspaceId
              const dragProps = !draggable || group.workspaceId === undefined ? undefined : {
                start: () => {
@@ -192,15 +194,15 @@ function SessionTree({ useSessions, startSession, open, workspaces, query, onRen
 }

 /** The flat "In one list" body: every session a top-level row, newest-first. */
-function FlatList({ useSessions, open, query }: Pick<SessionTreeProps, 'useSessions' | 'open' | 'query'>) {
+function FlatList({ useSessions, open }: Pick<SessionTreeProps, 'useSessions' | 'open'>) {
  const list = useSessions((s) => s)
-  const rows = useMemo(() => deriveFlat(list, { query }), [list, query])
+  const rows = useMemo(() => deriveFlat(list), [list])
  const now = Date.now()
  return (
    <div className={clsx(css.treeBody, css.wide)}>
      <div className={css.list} role="tree" aria-label="Sessions">
        {rows.length === 0 && (
-          <div className={css.empty}>{query === '' ? 'No sessions yet' : 'No matches'}</div>
+          <div className={css.empty}>No sessions yet</div>
        )}
        {rows.map(node => (
          <SessionNodeItem
@@ -221,6 +223,67 @@ function FlatList({ useSessions, open, query }: Pick<SessionTreeProps, 'useSessi
  )
 }

+interface RemoteSearchState {
+  query: string
+  status: 'idle' | 'loading' | 'ready' | 'error'
+  items: readonly SessionSearchResultItem[]
+  hasMore: boolean
+}
+
+/** Flat search body: local metadata matches plus the current Host result page. */
+function SearchResults({
+  useSessions,
+  open,
+  workspaces,
+  query,
+  remote,
+}: Pick<SessionTreeProps, 'useSessions' | 'open'> & {
+  workspaces: readonly WorkspaceView[]
+  query: string
+  remote: RemoteSearchState
+}) {
+  const list = useSessions((s) => s)
+  const currentRemote = remote.query === query
+    ? remote
+    : { query, status: 'loading' as const, items: [], hasMore: false }
+  const results = useMemo(
+    () => deriveSearchResults(list, workspaces, query, currentRemote),
+    [list, workspaces, query, currentRemote],
+  )
+  const pending = currentRemote.status === 'loading'
+  const failed = currentRemote.status === 'error'
+
+  return (
+    <div className={clsx(css.treeBody, css.wide)}>
+      <div className={css.list} role="tree" aria-label="搜索结果">
+        {results.items.map(result => (
+          <SearchResultItem
+            key={result.id}
+            result={result}
+            currentId={list.current}
+            onOpen={open}
+          />
+        ))}
+        {pending && (
+          <div className={css.searchStatus} role="status">正在搜索历史…</div>
+        )}
+        {failed && (
+          <div className={css.searchWarning} role="status">
+            历史内容搜索暂时不可用，仍显示名称匹配。
+          </div>
+        )}
+        {!pending && results.items.length === 0 && (
+          <div className={css.empty}>没有匹配结果</div>
+        )}
+        {results.hasMore && (
+          <div className={css.searchStatus}>仅显示前 20 项，请缩小搜索范围。</div>
+        )}
+      </div>
+      <span className={css.fade} />
+    </div>
+  )
+}
+
 /**
 * Render the browsing region.
 * @param props - composed slot props (shell owner share + store + injected actions).
@@ -238,12 +301,20 @@ export function WorkspaceBrowser({
  renameWorkspace,
  insertSessionBefore,
  createWorkspace,
+  searchSessions,
 }: WorkspaceBrowserProps) {
  const workspaces = useWorkspaces(state => state.items)
  const groupBy = useStore(s => s.groupBy)
  // The query outlives the tree and the input (both wide-only) so collapsing
  // does not silently drop an in-progress filter.
  const [query, setQuery] = useState('')
+  const normalizedQuery = query.trim()
+  const [remoteSearch, setRemoteSearch] = useState<RemoteSearchState>({
+    query: '',
+    status: 'idle',
+    items: [],
+    hasMore: false,
+  })
  const searchInput = useRef<HTMLInputElement | null>(null)
  // Section-header ＋ opens the picker menu (same popover in wide and rail
  // states; the menu anchors on this button).
@@ -263,6 +334,43 @@ export function WorkspaceBrowser({
    }
  }, [wide, searchOnExpand])

+  useEffect(() => {
+    if (normalizedQuery === '') {
+      setRemoteSearch({ query: '', status: 'idle', items: [], hasMore: false })
+      return
+    }
+    const controller = new AbortController()
+    setRemoteSearch({
+      query: normalizedQuery,
+      status: 'loading',
+      items: [],
+      hasMore: false,
+    })
+    const timer = window.setTimeout(() => {
+      searchSessions(normalizedQuery, controller.signal).then((result) => {
+        if (controller.signal.aborted) return
+        setRemoteSearch({
+          query: normalizedQuery,
+          status: 'ready',
+          items: result.items,
+          hasMore: result.hasMore,
+        })
+      }).catch(() => {
+        if (controller.signal.aborted) return
+        setRemoteSearch({
+          query: normalizedQuery,
+          status: 'error',
+          items: [],
+          hasMore: false,
+        })
+      })
+    }, SEARCH_DEBOUNCE_MS)
+    return () => {
+      window.clearTimeout(timer)
+      controller.abort()
+    }
+  }, [normalizedQuery, searchSessions])
+
  // Rename dialog (browser-owned so it outlives row unmounts during collapse).
  const [renameTarget, setRenameTarget] = useState<{ workspaceId: WorkspaceId; currentTitle: string } | null>(null)
  const [renameDraft, setRenameDraft] = useState('')
@@ -331,11 +439,11 @@ export function WorkspaceBrowser({
      {/* Expanded: the row is a click-to-focus field (the leading icon is
          decorative). Rail: the icon is the region's search control. */}
      <div className={css.search} onClick={() => { if (wide) searchInput.current?.focus() }}>
-        <Tooltip label="Search" disabled={wide}>
+        <Tooltip label="搜索" disabled={wide}>
          <button
            type="button"
            className={css.searchButton}
-            aria-label="Search sessions"
+            aria-label="搜索会话"
            tabIndex={wide ? -1 : 0}
            onClick={() => { if (!wide) { setSearchOnExpand(true); expandSidebar() } }}
          >
@@ -347,7 +455,7 @@ export function WorkspaceBrowser({
            ref={searchInput}
            className={clsx(css.searchInput, css.wide)}
            type="text"
-            placeholder="Search name, keywords..."
+            placeholder="搜索名称或关键词…"
            value={query}
            onChange={(e) => { setQuery(e.target.value) }}
          />
@@ -356,7 +464,7 @@ export function WorkspaceBrowser({
          <button
            type="button"
            className={clsx(css.clearButton, css.wide)}
-            aria-label="Clear search"
+            aria-label="清除搜索"
            onClick={() => { setQuery('') }}
          >
            <IconCloseFill14 />
@@ -367,15 +475,24 @@ export function WorkspaceBrowser({
      {/* Always-mounted seat keeps the region's flex slot while the list
          itself is wide-only. */}
      <div className={css.listArea}>
-        {wide && (groupBy === 'flat'
-          ? <FlatList useSessions={useSessions} open={open} query={query} />
+        {wide && (normalizedQuery !== ''
+          ? (
+              <SearchResults
+                useSessions={useSessions}
+                open={open}
+                workspaces={workspaces}
+                query={normalizedQuery}
+                remote={remoteSearch}
+              />
+            )
+          : groupBy === 'flat'
+            ? <FlatList useSessions={useSessions} open={open} />
          : (
              <SessionTree
                useSessions={useSessions}
                workspaces={workspaces}
                startSession={startSession}
                open={open}
-                query={query}
                insertSessionBefore={insertSessionBefore}
                onRenameRequest={(workspaceId, currentTitle) => {
                  setRenameTarget({ workspaceId, currentTitle })
@@ -13,7 +13,9 @@ import type { PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
 // runtime shares below.
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  SessionId, SessionSearchResultItem, WorkspaceId, WorkspaceView,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type { createWorkspaceViewStore } from '../stores.ts'

 /**
@@ -30,6 +32,14 @@ export type WorkspaceBrowserInjected = {
  startSession: (workspaceId?: WorkspaceId) => void
  /** Open a real Session. */
  open: (sessionId: SessionId) => void
+  /**
+   * Search current visible conversation messages. The Host fixes the result
+   * bound; `hasMore` means the query needs narrowing.
+   */
+  searchSessions: (
+    query: string,
+    signal: AbortSignal,
+  ) => Promise<{ items: readonly SessionSearchResultItem[]; hasMore: boolean }>
  /** Rename a Host Workspace (rejects on name conflict; resolves on durability). */
  renameWorkspace: (workspaceId: WorkspaceId, title: string) => Promise<void>
  /**
@@ -33,11 +33,17 @@ export const inject = ['slots', 'sessions', 'workspaces']
 * @param ctx - client root context.
 */
 export function apply(ctx: ClientContext): void {
+  const searchSessions: WorkspaceBrowserInjected['searchSessions'] = async (query, signal) => {
+    const result = await ctx.sessions.search(query, signal)
+    if (!result.ok) throw new Error(result.error.message)
+    return result.value
+  }
  const browserInjected = (): WorkspaceBrowserInjected => ({
    // Explicit group actions keep their target; unscoped New Session rides
    // the runtime's shared action (recent-Workspace projection inside).
    startSession: (workspaceId) => { ctx.workspaces.startSession(workspaceId) },
    open: (sessionId) => { ctx.sessions.open(sessionId) },
+    searchSessions,
    renameWorkspace: async (workspaceId, title) => { await ctx.workspaces.rename(workspaceId, title) },
    insertSessionBefore: async (workspaceId, sessionId, beforeSessionId) => {
      await ctx.workspaces.insertSessionBefore(workspaceId, sessionId, beforeSessionId)
@@ -24,6 +24,64 @@
  background: var(--dsw-alias-interactive-bg-active);
 }

+.searchResultRow {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  width: 100%;
+  min-height: 62px;
+  box-sizing: border-box;
+  border: none;
+  border-radius: 8px;
+  padding: 7px 8px;
+  background: transparent;
+  cursor: pointer;
+  text-align: left;
+  color: var(--dsw-alias-label-primary);
+}
+
+.searchResultRow:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.searchResultRow.selected {
+  background: var(--dsw-alias-interactive-bg-active);
+}
+
+.searchResultHeading {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+.searchResultTitle {
+  min-width: 0;
+  margin-left: 4px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 20px;
+}
+
+.searchResultWorkspace,
+.searchResultSnippet {
+  margin-left: 20px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 12px;
+  line-height: 17px;
+}
+
+.searchResultWorkspace {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.searchResultSnippet {
+  color: var(--dsw-alias-label-secondary);
+}
+
 /* Two-line row: the leading slot (folder/chevron), title, and trailing
   actions all top-align on the 20px first text line (figma cell) — content
   is 42px (20 + 2 + 20), so 6px vertical padding centers the block. */
@@ -12,7 +12,7 @@ import {
  IconFolderClose16, IconFolderOpen16, IconPlusOutline16,
  IconTrashOutline16, IconTriangleRightFill14, Menu, StateDot,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { GroupNode, SessionNode } from '../tree.ts'
+import type { GroupNode, SearchResultNode, SessionNode } from '../tree.ts'
 import { formatRelativeTime } from '../tree.ts'
 import css from './Rows.module.css'

@@ -149,6 +149,41 @@ export interface RowDragProps {
  end: () => void
 }

+/**
+ * One flat search result: title, Workspace context, and optional content
+ * excerpt. Search navigation opens the session only; it does not address an
+ * event inside the conversation.
+ * @param props.result - merged local/content search row.
+ * @param props.currentId - selected session id.
+ * @param props.onOpen - open the selected session.
+ * @returns the result button.
+ */
+export function SearchResultItem({ result, currentId, onOpen }: {
+  result: SearchResultNode
+  currentId: string | undefined
+  onOpen: (id: SearchResultNode['id']) => void
+}) {
+  const selected = result.id === currentId
+  return (
+    <button
+      type="button"
+      className={clsx(css.searchResultRow, selected && css.selected)}
+      role="treeitem"
+      aria-selected={selected}
+      onClick={() => { onOpen(result.id) }}
+    >
+      <span className={css.searchResultHeading}>
+        <span className={css.slot}>{result.running && <StateDot state="ongoing" />}</span>
+        <span className={css.searchResultTitle}>{result.title}</span>
+      </span>
+      <span className={css.searchResultWorkspace}>{result.workspace}</span>
+      {result.snippet !== undefined && (
+        <span className={css.searchResultSnippet}>{result.snippet}</span>
+      )}
+    </button>
+  )
+}
+
 /** Pointer-position half of a row (insert line above or below). */
 function rowHalf(e: { clientY: number; currentTarget: HTMLElement }): 'before' | 'after' {
  const rect = e.currentTarget.getBoundingClientRect()
@@ -3,7 +3,9 @@
 * Unassigned Sessions trail under Ungrouped; only the selected blank Session
 * remains visible.
 */
-import type { SessionId, SessionListState, SessionSummary, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  SessionId, SessionListState, SessionSearchResultItem, SessionSummary, WorkspaceId, WorkspaceView,
+} from '@deepseek-ai/dsh-client-runtime/client'

 /** Group key for Sessions outside every Workspace. */
 export const UNGROUPED_KEY = ''
@@ -15,7 +17,7 @@ export const UNGROUPED_LABEL = 'Ungrouped'
 export interface SessionNode {
  id: SessionId
  title: string
-  /** Visible children, already expansion/search-filtered (empty when folded). */
+  /** Visible children, already expansion-filtered (empty when folded). */
  children: readonly SessionNode[]
  /** The session HAS children in the data (the twist renders even while folded). */
  hasChildren: boolean
@@ -41,11 +43,25 @@ export interface GroupNode {
  sessions: readonly SessionNode[]
 }

+/** One flat search row combining list metadata with an optional content match. */
+export interface SearchResultNode {
+  id: SessionId
+  title: string
+  workspace: string
+  running: boolean
+  snippet?: string
+}
+
+/** Bounded merged search projection plus the refine-query hint bit. */
+export interface SearchResultSet {
+  items: readonly SearchResultNode[]
+  hasMore: boolean
+}
+
 /** Viewing state consumed by the derivation — the component's local useState arrays, taken as-is. */
 export interface TreeView {
  expandedProjects: readonly string[]
  expandedSessions: readonly string[]
-  query: string
 }

 interface Group {
@@ -204,47 +220,15 @@ function buildVisible(g: Group, expandedSessions: ReadonlySet<string>): SessionN
  return g.roots.map(walk).filter((n): n is SessionNode => n !== null)
 }

-/** Matched sessions plus their ancestor chains (forced visible under search). */
-function searchVisible(g: Group, q: string): Set<SessionId> {
-  const visible = new Set<SessionId>()
-  for (const m of g.summaries.values()) {
-    if (!sessionTitle(m).toLowerCase().includes(q)) continue
-    let cur: SessionSummary | undefined = m
-    while (cur !== undefined && !visible.has(cur.id)) {
-      visible.add(cur.id)
-      cur = cur.parentId !== undefined && cur.parentId !== cur.id ? g.summaries.get(cur.parentId) : undefined
-    }
-  }
-  return visible
-}
-
-function buildSearch(g: Group, visible: ReadonlySet<SessionId>): SessionNode[] {
-  const visited = new Set<SessionId>()
-  const walk = (id: SessionId): SessionNode | null => {
-    if (visited.has(id) || !visible.has(id)) return null
-    visited.add(id)
-    const s = g.summaries.get(id)
-    /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */
-    if (s === undefined) return null
-    const kids = (g.children.get(id) ?? []).filter(kid => visible.has(kid))
-    const children = kids.map(walk).filter((n): n is SessionNode => n !== null)
-    return sessionNode(s, children, kids.length > 0, kids.length > 0)
-  }
-  return g.roots.map(walk).filter((n): n is SessionNode => n !== null)
-}
-
 /**
 * Derive the nested workspace browser group structure.
 *
- * Normal mode: every group shows; sessions populate under expanded groups,
- * descending only into expanded sessions. Search mode (non-blank query,
- * case-insensitive display-title substring): expansion state is ignored —
- * matched sessions and their ancestor chains are forced visible, groups
- * without a display-title or label hit are dropped, and a label-only hit
- * keeps the bare group header. Blank sessions are excluded everywhere.
+ * Every group shows; sessions populate under expanded groups, descending
+ * only into expanded sessions. Blank sessions are excluded except for the
+ * selected provisional New Session row.
 * @param list - sessions list snapshot (`current` feeds containsCurrent).
 * @param workspaces - real workspaces in stable Host order.
- * @param view - local expansion arrays and search query.
+ * @param view - local expansion arrays.
 * @returns group sections in render order.
 */
 export function deriveGroups(
@@ -252,7 +236,6 @@ export function deriveGroups(
  workspaces: readonly WorkspaceView[],
  view: TreeView,
 ): GroupNode[] {
-  const q = view.query.trim().toLowerCase()
  const expandedProjects = new Set(view.expandedProjects)
  const expandedSessions = new Set(view.expandedSessions)
  const currentGroup = list.current === undefined
@@ -261,32 +244,17 @@ export function deriveGroups(
        ?? UNGROUPED_KEY
  const groups: GroupNode[] = []
  for (const g of groupByWorkspace(list, workspaces)) {
-    if (q === '') {
-      const expanded = expandedProjects.has(g.key)
-      groups.push({
-        key: g.key,
-        workspaceId: g.workspaceId,
-        cwd: g.cwd,
-        label: g.label,
-        sessionCount: g.summaries.size,
-        expanded,
-        containsCurrent: g.key === currentGroup,
-        sessions: expanded ? buildVisible(g, expandedSessions) : [],
-      })
-    } else {
-      const visible = searchVisible(g, q)
-      if (visible.size === 0 && !g.label.toLowerCase().includes(q)) continue
-      groups.push({
-        key: g.key,
-        workspaceId: g.workspaceId,
-        cwd: g.cwd,
-        label: g.label,
-        sessionCount: g.summaries.size,
-        expanded: visible.size > 0,
-        containsCurrent: g.key === currentGroup,
-        sessions: buildSearch(g, visible),
-      })
-    }
+    const expanded = expandedProjects.has(g.key)
+    groups.push({
+      key: g.key,
+      workspaceId: g.workspaceId,
+      cwd: g.cwd,
+      label: g.label,
+      sessionCount: g.summaries.size,
+      expanded,
+      containsCurrent: g.key === currentGroup,
+      sessions: expanded ? buildVisible(g, expandedSessions) : [],
+    })
  }
  return groups
 }
@@ -295,25 +263,97 @@ export function deriveGroups(
 * Derive the flat session list ("In one list" mode): every session — fork
 * children included — as a top-level row, strictly newest-first. No grouping,
 * no parent/child adjacency; rows reuse SessionNode with children always
- * empty so the renderer stays branch-free. Search mode filters by
- * case-insensitive display-title substring.
+ * empty so the renderer stays branch-free.
 * @param list - sessions list snapshot.
- * @param view - the search query (expansion state does not apply).
 * @returns flat rows in render order.
 */
-export function deriveFlat(list: SessionListState, view: Pick<TreeView, 'query'>): SessionNode[] {
-  const q = view.query.trim().toLowerCase()
+export function deriveFlat(list: SessionListState): SessionNode[] {
  const rows: SessionSummary[] = []
  for (const id of list.ids) {
    const s = list.byId[id]
    if (s === undefined || !sessionVisible(s, list.current)) continue
-    if (q !== '' && !sessionTitle(s).toLowerCase().includes(q)) continue
    rows.push(s)
  }
  rows.sort(byRecency)
  return rows.map(s => sessionNode(s, [], false, false))
 }

+/** Maximum rows rendered by the basic search surface. */
+const SEARCH_RESULT_LIMIT = 20
+
+/**
+ * Merge immediate title/Workspace substring matches with ranked Host content
+ * matches. Local rows lead newest-first, content-only rows retain backend
+ * order, and duplicate sessions receive the backend snippet in place.
+ * @param list - session metadata authority.
+ * @param workspaces - Workspace membership and display labels.
+ * @param query - caller text; surrounding whitespace is ignored.
+ * @param content - ranked Host content-search page.
+ * @returns at most 20 deduplicated flat rows and a refine-query hint bit.
+ */
+export function deriveSearchResults(
+  list: SessionListState,
+  workspaces: readonly WorkspaceView[],
+  query: string,
+  content: { items: readonly SessionSearchResultItem[]; hasMore: boolean },
+): SearchResultSet {
+  const q = query.trim().toLowerCase()
+  if (q === '') return { items: [], hasMore: false }
+
+  const workspaceBySession = new Map<SessionId, string>()
+  for (const workspace of workspaces) {
+    for (const sessionId of workspace.sessionIds) {
+      if (!workspaceBySession.has(sessionId)) workspaceBySession.set(sessionId, workspace.title)
+    }
+  }
+  const labelOf = (summary: SessionSummary): string =>
+    workspaceBySession.get(summary.id) ?? projectLabel(summary.cwd)
+  const contentBySession = new Map<SessionId, SessionSearchResultItem>()
+  for (const item of content.items) {
+    if (!contentBySession.has(item.sessionId)) contentBySession.set(item.sessionId, item)
+  }
+
+  const local: SessionSummary[] = []
+  for (const id of list.ids) {
+    const summary = list.byId[id]
+    if (summary === undefined || !sessionVisible(summary, list.current)) continue
+    if (
+      sessionTitle(summary).toLowerCase().includes(q)
+      || labelOf(summary).toLowerCase().includes(q)
+    ) {
+      local.push(summary)
+    }
+  }
+  local.sort(byRecency)
+
+  const ordered: SessionSummary[] = []
+  const included = new Set<SessionId>()
+  const include = (summary: SessionSummary): void => {
+    if (included.has(summary.id)) return
+    included.add(summary.id)
+    ordered.push(summary)
+  }
+  for (const summary of local) include(summary)
+  for (const item of content.items) {
+    const summary = list.byId[item.sessionId]
+    if (summary !== undefined && sessionVisible(summary, list.current)) include(summary)
+  }
+
+  return {
+    items: ordered.slice(0, SEARCH_RESULT_LIMIT).map((summary) => {
+      const match = contentBySession.get(summary.id)
+      return {
+        id: summary.id,
+        title: sessionTitle(summary),
+        workspace: labelOf(summary),
+        running: summary.running,
+        ...match === undefined ? {} : { snippet: match.snippet },
+      }
+    }),
+    hasMore: content.hasMore || ordered.length > SEARCH_RESULT_LIMIT,
+  }
+}
+
 /**
 * Compact relative time for session rows ("now", "5min", "3h", "2d", "4mo", "1y").
 * @param updatedAt - epoch ms of the session's last activity.