@rexvane/piweb 0.3.20 → 0.3.22

package/src/components/GitPanel.tsx

@@ -39,10 +39,19 @@ interface GitInfo {
 	statusError?: string;
 }
 
+interface GithubIdentity {
+	login: string;
+	name?: string;
+	avatar?: string;
+	url?: string;
+	repo?: string;
+}
+
 interface DiffResult {
 	patch: string;
 	truncated: boolean;
 	binary: boolean;
+	stats?: { add: number; del: number };
 	title?: string;
 }
 
@@ -75,6 +84,7 @@ export function GitPanel({
 }) {
 	const { t } = useI18n();
 	const [info, setInfo] = useState<GitInfo | null>(null);
+	const [identity, setIdentity] = useState<GithubIdentity | null>(null);
 	const [loading, setLoading] = useState(false);
 	const [statusError, setStatusError] = useState("");
 	const [diffError, setDiffError] = useState("");
@@ -105,6 +115,23 @@ export function GitPanel({
 		}
 	}, [cwd]);
 
+	// GitHub 身份单独拉：要走网络（gh / 头像），不能拖慢上面那条纯本地的状态读取
+	useEffect(() => {
+		setIdentity(null);
+		if (!cwd) return;
+		const controller = new AbortController();
+		void (async () => {
+			try {
+				const r = await fetch(`/api/github?cwd=${encodeURIComponent(cwd)}`, { signal: controller.signal });
+				const j = await r.json();
+				if (j?.success && j.data?.identity) setIdentity(j.data.identity as GithubIdentity);
+			} catch {
+				/* 取不到就只显示分支，不报错 */
+			}
+		})();
+		return () => controller.abort();
+	}, [cwd, refreshKey]);
+
 	useEffect(() => {
 		setInfo(null);
 		setView(null);
@@ -165,13 +192,31 @@ export function GitPanel({
 	const error = view ? diffError : statusError || info?.statusError || "";
 
 	const parsed = useMemo(() => (diff?.patch ? parseUnifiedDiff(diff.patch) : null), [diff]);
-	const stats = parsed ? diffStats(parsed) : null;
+	// 新服务端给完整 Git 统计；旧服务端只在 patch 完整时才允许本地计数。
+	const stats = diff?.binary ? null : diff?.stats ?? (parsed && !diff?.truncated ? diffStats(parsed) : null);
 
 	const conflicts = info?.files.filter((f) => f.kind === "conflict") ?? [];
 	const staged = info?.files.filter((f) => f.kind !== "conflict" && f.kind !== "untracked" && f.indexStatus !== " ") ?? [];
 	const unstaged = info?.files.filter((f) => f.kind !== "conflict" && f.kind !== "untracked" && f.workStatus !== " ") ?? [];
 	const untracked = info?.files.filter((f) => f.kind === "untracked") ?? [];
 
+	/**
+	 * 按 Git 的三个区呈现（分支 / 上游那些是「版本库」侧，在别的行）：
+	 * - 暂存区：`git add` 过的，下次 commit 会带上；
+	 * - 工作区：改了还没 add 的 + 未跟踪的新文件（都属于「还没进暂存区」）；
+	 * - 冲突单独置顶（不先解决，提交走不下去）。
+	 * 未跟踪文件要整份当新增行看，模式逐文件给，不能按组统一。
+	 */
+	const areas: Array<{ key: string; label: string; entries: Array<{ file: GitFileEntry; mode: "staged" | "worktree" | "untracked" }>; danger?: boolean }> = [
+		{ key: "conflict", label: t.gitConflict, entries: conflicts.map((file) => ({ file, mode: "worktree" as const })), danger: true },
+		{ key: "staged", label: t.gitStagingArea, entries: staged.map((file) => ({ file, mode: "staged" as const })) },
+		{
+			key: "worktree",
+			label: t.gitWorkingTree,
+			entries: [...unstaged.map((file) => ({ file, mode: "worktree" as const })), ...untracked.map((file) => ({ file, mode: "untracked" as const }))],
+		},
+	].filter((area) => area.entries.length > 0);
+
 	const openFile = (f: GitFileEntry, mode: "staged" | "worktree" | "untracked", label: string) => changeView({ kind: "file", path: f.path, mode, label });
 
 	const headerTitle = view
@@ -247,6 +292,39 @@ export function GitPanel({
 				)}
 				{!view && info?.isRepo && (
 					<div className="flex flex-col gap-4">
+						{/* GitHub 身份：头像 + 账号（取不到就整行不出现） */}
+						{identity && (
+							<div className="flex items-center gap-2">
+								{identity.avatar ? (
+									// eslint-disable-next-line @next/next/no-img-element
+									<img src={identity.avatar} alt="" width={22} height={22} className="flex-none rounded-full" />
+								) : (
+									<span
+										className="grid flex-none place-items-center rounded-full"
+										style={{ width: 22, height: 22, background: "var(--dsw-selector)", fontSize: 11, fontWeight: 600, color: "var(--dsw-label-secondary)" }}
+										aria-hidden
+									>
+										{identity.login.slice(0, 1).toUpperCase()}
+									</span>
+								)}
+								<a
+									href={identity.url ?? `https://github.com/${identity.login}`}
+									target="_blank"
+									rel="noreferrer"
+									className="min-w-0 truncate"
+									style={{ fontSize: 12.5, color: "var(--dsw-label-secondary)", textDecoration: "none" }}
+									title={identity.name ? `${identity.name} (@${identity.login})` : `@${identity.login}`}
+								>
+									@{identity.login}
+								</a>
+								{identity.repo && (
+									<span className="min-w-0 truncate" style={{ fontSize: 11.5, color: "var(--dsw-label-caption)" }} title={identity.repo}>
+										· {identity.repo}
+									</span>
+								)}
+							</div>
+						)}
+
 						{/* 分支行 */}
 						<div className="flex flex-wrap items-center gap-2" style={{ fontSize: 12.5 }}>
 							<span
@@ -280,45 +358,37 @@ export function GitPanel({
 						{error ? null : info.files.length === 0 ? (
 							<div style={{ fontSize: 12.5, color: "var(--dsw-label-caption)" }}>{t.gitNoChanges}</div>
 						) : (
-							[
-								{ label: t.gitConflict, list: conflicts, mode: "worktree" as const },
-								{ label: t.gitStaged, list: staged, mode: "staged" as const },
-								{ label: t.gitUnstaged, list: unstaged, mode: "worktree" as const },
-								{ label: t.gitUntracked, list: untracked, mode: "untracked" as const },
-							].map(
-								(group) =>
-									group.list.length > 0 && (
-										<div key={group.label}>
-											<div className="mb-1 flex items-center gap-2" style={{ fontSize: 11.5, color: group.mode === "worktree" && group.label === t.gitConflict ? "var(--dsw-danger)" : "var(--dsw-label-caption)" }}>
-												<span style={{ fontWeight: 600 }}>{group.label}</span>
-												<span>{group.list.length}</span>
-											</div>
-											<div className="flex flex-col">
-												{group.list.map((f) => (
-													<button
-														key={`${group.label}:${f.path}`}
-														type="button"
-														className="flex w-full items-center gap-2 rounded-lg px-2 py-1 text-left transition-colors"
-														title={f.path}
-														onMouseEnter={(e) => (e.currentTarget.style.background = "var(--dsw-hover)")}
-														onMouseLeave={(e) => (e.currentTarget.style.background = "transparent")}
-														onClick={() => openFile(f, group.mode, group.mode === "staged" ? t.gitStagedDiff : group.mode === "untracked" ? t.gitUntracked : t.gitWorktreeDiff)}
-													>
-														<span
-															className="flex-none rounded px-1 text-center"
-															style={{ minWidth: 16, fontSize: 10.5, fontFamily: "var(--font-mono)", fontWeight: 600, color: KIND_COLOR[f.kind], background: "var(--dsw-hover)" }}
-														>
-															{f.kind === "untracked" ? "?" : f.kind === "conflict" ? "!" : group.mode === "staged" ? f.indexStatus : f.workStatus !== " " ? f.workStatus : f.indexStatus}
-														</span>
-														<span className="min-w-0 flex-1 truncate" style={{ fontSize: 12, fontFamily: "var(--font-mono)", color: "var(--dsw-label-secondary)" }}>
-															{f.path}
-														</span>
-													</button>
-												))}
-											</div>
-										</div>
-									),
-							)
+							areas.map((area) => (
+								<div key={area.key}>
+									<div className="mb-1 flex items-center gap-2" style={{ fontSize: 11.5, color: area.danger ? "var(--dsw-danger)" : "var(--dsw-label-caption)" }}>
+										<span style={{ fontWeight: 600 }}>{area.label}</span>
+										<span>{area.entries.length}</span>
+									</div>
+									<div className="flex flex-col">
+										{area.entries.map(({ file: f, mode }) => (
+											<button
+												key={`${area.key}:${f.path}`}
+												type="button"
+												className="flex w-full items-center gap-2 rounded-lg px-2 py-1 text-left transition-colors"
+												title={f.path}
+												onMouseEnter={(e) => (e.currentTarget.style.background = "var(--dsw-hover)")}
+												onMouseLeave={(e) => (e.currentTarget.style.background = "transparent")}
+												onClick={() => openFile(f, mode, mode === "staged" ? t.gitStagedDiff : mode === "untracked" ? t.gitUntracked : t.gitWorktreeDiff)}
+											>
+												<span
+													className="flex-none rounded px-1 text-center"
+													style={{ minWidth: 16, fontSize: 10.5, fontFamily: "var(--font-mono)", fontWeight: 600, color: KIND_COLOR[f.kind], background: "var(--dsw-hover)" }}
+												>
+													{f.kind === "untracked" ? "?" : f.kind === "conflict" ? "!" : mode === "staged" ? f.indexStatus : f.workStatus !== " " ? f.workStatus : f.indexStatus}
+												</span>
+												<span className="min-w-0 flex-1 truncate" style={{ fontSize: 12, fontFamily: "var(--font-mono)", color: "var(--dsw-label-secondary)" }}>
+													{f.path}
+												</span>
+											</button>
+										))}
+									</div>
+								</div>
+							))
 						)}
 
 						{/* 最近提交 */}

package/src/components/MarkdownBlock.tsx

@@ -7,13 +7,33 @@
  * 带着 lowlight/highlight.js 的常用语言集，实测占首屏 JS 的 472KB（全部首屏 JS 1272KB），
  * 而 Hero 页（还没开会话）根本用不到它。ChatWindow 用 next/dynamic 引用本模块，
  * 首屏不再下载这 472KB；AppShell 在空闲时预取，真正打开会话时通常已经就绪。
+ *
+ * 流式输出版（v7）：
+ * - 显示样式可配（见 lib/chat/stream-settings）：平滑 / 打字机 / 渐显 / 即时，速度五档、可选打字光标；
+ *   设置里改完下一帧生效，正在流的那条回答不用重开。
+ * - 逐帧推进：把「已到达的完整文本」和「已显示的文本」分开，每帧只把显示进度往前推一小步，
+ *   服务端 token 再来得快、再成串到达，界面也是匀速长出来的，不再一跳一跳。
+ * - 增量切分 + 分块记忆化：「已稳定的完整块」按 key 记忆化，扫描进度也复用上一帧，
+ *   每帧代价只与「新增的那几个字」成正比（旧版每帧重扫全文才是长回答的卡顿来源）。
+ * - 代码围栏内的 tail 用纯文本渲染，等闭合后再交给 highlight.js 高亮一次，
+ *   避免流式代码块每帧重新高亮。
+ * - 贴底听对话区的（见 chat/chat-scroll）；回答结束后先把还没放出来的字放完，再换成整段渲染。
  */
-import { memo, useEffect, useRef, useState } from "react";
+import { memo, useContext, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import ReactMarkdown from "react-markdown";
 import rehypeHighlight from "rehype-highlight";
 import remarkGfm from "remark-gfm";
+import { ChatScrollContext } from "@/components/chat/chat-scroll";
 import { IconCheckOutline14, IconCopyOutline16 } from "@/components/icons";
 import { copyText } from "@/lib/clipboard";
+import {
+	getServerStreamSettings,
+	getStreamSettings,
+	nextRevealEnd,
+	streamStepMs,
+	subscribeStreamSettings,
+	type StreamSettings,
+} from "@/lib/chat/stream-settings";
 import { useI18n } from "@/i18n";
 
 type MarkdownTextNode = { value?: unknown; children?: MarkdownTextNode[] };
@@ -84,51 +104,327 @@ function SafeImage({ src, alt, title }: { src?: unknown; alt?: string; title?: s
 	);
 }
 
+/**
+ * 只有 Markdown 内容、没有 .md 外层容器的纯内容组件。
+ * 流式分块时，多个块共用同一个 .md 容器（外边距规则因此照旧生效），
+ * 每块各自记忆化：只要 text 没变就不会重新解析。
+ */
+const MarkdownContent = memo(function MarkdownContent({ text }: { text: string }) {
+	return (
+		<ReactMarkdown
+			remarkPlugins={[remarkGfm]}
+			rehypePlugins={[[rehypeHighlight, { detect: false, ignoreMissing: true }]]}
+			components={{
+				a: ({ node: _node, ...props }) => <a {...props} target="_blank" rel="noopener noreferrer" />,
+				img: ({ src, alt, title }) => <SafeImage src={src} alt={alt} title={title} />,
+				pre: ({ node, children, ...props }) => (
+					<div className="md-code-block">
+						<div className="md-code-copy"><CopyButton text={markdownNodeText(node)} /></div>
+						<pre {...props}>{children}</pre>
+					</div>
+				),
+			}}
+		>
+			{text}
+		</ReactMarkdown>
+	);
+});
+
 export const MarkdownBlock = memo(function MarkdownBlock({ text }: { text: string }) {
 	return (
 		<div className="md">
-			<ReactMarkdown
-				remarkPlugins={[remarkGfm]}
-				rehypePlugins={[[rehypeHighlight, { detect: false, ignoreMissing: true }]]}
-				components={{
-					a: ({ node: _node, ...props }) => <a {...props} target="_blank" rel="noopener noreferrer" />,
-					img: ({ src, alt, title }) => <SafeImage src={src} alt={alt} title={title} />,
-					pre: ({ node, children, ...props }) => (
-						<div className="md-code-block">
-							<div className="md-code-copy"><CopyButton text={markdownNodeText(node)} /></div>
-							<pre {...props}>{children}</pre>
-						</div>
-					),
-				}}
-			>
-				{text}
-			</ReactMarkdown>
+			<MarkdownContent text={text} />
 		</div>
 	);
 });
 
-/** 流式正文的节流渲染（见 ChatWindow 的说明）：这里只负责延迟把稳定文本交给 MarkdownBlock */
-const STREAM_MARKDOWN_THROTTLE_MS = 100;
+// ---------- 流式渲染 ----------
+
+/** 列表项（含有序列表）；用于避免在松散列表内部的空行处切块 */
+const LIST_ITEM_RE = /^ {0,3}(?:[-*+]|\d+[.)])\s/;
+/** 围栏行：标记 + 其后的内容（开头行是语言等信息，闭合行只能是空白） */
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+/** 缩进起头的行：上面列表项的续行，或缩进代码块——都和前面连着，不从这里切 */
+const INDENTED_RE = /^[ \t]+\S/;
+
+interface FenceState {
+	inFence: boolean;
+	char: string;
+	length: number;
+}
+
+/**
+ * 按 CommonMark 推进围栏状态，返回这一行开启 / 闭合了围栏，或者都不是。
+ * 闭合行必须是同一种字符、不短于开头、后面没有别的内容：围栏里出现 "```js" 或更短的 "```"
+ * 都还是代码。反引号开头行的信息里不能再有反引号，否则那一行只是普通文本。
+ */
+function advanceFence(state: FenceState, line: string): "open" | "close" | null {
+	const fence = FENCE_RE.exec(line);
+	if (!fence) return null;
+	const [, marker, rest] = fence;
+	if (!state.inFence) {
+		if (marker[0] === "`" && rest.includes("`")) return null;
+		state.inFence = true;
+		state.char = marker[0];
+		state.length = marker.length;
+		return "open";
+	}
+	if (marker[0] === state.char && marker.length >= state.length && rest.trim() === "") {
+		state.inFence = false;
+		return "close";
+	}
+	return null;
+}
+
+export interface StreamingSplit {
+	/** 已稳定的完整块：文本不再变，各自记忆化，不会跟着尾巴一起重新解析 */
+	blocks: string[];
+	/** 正在生成的尾巴 */
+	tail: string;
+	/** 尾巴是否落在未闭合的代码围栏里 */
+	tailInFence: boolean;
+}
+
+/**
+ * 增量切分器：流式文本只会往后长，已经扫过的行不可能再改变判定，所以只扫新增的行。
+ * 每帧代价与「新增文本」成正比，长回答不会随长度增长而越来越卡（旧版每帧重扫全文）。
+ *
+ * 切分规则：
+ * - 只在代码围栏之外的空行处切：空行是天然的块边界，两侧各自都是完整可解析的 Markdown；
+ * - 还在列表里、下一行又是列表项（松散列表）时不切，保持有序列表序号连续。列表项下面缩进的
+ *   续段不算离开列表；空行后顶格的非列表行才算；
+ * - 下一行缩进起头时不切：那是上面列表项的续段（或缩进代码块），切开会被当成独立段落；
+ * - 半行（还没换行符）不急着判：半行 "2." 看着不像列表项，写完 "2. 乙" 才是，判早了会
+ *   把松散列表切开、序号重排。只有「再长也不会改变判定」时才就地判，否则等下一行写完。
+ */
+export function createStreamingSplitter(): { update: (text: string) => StreamingSplit } {
+	let prevText = "";
+	let scanPos = 0;
+	let fence: FenceState = { inFence: false, char: "", length: 0 };
+	let segStart = 0;
+	/** 最近一次顶格内容是列表项（还在列表里） */
+	let inList = false;
+	let prevBlank = true;
+	let blocks: string[] = [];
+
+	const reset = () => {
+		prevText = "";
+		scanPos = 0;
+		fence = { inFence: false, char: "", length: 0 };
+		segStart = 0;
+		inList = false;
+		prevBlank = true;
+		blocks = [];
+	};
+
+	return {
+		update(text: string): StreamingSplit {
+			// 被整体替换（编辑重发、切会话）时重头扫；正常流式是前缀延长
+			if (!text.startsWith(prevText)) reset();
+			prevText = text;
+			while (scanPos < text.length) {
+				const nl = text.indexOf("\n", scanPos);
+				// 半行不判：等换行到了再判（围栏行、空行边界都可能被这半行改变）
+				if (nl === -1) break;
+				const line = text.slice(scanPos, nl);
+				const wasInFence = fence.inFence;
+				const fenceStep = advanceFence(fence, line);
+				const blank = line.trim() === "";
+				if (!fence.inFence && blank) {
+					const nextStart = nl + 1;
+					const nextNl = text.indexOf("\n", nextStart);
+					const nextLine = text.slice(nextStart, nextNl === -1 ? text.length : nextNl);
+					const nextIndented = INDENTED_RE.test(nextLine);
+					// 下一行是否已经写完，或者「再长也不会改变判定」：缩进起头的永远不切；
+					// 不在列表里时，非空的下一行写成什么都要切
+					const decidable =
+						nextNl !== -1 ||
+						(nextStart < text.length && nextLine.trim() !== "" && (nextIndented || !inList));
+					if (!decidable) break; // scanPos 留在空行处，等下一行写完再判
+					const keepTogether = nextIndented || (inList && LIST_ITEM_RE.test(nextLine));
+					if (!keepTogether && nextLine.trim() !== "") {
+						const seg = text.slice(segStart, nextStart);
+						if (seg.trim()) blocks.push(seg);
+						segStart = nextStart;
+					}
+				}
+				// 列表状态只看围栏外的行：列表项进入列表；顶格的围栏、或空行后顶格的普通行离开列表
+				if (!wasInFence && !blank) {
+					if (LIST_ITEM_RE.test(line)) inList = true;
+					else if (fenceStep === "open" ? !INDENTED_RE.test(line) : prevBlank && !INDENTED_RE.test(line)) inList = false;
+				}
+				if (!wasInFence || !fence.inFence) prevBlank = blank;
+				scanPos = nl + 1;
+			}
+			return { blocks: blocks.slice(), tail: text.slice(segStart), tailInFence: fence.inFence };
+		},
+	};
+}
+
+/**
+ * 把落在未闭合围栏里的尾巴拆成「围栏前的 Markdown」和「围栏里的代码」。
+ * 开头那行（```python）不能当代码露出来；正在敲、还没换行的闭合行也不露。
+ */
+export function splitOpenFence(tail: string): { before: string; lang: string; code: string } {
+	const state: FenceState = { inFence: false, char: "", length: 0 };
+	let openAt = -1;
+	let codeAt = 0;
+	let lang = "";
+	let pos = 0;
+	while (pos < tail.length) {
+		const nl = tail.indexOf("\n", pos);
+		// 开头行一定是完整行：切分器只按完整行判围栏
+		if (nl === -1) break;
+		const line = tail.slice(pos, nl);
+		if (advanceFence(state, line) === "open") {
+			openAt = pos;
+			codeAt = nl + 1;
+			lang = (FENCE_RE.exec(line)?.[2] ?? "").trim().split(/\s+/)[0] ?? "";
+		}
+		pos = nl + 1;
+	}
+	if (openAt === -1 || !state.inFence) return { before: tail, lang: "", code: "" };
+	let code = tail.slice(codeAt);
+	const partial = code.slice(code.lastIndexOf("\n") + 1);
+	const marker = partial.trimStart();
+	if (marker && partial.length - marker.length <= 3 && marker[0] === state.char && /^(`+|~+)\s*$/.test(marker)) {
+		code = code.slice(0, code.length - partial.length);
+	}
+	return { before: tail.slice(0, openAt), lang, code };
+}
+
+/** 一次性切分（冷启动 / 测试用）；流式循环里请复用 createStreamingSplitter 的扫描进度 */
+export function splitStreamingMarkdown(text: string): StreamingSplit {
+	return createStreamingSplitter().update(text);
+}
+
+/** 流式偏好：设置面板一改，这里立刻换样式（正在流的那条回答不用重开） */
+function useStreamSettings(): StreamSettings {
+	return useSyncExternalStore(subscribeStreamSettings, getStreamSettings, getServerStreamSettings);
+}
+
+interface StreamView extends StreamingSplit {
+	/** 当前显示出来的部分（始终是目标文本的前缀） */
+	shown: string;
+}
+
+/**
+ * live：回答还在流。结束后（live 变 false）组件不急着换掉——先按原节奏把还没放出来的字放完，
+ * 追平后再渲染成整段 Markdown（和历史消息同一种渲染，脚注、引用式链接这类跨块语法也就对了）。
+ * 一结束就整段替换的话，打字机这类慢样式积压的一两百字会一口吐出来。
+ */
+export const StreamingMarkdownBlock = memo(function StreamingMarkdownBlock({ text, live = true }: { text: string; live?: boolean }) {
+	const settings = useStreamSettings();
+	const scroll = useContext(ChatScrollContext);
+	const splitterRef = useRef<{ update: (text: string) => StreamingSplit } | null>(null);
+	if (!splitterRef.current) splitterRef.current = createStreamingSplitter();
+	const [view, setView] = useState<StreamView>(() => ({ shown: text, ...splitterRef.current!.update(text) }));
+	const viewRef = useRef(view);
+	const targetRef = useRef(text);
+	const settingsRef = useRef(settings);
+	const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	const commit = (shown: string) => {
+		const next: StreamView = { shown, ...splitterRef.current!.update(shown) };
+		viewRef.current = next;
+		setView(next);
+	};
+
+	const stopTimer = () => {
+		if (timerRef.current !== null) clearTimeout(timerRef.current);
+		timerRef.current = null;
+	};
 
-export const StreamingMarkdownBlock = memo(function StreamingMarkdownBlock({ text }: { text: string }) {
-	const [shown, setShown] = useState(text);
-	const latest = useRef(text);
-	const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+	/** 一帧：只把显示进度往前推一点。用 setTimeout 而非 rAF：后台标签页 / 测试环境同样确定。 */
+	const step = () => {
+		timerRef.current = null;
+		const target = targetRef.current;
+		const shown = viewRef.current.shown;
+		if (shown === target) return; // 追平，收工（下次文本变化再启动）
+		if (!target.startsWith(shown)) {
+			commit(target); // 目标被整体替换（编辑重发）：直接跟上，不再逐帧
+			return;
+		}
+		const current = settingsRef.current;
+		commit(target.slice(0, nextRevealEnd(target, shown.length, current)));
+		timerRef.current = setTimeout(step, streamStepMs(current.speed));
+	};
+
+	/** 起节拍（已经在跑就不动）；「即时」不排队，直接追平 */
+	const start = () => {
+		if (timerRef.current !== null) return;
+		const current = settingsRef.current;
+		if (current.style === "instant") {
+			if (viewRef.current.shown !== targetRef.current) commit(targetRef.current);
+			return;
+		}
+		timerRef.current = setTimeout(step, streamStepMs(current.speed));
+	};
+
+	// 目标变化：更新目标，节拍没在跑就起一个。已有节拍时不重置计时器（防抖会让正文冻住）
+	useEffect(() => {
+		targetRef.current = text;
+		if (text !== viewRef.current.shown) start();
+	}, [text]);
+
+	// 偏好变化即时生效：切成「即时」就停表追平，切回别的样式就继续起节拍
 	useEffect(() => {
-		latest.current = text;
-		// 节流而不是防抖：计时器只在空闲时才设，期间到来的新文本只更新 latest、不重置计时。
-		// 若每次变化都清掉重来，文本一直在流（约 16ms 一次）时计时器永远到不了点，正文就冻住了。
-		if (text === shown || timer.current) return;
-		timer.current = setTimeout(() => {
-			timer.current = null;
-			setShown(latest.current);
-		}, STREAM_MARKDOWN_THROTTLE_MS);
-	}, [text, shown]);
-	useEffect(() => () => {
-		if (timer.current) clearTimeout(timer.current);
-		timer.current = null;
-	}, []);
-	return <MarkdownBlock text={shown} />;
+		settingsRef.current = settings;
+		if (viewRef.current.shown === targetRef.current) return;
+		if (settings.style === "instant") {
+			stopTimer();
+			commit(targetRef.current);
+			return;
+		}
+		start();
+	}, [settings]);
+
+	useEffect(() => () => stopTimer(), []);
+
+	const settled = !live && view.shown === text;
+
+	// 逐帧推进会让内容往下长：提交后（绘制前）跟着贴底，界面不再跳动。
+	// 贴不贴听对话区的（往上翻过、大纲正在跳转都会松开），这里不另量距离、不另设阈值；
+	// 追平那一帧和换成整段渲染那一帧同样会变高，也要贴。
+	useLayoutEffect(() => {
+		if (scroll?.shouldPin()) scroll.pin();
+	}, [view, settled, scroll]);
+
+	if (settled) return <MarkdownBlock text={text} />;
+
+	const { shown, blocks, tail, tailInFence } = view;
+	// 尾巴常驻同一个 key 的容器：块升级时尾巴原地更新而不是整棵重挂——
+	// 重挂会让渐显动画在「已经显示过的内容」上重播一遍，正是输出时闪烁几下的来源。
+	// 围栏未闭合时用与最终渲染相同的结构（md-code-block > pre > code，含复制按钮，同样不折行），
+	// 闭合升级只有语法着色的差别，没有布局跳变；开头的 ``` 行不进代码。
+	let tailNode: React.ReactNode;
+	if (tailInFence) {
+		const { before, lang, code } = splitOpenFence(tail);
+		tailNode = (
+			<>
+				{before.trim() ? <MarkdownContent text={before} /> : null}
+				<div className="md-code-block">
+					<div className="md-code-copy"><CopyButton text={code} /></div>
+					<pre><code className={lang ? `hljs language-${lang}` : undefined}>{code}</code></pre>
+				</div>
+			</>
+		);
+	} else {
+		tailNode = <MarkdownContent text={tail} />;
+	}
+
+	return (
+		<div
+			className={settings.caret ? "md pw-stream pw-stream-caret" : "md pw-stream"}
+			data-stream-style={settings.style}
+			data-stream-pending={shown === text ? undefined : ""}
+		>
+			{blocks.map((block, i) => <MarkdownContent key={i} text={block} />)}
+			{tail
+				? <div className="pw-stream-tail" key="tail">{tailNode}</div>
+				: null}
+		</div>
+	);
 });
 
 export default MarkdownBlock;