Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* MessageNavRail
* ---------------------------------------------------------------------------
* 聊天区左缘的"提问导航条":每条用户提问一根短刻度,当前正在阅读的提问加深,
* hover 显示"提问 + 回答摘要"预览卡,点击跳转到那一轮的顶部。
*
* 职责定义(设计推导起点):长 agent 对话的意义单元是"轮次"(提问→回答),
* 导航条同时承担 ①定位(当前项)②跳转(落点框住整轮)③识别(预览卡)。
*
* 显隐(活跃深、空闲浅,不完全隐没):
* - 前提条件:真实提问 ≥ NAV_RAIL_MIN_ENTRIES 且内容列左侧留白足够
* (窄窗口 / 嵌入面板自然隐藏,绝不压在气泡上);
* - 满足前提后**常驻但分两档**:滚动、鼠标滑到左缘、悬停刻度时全亮;
* 静止阅读 NAV_RAIL_IDLE_HIDE_MS 后**减淡**为浅灰(2026-07-28 验收
* 定稿:完全淡出会让人忘记它的存在,减淡保留"地图在这"的心理暗示,
* 阅读态噪音仍然很低)。
*
* 入口去重:导航条**完整覆盖导航**(出场且未截断)时,父级抑制右上角
* "跳到上一条提问"chip —— 同一个导航任务只保留一套入口(经
* onNavCoverageChange 上报)。刻度被截断的超长会话里 chip 回归,截断区
* 仍有导航可用(PR #830 review)。
*
* 几何职责分工:
* - 本组件只做 DOM 测量(scroll + ResizeObserver,rAF 节流,与
* usePrevUserMessageInView 同款套路)并渲染;
* - 判定与规划是纯函数,在 messageNavRailModel.ts,node 环境直接单测;
* - 点击后的跳转(含渲染窗口外目标的扩窗、落点计算)由 MessageStream 的
* onJump 承接,那边持有 firstVisibleItemKey / chip-jump 抑制协议等状态。
*
* pending 态:点击后目标立即显示为当前项(乐观),平滑滚动落定(几何判定
* 追上)或用户产生主动滚动意图(wheel / touch / 方向键)时回归几何真值;
* 3s 安全兜底防"点完不动"卡住乐观态,与 CHIP_JUMP_SAFETY_MS 同源经验值。
*/
import {
useCallback,
useEffect,
useRef,
useState,
type PointerEvent as ReactPointerEvent,
type WheelEvent as ReactWheelEvent,
} from 'react';
import { useTranslation } from 'react-i18next';
import { cn } from '@/lib/utils';
import { Tooltip } from '@/components/ui/tooltip';
import { useNavigationKeyListener } from './useNavigationKeyListener';
import {
NAV_RAIL_ACTIVE_FUDGE_PX,
NAV_RAIL_MIN_AVAIL_HEIGHT_PX,
NAV_RAIL_MIN_ENTRIES,
NAV_RAIL_RANGE_BOTTOM_EDGE_PX,
hasNavRailRoom,
pickActiveNavId,
pickVisibleNavRange,
planNavRailTicks,
planNavRailTickWidth,
planNavRailTickProgress,
type NavRailEntry,
} from './messageNavRailModel';
import { forwardNavRailWheel } from './messageNavRailWheel';
// 乐观 pending 态的安全兜底时长,对齐 MessageStream 的 CHIP_JUMP_SAFETY_MS。
const PENDING_SAFETY_MS = 3000;
// 静止这么久后减淡(不隐没) — 节奏对齐全局滚动条自动隐藏
// (lib/scrollbarAutoHide.ts 的 .is-scrolling,2s)。
const NAV_RAIL_IDLE_HIDE_MS = 2000;
// 空闲档的整条不透明度。全亮 100% / 空闲减淡到这个值,保留"地图在这"的
// 存在感又不抢阅读注意力(2026-07-28 实机验收定的档位)。
const NAV_RAIL_IDLE_OPACITY_CLASS = 'opacity-40';
// 鼠标滑进滚动容器左缘这么宽的区域时唤醒导航条(mousemove 探测,不放
// pointer-events 层,避免挡住从留白处起手的划选)。
const WAKE_GUTTER_PX = 48;
// 刻度带的上下保留:顶部对齐内容区 pt-7;底部在输入 overlay 之上再让 16px。
const RAIL_TOP_PX = 28;
const RAIL_BOTTOM_EXTRA_PX = 16;
export interface MessageNavRailProps {
/** 已加载的全部真实提问(deriveNavRailEntries 产物,时间正序)。 */
entries: NavRailEntry[];
/** MessageStream 的滚动容器 ref,测量与锚点查询都以它为根。 */
scrollRef: { readonly current: HTMLDivElement | null };
/** 内容列 maxWidth(与 MessageStream contentRef 的 maxWidth 同值)。 */
contentMaxWidth: number;
/** ResizeObserver 测量时读取最新宽度,避免把连续像素变化回灌给 React。 */
getContentMaxWidth?: () => number;
/** 底部输入 overlay 高度(resolvedBottomPadding),刻度带避开这段。 */
bottomOffset: number;
/** 点击刻度 → 跳到该提问。目标可能在渲染窗口外,由父级扩窗后滚动。 */
onJump: (clientId: string) => void;
/**
* "导航条完整覆盖导航"变化上报(出场资格 && 刻度未截断)。父级用它做
* 入口去重:覆盖时抑制"跳到上一条提问"chip;导航条缺席或截断了更早
* 刻度时 chip 回归。与淡入淡出无关 —— chip 只在滚动时出现,而滚动一定
* 会唤醒导航条,按覆盖态抑制即可,信号稳定不闪烁。
*/
onNavCoverageChange?: (covers: boolean) => void;
/** 切会话重置几何与 pending 态(与 usePrevUserMessageInView 同款)。 */
resetKey?: string;
}
export function MessageNavRail({
entries,
scrollRef,
contentMaxWidth,
getContentMaxWidth,
bottomOffset,
onJump,
onNavCoverageChange,
resetKey,
}: MessageNavRailProps) {
const { t } = useTranslation();
const [activeId, setActiveId] = useState<string | null>(null);
// 视口内可见轮次的范围(整段提亮,与"当前项加长"互补)。存 id 而非下标:
// 测量与渲染之间 entries 可能已更新,按 id 回查最稳。
const [visibleRange, setVisibleRange] = useState<{ startId: string; endId: string } | null>(null);
const [pendingId, setPendingId] = useState<string | null>(null);
const [hoveredId, setHoveredId] = useState<string | null>(null);
const [scrubId, setScrubId] = useState<string | null>(null);
const [hasRoom, setHasRoom] = useState(false);
const [availHeight, setAvailHeight] = useState(0);
// 淡入淡出:挂载即亮(给切进会话的用户一个初始定位),此后随活动唤醒。
const [awake, setAwake] = useState(true);
const rafRef = useRef<number | null>(null);
const pendingTimerRef = useRef<number | null>(null);
const idleTimerRef = useRef<number | null>(null);
const hoveringRef = useRef(false);
const railRef = useRef<HTMLElement | null>(null);
const scrubRef = useRef<{
pointerId: number;
startY: number;
moved: boolean;
lastJumpedIndex: number | null;
button: HTMLButtonElement;
} | null>(null);
const suppressClickRef = useRef(false);
// 容器左缘缓存,给高频 mousemove 的左缘唤醒判定用,免得每次事件都
// getBoundingClientRect 强制布局读;measure(scroll/resize 都会触发)时刷新。
const containerLeftRef = useRef(0);
// 测量回调经 rAF 异步触发,entries 派生的 id 列表 / 布局参数用 ref 透传
// 拿最新值,避免把大数组挂进依赖链让监听器反复重挂。id 列表按 entries
// 引用缓存,长会话滚动的高频测量不逐帧重新分配数组(Copilot review);
// 初值空占位,首次渲染即被下面的引用比较填充,不在每次 render 白算一遍。
const measureIdsRef = useRef<{ source: readonly NavRailEntry[] | null; ids: string[] }>({
source: null,
ids: [],
});
if (measureIdsRef.current.source !== entries) {
measureIdsRef.current = { source: entries, ids: entries.map((e) => e.id) };
}
const contentMaxWidthRef = useRef(contentMaxWidth);
contentMaxWidthRef.current = contentMaxWidth;
const getContentMaxWidthRef = useRef(getContentMaxWidth);
getContentMaxWidthRef.current = getContentMaxWidth;
const bottomOffsetRef = useRef(bottomOffset);
bottomOffsetRef.current = bottomOffset;
// 切会话全部归零,防旧目标 / 旧乐观态残留;重新亮一次做初始定位。
useEffect(() => {
setActiveId(null);
setVisibleRange(null);
setPendingId(null);
setHoveredId(null);
setScrubId(null);
scrubRef.current = null;
setAwake(true);
}, [resetKey]);
// 唤醒 + 重排空闲淡出计时。悬停刻度期间不淡出(计时器到点重排)。
const wake = useCallback(() => {
setAwake((cur) => (cur ? cur : true));
if (idleTimerRef.current !== null) {
window.clearTimeout(idleTimerRef.current);
}
const scheduleHide = () => {
idleTimerRef.current = window.setTimeout(() => {
idleTimerRef.current = null;
if (hoveringRef.current) {
scheduleHide();
return;
}
setAwake(false);
}, NAV_RAIL_IDLE_HIDE_MS);
};
scheduleHide();
}, []);
const measure = useCallback(() => {
rafRef.current = null;
const root = scrollRef.current;
if (!root) return;
const containerRect = root.getBoundingClientRect();
containerLeftRef.current = containerRect.left;
const liveContentMaxWidth = getContentMaxWidthRef.current?.() || contentMaxWidthRef.current;
const roomOk = hasNavRailRoom(containerRect.width, liveContentMaxWidth);
setHasRoom(roomOk);
const avail = Math.max(
0,
containerRect.height - bottomOffsetRef.current - RAIL_TOP_PX - RAIL_BOTTOM_EXTRA_PX,
);
setAvailHeight(avail);
const ids = measureIdsRef.current.ids;
// 组件常驻挂载,不出场(条数不足 / 窄窗 / 矮视口)时跳过逐条锚点测量,
// 短对话滚动不背 querySelector + 布局读的开销;room/avail 已更新,条件
// 翻转时下一次测量自然恢复(Copilot review)。
if (ids.length < NAV_RAIL_MIN_ENTRIES || !roomOk || avail < NAV_RAIL_MIN_AVAIL_HEIGHT_PX) {
setActiveId((cur) => (cur === null ? cur : null));
setVisibleRange((cur) => (cur === null ? cur : null));
return;
}
// 同一帧内 topAt 会被 active / range 两个判定反复调,缓存 DOM 测量。
const topCache = new Map<number, number | null>();
const topAt = (i: number): number | null => {
const cached = topCache.get(i);
if (cached !== undefined) return cached;
const el = root.querySelector(
`[data-message-client-id="${CSS.escape(ids[i])}"]`,
) as HTMLElement | null;
const top = el ? el.getBoundingClientRect().top : null;
topCache.set(i, top);
return top;
};
const next = pickActiveNavId(ids, containerRect.top + NAV_RAIL_ACTIVE_FUDGE_PX, topAt);
setActiveId((cur) => (cur === next ? cur : next));
// 有效视口 = 扣除容差后的边界:顶部与当前项共用同一条阈值线(空白余量
// 不算"看见了上一轮"),底部留 8px 防露头即亮。语义见 pickVisibleNavRange。
const range = pickVisibleNavRange(
ids,
containerRect.top + NAV_RAIL_ACTIVE_FUDGE_PX,
containerRect.bottom - NAV_RAIL_RANGE_BOTTOM_EDGE_PX,
topAt,
);
const nextRange = range ? { startId: ids[range.startIndex], endId: ids[range.endIndex] } : null;
setVisibleRange((cur) =>
cur?.startId === nextRange?.startId && cur?.endId === nextRange?.endId ? cur : nextRange,
);
}, [scrollRef]);
const scheduleMeasure = useCallback(() => {
if (rafRef.current === null) {
rafRef.current = requestAnimationFrame(measure);
}
}, [measure]);
// 主动滚动意图(wheel / touch / 方向键)→ 放弃乐观 pending,回归几何真值。
const dropPending = useCallback(() => {
setPendingId((cur) => (cur === null ? cur : null));
}, []);
useEffect(() => {
const root = scrollRef.current;
if (!root) return;
const onScroll = () => {
wake();
scheduleMeasure();
};
// 左缘唤醒走 mousemove 探测而不是铺一层 pointer-events 热区:
// 留白区常被用来起手划选文本,热区会吃掉 mousedown。左缘坐标用
// measure 缓存的值(窗口纯平移导致的极小误差可接受),不在高频事件里
// 强制布局读。
const onMouseMove = (e: MouseEvent) => {
if (e.clientX - containerLeftRef.current <= WAKE_GUTTER_PX) {
wake();
}
};
root.addEventListener('scroll', onScroll, { passive: true });
root.addEventListener('mousemove', onMouseMove, { passive: true });
root.addEventListener('wheel', dropPending, { passive: true });
root.addEventListener('touchstart', dropPending, { passive: true });
const ro = new ResizeObserver(() => scheduleMeasure());
ro.observe(root);
// 初次同步:挂载后未滚动也能算出当前项与可用空间。
scheduleMeasure();
return () => {
root.removeEventListener('scroll', onScroll);
root.removeEventListener('mousemove', onMouseMove);
root.removeEventListener('wheel', dropPending);
root.removeEventListener('touchstart', dropPending);
ro.disconnect();
if (rafRef.current !== null) {
cancelAnimationFrame(rafRef.current);
rafRef.current = null;
}
};
}, [scrollRef, scheduleMeasure, dropPending, wake]);
useNavigationKeyListener(dropPending);
// 条目变化(新发消息 / load-more prepend)与喂进测量的布局 props 变化都要
// 重算。bottomOffset / contentMaxWidth 只经 ref 透传给 measure,不列进这里
// 的话 composer 撑高(多行输入 / 加附件)既不触发容器 resize 也不滚动,
// availHeight 与纵向出场门槛会停在旧值直到下次滚动(PR #830 review)。
useEffect(() => {
scheduleMeasure();
}, [entries, bottomOffset, contentMaxWidth, getContentMaxWidth, scheduleMeasure]);
// 挂载亮相的那次也要按空闲节奏淡出。
useEffect(() => {
wake();
}, [wake, resetKey]);
// 平滑滚动落定,几何判定追上乐观目标 → 乐观态使命完成,交还给几何。
useEffect(() => {
if (pendingId !== null && pendingId === activeId) {
setPendingId(null);
}
}, [pendingId, activeId]);
// 出场资格:条数、横向留白、纵向空间三道门槛。纵向门槛防极矮视口 /
// 输入 overlay 占满高度时刻度溢出压到输入区(PR #830 review)。
const eligible =
entries.length >= NAV_RAIL_MIN_ENTRIES &&
hasRoom &&
availHeight >= NAV_RAIL_MIN_AVAIL_HEIGHT_PX;
const plan = planNavRailTicks(entries.length, availHeight);
// 覆盖态上报(入口去重用);卸载时收回。截断时不算覆盖 —— 被截掉的
// 早期区域没有刻度,chip 必须回归兜底。
const railCoversNav = eligible && plan.hiddenCount === 0;
useEffect(() => {
onNavCoverageChange?.(railCoversNav);
}, [railCoversNav, onNavCoverageChange]);
useEffect(() => {
return () => {
onNavCoverageChange?.(false);
};
}, [onNavCoverageChange]);
useEffect(() => {
return () => {
if (pendingTimerRef.current !== null) {
window.clearTimeout(pendingTimerRef.current);
}
if (idleTimerRef.current !== null) {
window.clearTimeout(idleTimerRef.current);
}
};
}, []);
const handleTickClick = useCallback(
(clientId: string) => {
if (suppressClickRef.current) {
suppressClickRef.current = false;
return;
}
setPendingId(clientId);
if (pendingTimerRef.current !== null) {
window.clearTimeout(pendingTimerRef.current);
}
pendingTimerRef.current = window.setTimeout(() => {
pendingTimerRef.current = null;
setPendingId(null);
}, PENDING_SAFETY_MS);
onJump(clientId);
},
[onJump],
);
const findScrubIndex = useCallback((clientY: number): number | null => {
const rail = railRef.current;
if (!rail) return null;
let nearest: { index: number; distance: number } | null = null;
for (const button of rail.querySelectorAll<HTMLButtonElement>('[data-message-nav-index]')) {
const index = Number(button.dataset.messageNavIndex);
if (!Number.isInteger(index)) continue;
const rect = button.getBoundingClientRect();
const distance = Math.abs(clientY - (rect.top + rect.height / 2));
if (nearest === null || distance < nearest.distance) nearest = { index, distance };
}
return nearest?.index ?? null;
}, []);
const jumpToScrubIndex = useCallback(
(index: number) => {
const entry = entries[index];
if (!entry) return;
setScrubId(entry.id);
const scrub = scrubRef.current;
if (scrub?.lastJumpedIndex === index) return;
if (scrub) scrub.lastJumpedIndex = index;
setPendingId(entry.id);
if (pendingTimerRef.current !== null) window.clearTimeout(pendingTimerRef.current);
pendingTimerRef.current = window.setTimeout(() => {
pendingTimerRef.current = null;
setPendingId(null);
}, PENDING_SAFETY_MS);
onJump(entry.id);
},
[entries, onJump],
);
const handleTickPointerDown = useCallback(
(index: number, event: ReactPointerEvent<HTMLButtonElement>) => {
if (event.button !== 0) return;
event.preventDefault();
suppressClickRef.current = false;
const button = event.currentTarget;
scrubRef.current = {
pointerId: event.pointerId,
startY: event.clientY,
moved: false,
lastJumpedIndex: null,
button,
};
setScrubId(entries[index]?.id ?? null);
wake();
button.setPointerCapture?.(event.pointerId);
},
[entries, wake],
);
const handleTickPointerMove = useCallback(
(event: ReactPointerEvent<HTMLButtonElement>) => {
const scrub = scrubRef.current;
if (!scrub || scrub.pointerId !== event.pointerId) return;
if (!scrub.moved && Math.abs(event.clientY - scrub.startY) < 3) return;
scrub.moved = true;
const index = findScrubIndex(event.clientY);
if (index !== null) jumpToScrubIndex(index);
},
[findScrubIndex, jumpToScrubIndex],
);
const finishScrub = useCallback(
(event: ReactPointerEvent<HTMLButtonElement>, suppressFollowUpClick: boolean) => {
const scrub = scrubRef.current;
if (!scrub || scrub.pointerId !== event.pointerId) return;
if (scrub.button.hasPointerCapture?.(event.pointerId)) {
scrub.button.releasePointerCapture?.(event.pointerId);
}
suppressClickRef.current = suppressFollowUpClick && scrub.moved;
scrubRef.current = null;
setScrubId(null);
},
[],
);
const handleTickMouseEnter = useCallback(() => {
hoveringRef.current = true;
wake();
}, [wake]);
const handleTickMouseLeave = useCallback(() => {
hoveringRef.current = false;
}, []);
// 悬停刻度带时滚轮不能失灵:导航条是滚动容器的兄弟 overlay,刻度按钮
// pointer-events-auto 会成为 wheel 目标、冒泡不经过滚动容器,浏览器不会
// 替我们滚聊天区(PR #830 review)。补两件事,缺一不可:
// 1. 先把 wheel **重派**给滚动容器 —— root 上挂着既有的 wheel 意图监听
// (本组件的 dropPending;MessageStream 的贴底跟随解锚 / 顶部意图
// 补页 / chip 抑制解除)。只补位移不补意图,贴底流式时在刻度带上滚
// 会被 pin-to-bottom 拽回、到顶后拉不出更早历史(对抗审查 P1)。
// 合成事件 untrusted、不产生默认滚动,与下一步不会双滚;先意图后
// 位移,对齐原生"监听先于默认滚动"的时序。
// 2. 再把增量转发成真实位移(见 messageNavRailWheel.ts)。产生的
// scroll 事件经 root 的 onScroll 走 wake + scheduleMeasure。
const handleRailWheel = useCallback(
(e: ReactWheelEvent<HTMLElement>) => {
const root = scrollRef.current;
if (!root) return;
root.dispatchEvent(new WheelEvent('wheel', { deltaX: e.deltaX, deltaY: e.deltaY }));
forwardNavRailWheel(root, e);
},
[scrollRef],
);
if (!eligible) return null;
const shown = entries.slice(plan.startIndex);
const displayActiveId = pendingId ?? activeId;
// 可见范围 id → 下标(渲染时按 id 回查,测量与渲染间 entries 变更也不会
// 错位)。单次遍历同时定位两端,滚动高频重渲下不扫两遍数组。
let rangeStartIdx = -1;
let rangeEndIdx = -1;
if (visibleRange) {
for (let i = 0; i < entries.length; i++) {
if (entries[i].id === visibleRange.startId) rangeStartIdx = i;
if (entries[i].id === visibleRange.endId) {
rangeEndIdx = i;
if (rangeStartIdx >= 0) break;
}
}
}
// 空闲档只是减淡、仍然可见可点,指针事件常开(悬停刻度本身就会唤醒全亮)。
const tickEvents = 'pointer-events-auto';
return (
<nav
ref={railRef}
aria-label={t('chat.messageNavRail.aria')}
// 容器不吃事件,只有刻度自身 pointer-events-auto(空闲减淡时也可点,
// 见 tickEvents 注释),不挡左缘留白里的文字选择;justify-center 让
// 刻度组在(避开输入 overlay 的)带内垂直居中。
className={cn(
'pointer-events-none absolute inset-y-0 left-2 z-30 flex w-6 flex-col items-stretch justify-center',
// §14.4 禁硬编码 duration / cubic-bezier。不透明度变化属 fast 档
// (150ms);原先是 Tailwind 的 duration-200 + ease-out。
'transition-opacity duration-[var(--motion-fast)] ease-[var(--motion-ease-out)]',
awake ? 'opacity-100' : NAV_RAIL_IDLE_OPACITY_CLASS,
)}
style={{ paddingTop: RAIL_TOP_PX, paddingBottom: bottomOffset + RAIL_BOTTOM_EXTRA_PX }}
// wheel 事件从 pointer-events-auto 的刻度冒泡到这里统一转发,
// "更早还有 N 条"占位刻度一并覆盖。
onWheel={handleRailWheel}
>
{/*
* 整条导轨共用一个 Provider。原先每根刻度包一层 <Tip>,而 Tip 内部是
* 无条件自带 <TooltipProvider> 的 —— 而 skipDelayDuration 是 **Provider
* 级**状态,跨刻度就是跨 Provider,新 Provider 没有"刚刚开过"的记忆,于是
* 每根都重新等满 delay。刻度纵距只有 9px,鼠标竖着划过去是连续闪断。
* 换成 primitives 挂在一个 Provider 下:首次 hover 等 150ms,之后 700ms 内
* 切到相邻刻度立即显示,竖向移动时预览卡只换内容、不中断。
* (在 <Tip> 外面套一层 Provider 没用 —— 内层会把外层遮住。)
*/}
<Tooltip.Provider delayDuration={150} skipDelayDuration={700}>
{plan.hiddenCount > 0 ? (
<Tooltip.Root>
<Tooltip.Trigger asChild>
<div
className={cn('flex items-center justify-center', tickEvents)}
style={{ height: plan.pitchPx }}
onMouseEnter={handleTickMouseEnter}
onMouseLeave={handleTickMouseLeave}
>
<span
aria-hidden="true"
className="text-10 leading-none text-[var(--text-tertiary)]"
>
⋯
</span>
</div>
</Tooltip.Trigger>
{/* 占位刻度是**标签**,继续用默认 tooltip 面色(近黑),与下面的
内容预览卡两类不混 —— 面色决策同 #830 原状。 */}
<Tooltip.Content side="right">
{t('chat.messageNavRail.hiddenEarlier', { count: plan.hiddenCount })}
</Tooltip.Content>
</Tooltip.Root>
) : null}
{shown.map((entry, i) => {
// 纯附件且无文件名的提问用 i18n 计数文案兜底(模型层不碰 i18n)。
const preview =
entry.preview ||
(entry.attachmentsOnly
? t('chat.messageNavRail.attachmentOnly', { count: entry.attachmentsOnly })
: '');
const isActive = entry.id === displayActiveId;
const fullIdx = plan.startIndex + i;
const interactionId = scrubId ?? hoveredId;
const interactionIndex =
interactionId == null ? -1 : entries.findIndex((item) => item.id === interactionId);
const interactionDistance =
interactionIndex < 0 ? null : Math.abs(fullIdx - interactionIndex);
// 该轮次的内容当前正显示在视口里 → 提亮"屏上内容高亮";
// 当前项在提亮之上再加长,两个信号分工:范围 = 在看什么,长刻度 = 读到哪。
const inView = rangeStartIdx >= 0 && fullIdx >= rangeStartIdx && fullIdx <= rangeEndIdx;
// 自动化提问是系统注入的重复性消息,用更短的刻度保留其导航入口,
// 同时让手动提问成为更容易扫到的主节奏。当前项仍比普通自动刻度更长,
// 保持点击跳转后的定位反馈。
const tickWidthClass = planNavRailTickWidth({
distance: interactionDistance,
isActive,
inView,
isAutomation: entry.isAutomation,
});
const tickOpacityClass =
interactionDistance === 0
? 'opacity-100'
: interactionDistance !== null
? 'opacity-[0.65]'
: isActive
? 'opacity-90'
: 'opacity-[0.65]';
const markerProgress = planNavRailTickProgress(interactionDistance);
return (
<Tooltip.Root key={entry.id}>
<Tooltip.Trigger asChild>
<button
type="button"
aria-label={t('chat.messageNavRail.jumpAria', {
index: plan.startIndex + i + 1,
preview,
})}
aria-current={isActive ? 'true' : undefined}
data-message-nav-automation={entry.isAutomation ? 'true' : undefined}
data-message-nav-index={fullIdx}
onClick={() => handleTickClick(entry.id)}
onMouseLeave={() => {
handleTickMouseLeave();
setHoveredId((current) => (current === entry.id ? null : current));
}}
onPointerEnter={() => {
setHoveredId(entry.id);
handleTickMouseEnter();
}}
onPointerDown={(event) => handleTickPointerDown(fullIdx, event)}
onPointerMove={handleTickPointerMove}
onPointerUp={(event) => finishScrub(event, true)}
onPointerCancel={(event) => finishScrub(event, false)}
onLostPointerCapture={(event) => finishScrub(event, false)}
onMouseEnter={() => {
setHoveredId(entry.id);
handleTickMouseEnter();
}}
// 命中区吃满整格纵距,刻度线本体只有 2px 高。焦点环用全局
// --focus-ring token(AgentTaskCard 同款),键盘 Tab 可见
// (PR #830 review:纯 outline-none 会让键盘用户丢焦点)。
className={cn(
'group flex w-full items-center rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring)]',
tickEvents,
)}
style={{ height: plan.pitchPx }}
>
<span
className={cn(
// §14.4 禁硬编码 duration / cubic-bezier:base 档
// (200ms)与原先的 duration-200 同值,曲线取尺寸插值的
// ease-move。过渡属性从 all 收窄到实际会变的两项。
'h-[2px] w-[26px] origin-left rounded-full',
'transition-[transform,background-color] duration-[var(--motion-base)]',
'ease-[var(--motion-ease-move)]',
tickWidthClass,
tickOpacityClass,
interactionDistance === 0 ||
(interactionDistance === null && (isActive || inView))
? 'bg-[var(--text-primary)]'
: 'bg-[var(--text-secondary)] group-hover:bg-[var(--text-primary)]',
)}
style={{
transform: `scaleX(${0.2308 + 0.7692 * markerProgress})`,
}}
/>
</button>
</Tooltip.Trigger>
{/*
* 预览卡 = 提问(加粗一行)+ 回答摘要(灰字,至多 3 行)。
* 摘要是识别的主载体:大量提问是"继续 / 重来"式短指令,只靠
* 提问认不出是哪一轮。回答未产生时只显示提问行。
*
* 面色刻意不用全局 tooltip token(亮暗两模式都是近黑,那是给
* "一句话标签"定的惯例):本卡是**内容预览**,语义对应 popover
* 内容面 —— 白底深字 / 暗色深面,多行正文可读性优先。旁边的
* "更早还有 N 条"是标签,继续用默认 tooltip 面色,两类不混。
* 覆盖类刻意与 TooltipContent 的原类同形式(任意值 bg-[...] /
* text-[...]),确保 tailwind-merge 归入同一冲突组、后写的必胜,
* 不赌歧义值的分组启发式。
* 阴影不覆盖:继承 TooltipContent 基座的浮层阴影决策,本卡不引入
* 新的深度样式(PR #830 review)。
*
* 无预览文本时不渲染 Content —— 与原先 <Tip text={null}> 的
* 透明传递等价(空内容不该冒出一个空卡)。
*/}
{preview ? (
<Tooltip.Content
side="right"
className={cn(
'max-w-[380px] break-normal px-3 py-2',
'border-[var(--border-default)] bg-[hsl(var(--popover))] text-[hsl(var(--popover-foreground))]',
'dark:border-[var(--border-default)]',
)}
>
<span className="flex max-w-[344px] flex-col gap-1">
<span className="truncate text-13 font-medium">{preview}</span>
{entry.answerExcerpt ? (
// 摘要 = 三级文字档。原为「主文字色 × 50% 透明度」(多轮实机验收后
// 用户直接指定,2026-07-28);2026-10-22 起文字是墨水阶梯,三级档
// (浅 44% / 深 40%)与正文 88% × 50% 等值,改用档位 token,不再
// 在文字色上叠透明度。调整仍须实机看效果。
<span className="line-clamp-3 whitespace-normal break-normal text-13 leading-relaxed text-[var(--text-tertiary)]">
{entry.answerExcerpt}
</span>
) : null}
</span>
</Tooltip.Content>
) : null}
</Tooltip.Root>
);
})}
</Tooltip.Provider>
</nav>
);
}