@steerable/agent-shell-web 0.6.65 → 0.6.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell-web",
-  "version": "0.6.65",
+  "version": "0.6.67",
   "type": "module",
   "description": "Steerable framework — product-neutral renderer SPA source for @steerable/agent-shell (React + Vite). Consumed by product web entry points via the `@/` alias (anchored at this package's src/) and the createProductViteConfig factory. Published as a source package (src/), plus the compiled vite.base config factory (vite.base.js + .d.ts) for Node-side config loading.",
   "license": "Apache-2.0",
@@ -45,8 +45,8 @@
     "react-router-dom": "^6.30.0",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
-    "@steerable/agent-protocol": "0.6.65",
-    "@steerable/agent-ui": "0.6.65"
+    "@steerable/agent-protocol": "0.6.67",
+    "@steerable/agent-ui": "0.6.67"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.0",
@@ -59,7 +59,7 @@
     "typescript": "^5.8.3",
     "vite": "^5.4.21",
     "vitest": "^3.2.4",
-    "@steerable/pack-sdk": "0.6.65"
+    "@steerable/pack-sdk": "0.6.67"
   },
   "scripts": {
     "gen": "echo agent-shell-web",

package/src/components/AgentSidebar.tsx

@@ -56,8 +56,8 @@
  *   │ ✎ 新对话                        │  ← 只打开落地页，有内容才落库
  *   │ 🧩 插件                         │ ← /settings?section=plugins（智能体 / Skills / MCP / 网络搜索）
  *   │  会话 v                     📁+ │ ← 📁+ 打开新建项目弹窗
- *   │  v 📁 项目A          (hover: ✎··)│ ← ✎ 新建对话；·· 菜单：重命名/换目录/访达/删
- *   │   ...（项目内对话）              │
+ *   │  v 📁 项目A          (hover: ✎··)│ ← 拖拽组头排序；✎ 新建对话；·· 菜单：重命名/换目录/访达/删
+ *   │   ...（项目内对话，超过 5 条再展开）│
  *   │   今天                          │
  *   │   ...（无项目对话，按日期分组）  │ ← 无项目排在项目分组之后
  *   ├─────────────────────────────────┤
@@ -109,7 +109,11 @@ import {
 import { usePendingAskUserChatIds } from "@/components/chat/AskUserPromptProvider";
 import { usePendingApprovalChatIds } from "@/components/chat/ApprovalPromptProvider";
 import type { UseChatsAndAgentsResult } from "@/hooks/useChatsAndAgents";
-import { useProjects } from "@/hooks/useProjects";
+import { persistProjectOrder, useProjects } from "@/hooks/useProjects";
+import {
+  nextProjectOrder,
+  type ProjectDropPlace,
+} from "@/lib/project-order";
 import type { RightPanelState } from "@/layouts/AgentLayout";
 import { BrandLockup } from "@/components/BrandLockup";
 import { ConfirmDialog } from "@/components/ConfirmDialog";
@@ -121,6 +125,48 @@ import { SidebarAccount } from "@/components/SidebarAccount";
 import { CreateProjectModal } from "@/components/CreateProjectModal";
 import { t } from "@/i18n";
 
+function projectDropPlace(element: HTMLElement, clientY: number): ProjectDropPlace {
+  const rect = element.getBoundingClientRect();
+  return clientY < rect.top + rect.height / 2 ? "before" : "after";
+}
+
+/** 项目里先露出的普通会话条数。每一次「显示更多」再露出同样多条。 */
+const PROJECT_CHAT_PAGE = 5;
+
+/**
+ * 进行中、等待输入的会话保持原位，不占用这 5 条名额。
+ * 当前打开的会话如果落在名额之外，仍单独留在列表里。
+ */
+function visibleProjectChats<T extends { id: string }>(
+  items: readonly T[],
+  limit: number,
+  options: {
+    currentId?: string;
+    isAlwaysVisible: (chat: T) => boolean;
+  },
+): { rows: T[]; hiddenCount: number } {
+  let ordinary = 0;
+  const kept = new Set<string>();
+  for (const chat of items) {
+    if (options.isAlwaysVisible(chat)) {
+      kept.add(chat.id);
+      continue;
+    }
+    if (ordinary < limit) {
+      kept.add(chat.id);
+      ordinary += 1;
+    }
+  }
+  if (
+    options.currentId &&
+    items.some((chat) => chat.id === options.currentId)
+  ) {
+    kept.add(options.currentId);
+  }
+  const rows = items.filter((chat) => kept.has(chat.id));
+  return { rows, hiddenCount: items.length - rows.length };
+}
+
 function placeProjectMenu(anchor: HTMLElement): { top: number; left: number } {
   const box = anchor.getBoundingClientRect();
   const width = 224;
@@ -481,6 +527,10 @@ export function AgentSidebar({
   const [collapsedProjectIds, setCollapsedProjectIds] = useState<Set<string>>(
     () => new Set(),
   );
+  // 每个项目已展开的普通会话名额。缺省是 PROJECT_CHAT_PAGE；Infinity 表示已全部展开。
+  const [projectChatLimits, setProjectChatLimits] = useState<
+    Record<string, number>
+  >({});
   const [renamingProjectId, setRenamingProjectId] = useState<string | null>(
     null,
   );
@@ -497,6 +547,37 @@ export function AgentSidebar({
     id: string;
     anchor: HTMLElement;
   } | null>(null);
+  const draggingProjectIdRef = useRef<string | null>(null);
+  const projectDragMovedRef = useRef(false);
+  const [draggingProjectId, setDraggingProjectId] = useState<string | null>(
+    null,
+  );
+  const [dropTarget, setDropTarget] = useState<{
+    id: string;
+    place: ProjectDropPlace;
+  } | null>(null);
+
+  const endProjectDrag = useCallback(() => {
+    draggingProjectIdRef.current = null;
+    setDraggingProjectId(null);
+    setDropTarget(null);
+    // dragend 之后浏览器有时还会补一次 click。等这次 click 过去再清标记，
+    // 避免松手把项目折叠掉；下一次真正的点击仍能折叠。
+    window.setTimeout(() => {
+      projectDragMovedRef.current = false;
+    }, 0);
+  }, []);
+
+  useEffect(() => {
+    if (!draggingProjectId) return;
+    const { cursor, userSelect } = document.body.style;
+    document.body.style.cursor = "grabbing";
+    document.body.style.userSelect = "none";
+    return () => {
+      document.body.style.cursor = cursor;
+      document.body.style.userSelect = userSelect;
+    };
+  }, [draggingProjectId]);
 
   const showProjectsChrome = hostToolChrome("projects");
 
@@ -592,14 +673,49 @@ export function AgentSidebar({
     }
   }, []);
 
-  const toggleProjectCollapsed = useCallback((projectId: string) => {
-    setCollapsedProjectIds((prev) => {
-      const next = new Set(prev);
-      if (next.has(projectId)) next.delete(projectId);
-      else next.add(projectId);
-      return next;
-    });
-  }, []);
+  const toggleProjectCollapsed = useCallback(
+    (projectId: string) => {
+      const collapsing = !collapsedProjectIds.has(projectId);
+      setCollapsedProjectIds((prev) => {
+        const next = new Set(prev);
+        if (next.has(projectId)) next.delete(projectId);
+        else next.add(projectId);
+        return next;
+      });
+      // 收起项目后再打开，回到最初的 5 条，不记住上次展开到第几页。
+      if (collapsing) {
+        setProjectChatLimits((limits) => {
+          if (limits[projectId] === undefined) return limits;
+          const next = { ...limits };
+          delete next[projectId];
+          return next;
+        });
+      }
+    },
+    [collapsedProjectIds],
+  );
+
+  const revealMoreProjectChats = useCallback(
+    (projectId: string, hiddenCount: number) => {
+      setProjectChatLimits((limits) => {
+        if (hiddenCount === 0) {
+          if (limits[projectId] === undefined) return limits;
+          const next = { ...limits };
+          delete next[projectId];
+          return next;
+        }
+        const current = limits[projectId] ?? PROJECT_CHAT_PAGE;
+        return {
+          ...limits,
+          [projectId]:
+            hiddenCount <= PROJECT_CHAT_PAGE
+              ? Number.POSITIVE_INFINITY
+              : current + PROJECT_CHAT_PAGE,
+        };
+      });
+    },
+    [],
+  );
 
   // Keep the shared "next new chat" agent aligned with the current chat. The
   // actual picker now lives in ChatInput, so the sidebar no longer renders the
@@ -918,6 +1034,22 @@ export function AgentSidebar({
 
   const hasElectron = hasHostBridge();
 
+  const projectChatWindow = (
+    items: typeof normalizedChats,
+    limit: number,
+  ) =>
+    visibleProjectChats(items, limit, {
+      currentId: currentChatId,
+      isAlwaysVisible: (chat) =>
+        Boolean(
+          chat.isStreaming ||
+            streamingChatIds.has(chat.id) ||
+            chat.needsUserInput ||
+            pendingAskUserChatIds.has(chat.id) ||
+            pendingApprovalChatIds.has(chat.id),
+        ),
+    });
+
   return (
     <div className="flex h-full w-full flex-col border-r border-agent-border/60 bg-agent-muted/70 backdrop-blur-md">
       {/* ───── Brand + actions ───── */}
@@ -1059,8 +1191,75 @@ export function AgentSidebar({
                         </div>
                       ) : (
                         projectGroups.map(({ project, items }) => (
-                          <div key={project.id} className="mb-1">
-                            <div className="group/proj relative">
+                          <div
+                            key={project.id}
+                            data-testid="sidebar-project"
+                            data-project-id={project.id}
+                            className="relative pb-1"
+                            onDragOver={(event) => {
+                              if (!draggingProjectIdRef.current) return;
+                              event.preventDefault();
+                              if (event.dataTransfer) event.dataTransfer.dropEffect = "move";
+                              const place = projectDropPlace(
+                                event.currentTarget,
+                                event.clientY,
+                              );
+                              setDropTarget((current) =>
+                                current?.id === project.id && current.place === place
+                                  ? current
+                                  : { id: project.id, place },
+                              );
+                            }}
+                            onDragLeave={(event) => {
+                              const next = event.relatedTarget;
+                              if (
+                                next instanceof Node &&
+                                event.currentTarget.contains(next)
+                              ) {
+                                return;
+                              }
+                              setDropTarget((current) =>
+                                current?.id === project.id ? null : current,
+                              );
+                            }}
+                            onDrop={(event) => {
+                              event.preventDefault();
+                              const fromId = draggingProjectIdRef.current;
+                              const place = projectDropPlace(
+                                event.currentTarget,
+                                event.clientY,
+                              );
+                              endProjectDrag();
+                              if (!fromId) return;
+                              const next = nextProjectOrder(
+                                projectGroups.map((group) => group.project.id),
+                                fromId,
+                                project.id,
+                                place,
+                              );
+                              if (!next) return;
+                              void persistProjectOrder(next).catch((err) => {
+                                setProjectError(
+                                  err instanceof Error ? err.message : String(err),
+                                );
+                              });
+                            }}
+                          >
+                            {dropTarget?.id === project.id && draggingProjectId ? (
+                              <div
+                                className={[
+                                  "pointer-events-none absolute inset-x-2 z-10 h-0.5 rounded-full bg-agent-foreground",
+                                  dropTarget.place === "before" ? "top-0" : "bottom-1",
+                                ].join(" ")}
+                                data-testid="sidebar-project-drop-indicator"
+                              />
+                            ) : null}
+                            <div
+                              className={[
+                                "group/proj relative",
+                                draggingProjectId === project.id ? "opacity-40" : "",
+                              ].join(" ")}
+                            >
                               {renamingProjectId === project.id ? (
                                 <form
                                   className="flex items-center px-2.5 pb-1 pt-1.5"
@@ -1087,8 +1286,31 @@ export function AgentSidebar({
                                 <>
                                   <button
                                     type="button"
-                                    onClick={() => toggleProjectCollapsed(project.id)}
-                                    className="flex w-full min-w-0 items-center px-2 pb-0.5 pt-1 text-[11px] font-medium text-agent-muted-foreground/90 transition-colors hover:text-agent-foreground"
+                                    draggable
+                                    data-testid="sidebar-project-handle"
+                                    data-project-id={project.id}
+                                    onDragStart={(event) => {
+                                      projectDragMovedRef.current = true;
+                                      draggingProjectIdRef.current = project.id;
+                                      setDraggingProjectId(project.id);
+                                      const transfer = event.dataTransfer;
+                                      if (!transfer) return;
+                                      transfer.effectAllowed = "move";
+                                      try {
+                                        transfer.setData("text/plain", project.name);
+                                      } catch (error) {
+                                        // 排序状态记在 ref 里。个别环境拒绝写入 DataTransfer。
+                                        void error;
+                                      }
+                                    }}
+                                    onDragEnd={() => {
+                                      endProjectDrag();
+                                    }}
+                                    onClick={() => {
+                                      if (projectDragMovedRef.current) return;
+                                      toggleProjectCollapsed(project.id);
+                                    }}
+                                    className="flex w-full min-w-0 cursor-grab items-center px-2 pb-0.5 pt-1 text-[11px] font-medium text-agent-muted-foreground/90 transition-colors hover:text-agent-foreground active:cursor-grabbing"
                                     title={`${project.name}\n${project.folderPath}`}
                                   >
                                     <LuFolder className="mr-1 h-3.5 w-3.5 shrink-0" />
@@ -1106,8 +1328,8 @@ export function AgentSidebar({
                                   <div
                                     className={`absolute right-1 top-1/2 flex -translate-y-1/2 items-center gap-0.5 transition-opacity ${
                                       projectMenu?.id === project.id
-                                        ? "opacity-100"
-                                        : "opacity-0 group-hover/proj:opacity-100"
+                                        ? "pointer-events-auto opacity-100"
+                                        : "pointer-events-none opacity-0 group-hover/proj:pointer-events-auto group-hover/proj:opacity-100"
                                     }`}
                                   >
                                     <button
@@ -1146,7 +1368,45 @@ export function AgentSidebar({
                                     {t("No chats yet. Hover the project name and click + to start one.")}
                                   </div>
                                 ) : (
-                                  items.map((chat) => renderChatRow(chat))
+                                  (() => {
+                                    const limit =
+                                      projectChatLimits[project.id] ??
+                                      PROJECT_CHAT_PAGE;
+                                    const folded = projectChatWindow(
+                                      items,
+                                      PROJECT_CHAT_PAGE,
+                                    );
+                                    const shown = projectChatWindow(items, limit);
+                                    const fullyShown = shown.hiddenCount === 0;
+                                    return (
+                                      <>
+                                        {shown.rows.map((chat) =>
+                                          renderChatRow(chat),
+                                        )}
+                                        {folded.hiddenCount > 0 && (
+                                          <button
+                                            type="button"
+                                            data-testid="sidebar-project-show-more"
+                                            data-project-id={project.id}
+                                            aria-expanded={fullyShown}
+                                            onClick={() =>
+                                              revealMoreProjectChats(
+                                                project.id,
+                                                shown.hiddenCount,
+                                              )
+                                            }
+                                            className="flex h-7 w-full items-center rounded-full px-2.5 text-left text-[11px] text-agent-muted-foreground/80 transition-colors hover:bg-agent-foreground/5 hover:text-agent-foreground"
+                                          >
+                                            {fullyShown
+                                              ? t("Show less")
+                                              : t("Show {count} more", {
+                                                  count: shown.hiddenCount,
+                                                })}
+                                          </button>
+                                        )}
+                                      </>
+                                    );
+                                  })()
                                 )}
                               </div>
                             )}

package/src/components/chat/ChatInput.tsx

@@ -32,7 +32,13 @@ import {
 import type { LocalChat, LocalChatAgent } from '@/lib/local-api';
 import type { ExecPolicy } from '@/lib/exec-policy';
 import { getWebChatModes, hostToolCapability, settingsChrome } from '@/lib/host-tools';
-import { hostClipboardAvailable, requestHostPaste, type HostClipboardFile } from '@/lib/host-paste';
+import {
+  hostClipboardAvailable,
+  releaseComposerPasteTarget,
+  requestHostPaste,
+  setComposerPasteTarget,
+  type HostClipboardFile,
+} from '@/lib/host-paste';
 import { attachmentFromPath, type AttachmentFile } from '@/lib/attachments';
 import { dropPointHitsRect, hostFileDropAvailable, listenHostFileDrop } from '@/lib/host-file-drop';
 import type { SteerOutcome } from '@steerable/agent-ui';
@@ -510,10 +516,17 @@ function getSelectionOffsets(root: HTMLDivElement): { start: number; end: number
     return measureRange.toString().length;
   };
 
-  return {
-    start: getOffset(range.startContainer, range.startOffset),
-    end: getOffset(range.endContainer, range.endOffset),
-  };
+  try {
+    return {
+      start: getOffset(range.startContainer, range.startOffset),
+      end: getOffset(range.endContainer, range.endOffset),
+    };
+  } catch {
+    // The caret can sit on the empty scaffold's <br> with an offset the
+    // range rejects. Paste still belongs at the end of the draft.
+    const end = getEditableText(root).length;
+    return { start: end, end };
+  }
 }
 
 function setCaretOffset(root: HTMLDivElement, offset: number) {
@@ -1149,6 +1162,10 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
         return;
       }
 
+      const wrote =
+        editorText !== value ||
+        pendingCaretOffset !== null ||
+        (!value && !hasEmptyImeScaffold(editor));
       if (editorText !== value || pendingCaretOffset !== null) {
         writeEditorValue(
           editor,
@@ -1167,8 +1184,10 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
       lastPushedValueRef.current = value;
       updateEditorHeight(editor);
 
-      if (pendingCaretOffset !== null && focused) {
-        setCaretOffset(editor, Math.min(pendingCaretOffset, value.length));
+      // replaceChildren drops the DOM selection. Without a caret inside the
+      // field, WKWebView ignores Ctrl/Cmd+V after a send.
+      if (focused && wrote) {
+        setCaretOffset(editor, Math.min(pendingCaretOffset ?? value.length, value.length));
         pendingCaretOffsetRef.current = null;
       }
     }, [value, mentionReferences, agents, chats, disabled, skills, mcpTools]);
@@ -1494,6 +1513,7 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
     useLayoutEffect(() => {
       const editor = editorRef.current;
       if (!editor) return;
+      setComposerPasteTarget(editor);
       const onCompositionStart = () => {
         isComposingRef.current = true;
         inputSyncGenRef.current += 1;
@@ -1519,6 +1539,7 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
       editor.addEventListener('hostpaste', onHostPaste);
       editor.addEventListener('hostpastefiles', onHostPasteFiles);
       return () => {
+        releaseComposerPasteTarget(editor);
         editor.removeEventListener('compositionstart', onCompositionStart, true);
         editor.removeEventListener('hostpaste', onHostPaste);
         editor.removeEventListener('hostpastefiles', onHostPasteFiles);

package/src/components/chat/LocalChatPanel.tsx

@@ -224,10 +224,13 @@ export function LocalChatPanel({
   const [attachmentError, setAttachmentError] = useState<string | null>(null);
   const [mentionReferences, setMentionReferences] = useState<MentionReference[]>([]);
   const inputRef = useRef<ChatInputHandle>(null);
+  // 空会话首屏和对话底部各有一棵输入框。发出第一条消息会卸掉正在聚焦的那棵；
+  // 不重新聚焦的话，Ctrl/Cmd+V 没有落点。
+  const showEmptyHero = Boolean(emptyHero) && messages.length === 0 && !isStreaming;
 
   useEffect(() => {
     inputRef.current?.focusAtEnd();
-  }, [chatId]);
+  }, [chatId, showEmptyHero]);
 
   const handleSelectPrompt = useCallback((prompt: string) => {
     setInputValue(prompt);
@@ -315,9 +318,6 @@ export function LocalChatPanel({
     }
   }, [inputValue, files, mentionReferences, onSubmit, mode, execPolicy, chatId, selectedAgentId]);
 
-  // 空会话 hero：messages 为空且未在流式时整面板切到居中首屏布局。
-  const showEmptyHero = Boolean(emptyHero) && messages.length === 0 && !isStreaming;
-
   const sessionTodos = useMemo(
     () =>
       resolveLatestSessionTodos({

package/src/components/chat/MessageList.tsx

@@ -21,7 +21,8 @@ import type { InspectTaskInput } from './executed-actions-model';
 import type { ChildInfo } from './OrchestrationChildrenCard';
 import type { ChatMode } from './ChatInput';
 import type { TurnBlock } from './turn-timeline';
-import type { TurnFile } from './turn-files';
+import { followedPreviewPath, type TurnFile } from './turn-files';
+import { publishConversationPreview } from '@/layouts/conversation-preview';
 import { inferDurationMs, readPersistedDurationMs } from './elapsed';
 import type { LlmSpeedSnapshot } from './process-status';
 
@@ -54,6 +55,27 @@ import type { LlmSpeedSnapshot } from './process-status';
 
 const NEAR_BOTTOM_THRESHOLD_PX = 100;
 
+/** 视口上三分之一附近的助手消息，当作当前正在看的回合。 */
+function assistantIdInView(container: HTMLElement): string | null {
+  const bounds = container.getBoundingClientRect();
+  const anchor = bounds.top + container.clientHeight * 0.35;
+  const nodes = container.querySelectorAll<HTMLElement>(
+    '[data-message-role="assistant"][data-message-id]',
+  );
+  let bestId: string | null = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const node of nodes) {
+    const rect = node.getBoundingClientRect();
+    if (rect.bottom < bounds.top || rect.top > bounds.bottom) continue;
+    const distance = Math.abs(rect.top - anchor);
+    const messageId = node.getAttribute('data-message-id');
+    if (!messageId || distance >= bestDistance) continue;
+    bestId = messageId;
+    bestDistance = distance;
+  }
+  return bestId;
+}
+
 function internalTrigger(message: ChatMessage): 'goal' | 'loop' | null {
   if (!message.messageMetadata) return null;
   try {
@@ -240,6 +262,41 @@ export function MessageList({
     };
   }, [checkAtBottom]);
 
+  // 右侧预览跟着这一屏在看的回合。停在底部时用最近一份能打开的产物。
+  useEffect(() => {
+    if (!chatId) return;
+    const publish = () => {
+      const el = containerRef.current;
+      if (!el) return;
+      const atBottom =
+        el.scrollHeight - el.scrollTop - el.clientHeight < NEAR_BOTTOM_THRESHOLD_PX;
+      const ordered = visibleMessages
+        .filter((message) => message.role === 'assistant')
+        .map((message) => ({
+          id: message.id,
+          files: message.id === lastAssistantId
+            ? (turnFilesByMessageId?.[message.id] ?? currentTurnFiles)
+            : turnFilesByMessageId?.[message.id],
+        }));
+      const selected = followedPreviewPath(ordered, {
+        atBottom,
+        focusedId: atBottom ? null : assistantIdInView(el),
+      });
+      if (!selected) return;
+      publishConversationPreview({
+        chatId,
+        messageId: selected.messageId,
+        path: selected.path,
+      });
+    };
+    publish();
+    const el = containerRef.current;
+    el?.addEventListener('scroll', publish, { passive: true });
+    return () => {
+      el?.removeEventListener('scroll', publish);
+    };
+  }, [chatId, currentTurnFiles, lastAssistantId, messages, turnFilesByMessageId]);
+
   // Snap to bottom on first paint, regardless of whether the user "was" at
   // the bottom — there's no "before" on mount.
   useLayoutEffect(() => {

package/src/components/chat/turn-files.ts

@@ -388,3 +388,60 @@ export function groupTurnFiles(
 
   return { deliverables, intermediates, totalAdditions, totalDeletions };
 }
+
+/** 右侧栏能直接打开的扩展名。交付物优先，同层里靠前的类型优先。 */
+const RIGHT_PREVIEW_EXTENSIONS = [
+  '.pptx', // shell-neutral:allow — Office 幻灯片扩展名，不是产品品牌
+  '.ppt', // shell-neutral:allow — Office 幻灯片扩展名，不是产品品牌
+  '.docx',
+  '.doc',
+  '.md',
+  '.markdown',
+];
+
+/**
+ * 这一轮在右侧栏里该显示的文件。
+ * 交付物压过脚本和中间产物；同一层里幻灯片、文档、Markdown 依次优先。
+ */
+export function previewPathForTurn(files: readonly TurnFile[] | undefined): string | null {
+  if (!files || files.length === 0) return null;
+  let best: { path: string; rank: number; deliverable: boolean } | null = null;
+  for (const file of files) {
+    if (isIgnoredTurnFile(file.path)) continue;
+    const rank = RIGHT_PREVIEW_EXTENSIONS.indexOf(getFileExtension(file.path));
+    if (rank < 0) continue;
+    const deliverable = getTurnFileCategory(file) === 'deliverable';
+    if (
+      !best
+      || (deliverable && !best.deliverable)
+      || (deliverable === best.deliverable && rank < best.rank)
+    ) {
+      best = { path: file.path, rank, deliverable };
+    }
+  }
+  return best?.path ?? null;
+}
+
+/**
+ * 右侧预览跟着对话走。
+ * 停在底部时用最近一轮有预览的产物；往上翻时只用当前看着的那条助手消息。
+ */
+export function followedPreviewPath(
+  ordered: readonly { id: string; files?: readonly TurnFile[] }[],
+  options: { atBottom: boolean; focusedId: string | null },
+): { messageId: string; path: string } | null {
+  const pick = (entry: { id: string; files?: readonly TurnFile[] } | undefined) => {
+    if (!entry) return null;
+    const path = previewPathForTurn(entry.files);
+    return path ? { messageId: entry.id, path } : null;
+  };
+  if (options.atBottom) {
+    for (let index = ordered.length - 1; index >= 0; index -= 1) {
+      const found = pick(ordered[index]);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (!options.focusedId) return null;
+  return pick(ordered.find((entry) => entry.id === options.focusedId));
+}