difftab 0.8.1 → 0.10.0

package/dist/server/main.js

@@ -400,6 +400,20 @@ async function emptyTree(root) {
 	return (format.code === 0 ? format.stdout.trim() : "sha1") === "sha256" ? EMPTY_TREE.sha256 : EMPTY_TREE.sha1;
 }
 
+//#endregion
+//#region src/server/shared/protocol.ts
+/**
+* 服务端 SSE 心跳周期（约 15s）。**它是协议的一部分，所以定在这里而不是 http/sse.ts**：
+* 后端拿它当发送周期，前端拿它当「对端还在」的判据。两边各写一个 15000，改周期时只改一边
+* 不会报错、也没有任何用例会红——前端的死连接判定就此静默失准，症状只是「有时候刷不出来」。
+*/
+const HEARTBEAT_MS = 15e3;
+/**
+* 一次搜索最多回多少行命中，到了即 `truncated`。**放在协议里**：前端的截断提示要说出这个数，各写
+* 一份时改了一边，页面上说的就不是真的。
+*/
+const MAX_SEARCH_LINES = 2e3;
+
 //#endregion
 //#region src/server/git/worktree.ts
 /**
@@ -419,7 +433,8 @@ const MAX_LINES = 5e4;
 * 只在**已判定为二进制之后**才查——单看扩展名会把一个内容是文本的 `.png`（占位符、被 LFS
 * 换成指针的图）送去 `<img>` 里画成一张破图，而它本来有一份能看的文本 diff。
 *
-* **SVG 刻意不在表里**：它是文本，走文本 diff 更有信息量。表也是 `/api/blob` 的 `Content-Type`
+* **SVG 刻意不在表里**：它是文本，走文本 diff 更有信息量；进了表，含 NUL 的 `.svg` 会从二进制
+* 那支被当成图放行。它的预览走 `isSvg` / `previewMimeOf` 那一路。表也是 `/api/blob` 的 `Content-Type`
 * 来源——`nosniff` 之下类型错一个字浏览器就不画，所以值必须是精确的 MIME。
 */
 const IMAGE_MIME = {
@@ -434,7 +449,24 @@ const IMAGE_MIME = {
 };
 /** 这条路径按扩展名算图片时给 MIME，否则 `null`。`posix.extname` 对 `.png` 这种点开头的名字给空串。 */
 function imageMimeOf(path) {
-	return IMAGE_MIME[posix.extname(path).slice(1).toLowerCase()] ?? null;
+	return IMAGE_MIME[extensionOf(path)] ?? null;
+}
+function extensionOf(path) {
+	return posix.extname(path).slice(1).toLowerCase();
+}
+/**
+* 这条路径的文本 payload 要不要带 `preview`。只看扩展名——它挂在**已判定为文本**的那一支上，
+* 与图片表「二进制之后才查」是对称的两半。
+*/
+function isSvg(path) {
+	return extensionOf(path) === "svg";
+}
+/**
+* `/api/blob` 认的 MIME：图片表并上 svg。**只给字节端点用**，分类链仍只认 `imageMimeOf`——两张
+* 表合成一张时，含 NUL 的 `.svg` 在 payload 里成了图。
+*/
+function previewMimeOf(path) {
+	return isSvg(path) ? "image/svg+xml" : imageMimeOf(path);
 }
 /** 坏请求（路径非法 / 目标不在了）。**不叫 `DiffRequestError`**：三条路都会抛它。 */
 var WorktreeError = class extends Error {
@@ -512,11 +544,11 @@ async function resolveInRepo(root, path, options) {
 * 在 **Buffer 上数**而不是 `split('\n').length`：后者为了得到一个数字，把整份文件又切成 N 个
 * 字符串立刻丢掉，而超限那一路根本不需要正文。
 */
-function countLines(buffer) {
-	if (buffer.length === 0) return 0;
+function countLines(text) {
+	if (text.length === 0) return 0;
 	let lines = 0;
-	for (let i = buffer.indexOf(10); i !== -1; i = buffer.indexOf(10, i + 1)) lines += 1;
-	return buffer[buffer.length - 1] === 10 ? lines : lines + 1;
+	for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) lines += 1;
+	return text.lastIndexOf("\n") === text.length - 1 ? lines : lines + 1;
 }
 /**
 * 工作区里一份内容的身份：体积 + mtime。**内容身份，不是时间戳**——前端拿它当 `<img>` 的
@@ -540,9 +572,13 @@ function worktreeVersion(info) {
 *   的一档。与 `text` 一样把 `buffer` 带出去：`/api/blob` 的新侧就是这条链，不另写一份「lstat →
 *   体积 → 读」的副本——上一份副本连 NUL 那道都没有，一个内容是文本的 `.png` 在 payload 里是
 *   文本、在字节端点上却被当图发出去。
-* - **`version` 是这份内容的身份**（`worktreeVersion`），前端拿它决定要不要重取。
+* - **`version` 是这份内容的身份**（`worktreeVersion`），前端拿它决定要不要重取。`text` 也带：
+*   SVG 的预览拿它当 `<img>` 的 `v=`。
+* - **`maxLines` 只给 `/api/blob` 的 SVG 新侧放宽**：行数闸挡的是「文本太长、表格画不动」，对一张
+*   图没有意义；旧侧的 `cat-file blob` 本就不数行，不放宽时一个五万行以上、只改了几行的 SVG
+*   会拿到预览，而 After 那张永远取不回来。
 */
-async function inspectFile(root, path) {
+async function inspectFile(root, path, { maxLines = MAX_LINES } = {}) {
 	const { abs } = await resolveInRepo(root, path, { follow: false });
 	let info;
 	try {
@@ -571,7 +607,7 @@ async function inspectFile(root, path) {
 		};
 	}
 	const lines = countLines(buffer);
-	if (lines > 5e4) return {
+	if (lines > maxLines) return {
 		kind: "too-large",
 		size: info.size,
 		reason: "lines"
@@ -581,7 +617,8 @@ async function inspectFile(root, path) {
 		buffer,
 		size: info.size,
 		lines,
-		executable: (info.mode & 73) !== 0
+		executable: (info.mode & 73) !== 0,
+		version: worktreeVersion(info)
 	};
 }
 
@@ -603,8 +640,9 @@ const FIELDS$1 = 6;
 *   都在射程内，而白名单只看子命令；
 * - 末尾的 `--`：`rev` 之后的任何东西都不再被当成选项。
 *
-* `rev` 必须已过 `assertOid`——它拼在 revision 位置，`GIT_LITERAL_PATHSPECS` 管不到那里，
-* `--output=<路径>` 在那个位置就是一次写文件。
+* `rev` 是一个完整对象名、字面量 `HEAD`，或两个完整对象名拼成的 `<a>..<b>`，每个对象名都必须已过
+* `assertOid`——它拼在 revision 位置，`GIT_LITERAL_PATHSPECS` 管不到那里，`--output=<路径>` 在那个
+* 位置就是一次写文件。
 */
 function logArgs(rev, count, skip) {
 	return [
@@ -651,6 +689,14 @@ function parseLog(output) {
 	}
 	return commits;
 }
+/** 取了 `PAGE_SIZE + 1` 条的 `log` 输出切成一页：多出来的那一条只用来判 `hasMore`。 */
+function toPage(stdout) {
+	const commits = parseLog(stdout);
+	return {
+		commits: commits.slice(0, 50),
+		hasMore: commits.length > 50
+	};
+}
 /**
 * 提交列表的一页。`head` 缺省即「从 HEAD 起」，并把 HEAD 此刻的 oid 回传当锚点；之后每一页
 * 都带着它再 `--skip`——按 HEAD 往下数时，agent 在两次翻页之间提交一次，第二页就重复第一页的
@@ -668,14 +714,25 @@ async function listCommits(root, query) {
 		};
 		throw new Error("HEAD points to a commit that cannot be read");
 	}
-	const commits = parseLog(result.stdout);
+	const page = toPage(result.stdout);
 	return {
-		head: query.head ?? commits[0]?.sha ?? null,
-		commits: commits.slice(0, 50),
-		hasMore: commits.length > 50
+		head: query.head ?? page.commits[0]?.sha ?? null,
+		...page
 	};
 }
 /**
+* 上游有、HEAD 走不到的提交（`<head>..<upstream>`），最新的在前，至多一页。两端都是请求带来的完整
+* 对象名：前端拿 HEAD oid 与它在 refs 里找到的上游 sha 来问，**不写 `HEAD..@{u}`**——`@{u}` 是又一种
+* 要钉的 revision 语法，而且解析的是此刻的上游，未必是前端徽标画着的那一个。任一端不是本仓库里的
+* 提交时 `log` 非零退出，一律 `not-found`。
+*/
+async function listIncoming(root, query) {
+	const range = `${assertOid(query.head)}..${assertOid(query.upstream)}`;
+	const result = await runGit(logArgs(range, 51), root);
+	if (result.code !== 0) throw new WorktreeError("not-found", "no such commit");
+	return toPage(result.stdout);
+}
+/**
 * 把请求里的 sha 落成 `CommitRange`。**对比端只在这里定一次**：三条路各自去找父提交时，将来
 * 改一处（比如合并提交换个父）漏改另一处，文件清单、补丁与图片就是对着三个不同的父在比，而
 * 不报错。
@@ -830,16 +887,16 @@ async function baseBlobSize(root, baseRef, normalizedPath) {
 	return Number.isSafeInteger(size) && size >= 0 ? size : null;
 }
 /**
-* 取一侧的字节。**非图片扩展名一律 400**——不限扩展名的话它就是一个「下载工作区任意文件」
+* 取一侧的字节。**图片表与 svg 之外的扩展名一律 400**——不限扩展名的话它就是一个「下载工作区任意文件」
 * 的端点，而 `/api/file` 读任意文本时至少还经过分类链与两道闸。
 *
 * 两侧都再卡一次 5MB（`MAX_BYTES`）：payload 已经按侧卡过，但字节是第二次请求，中间文件可以
-* 长大。`new` 侧走 `inspectFile`——与 payload 同一条链，NUL ∧ 扩展名两半都过；`old` 侧带
-* `maxStdoutBytes` 去撞，超限即就地掐断 git。
+* 长大。`new` 侧走 `inspectFile`——与 payload 同一条链：图片要 `image`（NUL ∧ 扩展名），svg 要
+* `text`，两种分类与扩展名必须对得上；`old` 侧带 `maxStdoutBytes` 去撞，超限即就地掐断 git。
 */
 async function readImageBytes(repo, path, side, commit) {
 	const { root } = repo;
-	const mime = imageMimeOf(path);
+	const mime = previewMimeOf(path);
 	if (mime === null) throw new WorktreeError("invalid-path", "not an image");
 	if (commit !== void 0) {
 		const resolved = await resolveCommit(repo, commit);
@@ -849,13 +906,14 @@ async function readImageBytes(repo, path, side, commit) {
 		};
 	}
 	if (side === "new") {
-		const file = await inspectFile(root, path);
+		const svg = isSvg(path);
+		const file = await inspectFile(root, path, svg ? { maxLines: Infinity } : {});
 		if (file.kind === "too-large") throw new WorktreeError("too-large", "image too large");
-		if (file.kind !== "image") throw new WorktreeError("invalid-path", "not an image");
-		return {
+		if (file.kind === "image" && !svg || file.kind === "text" && svg) return {
 			buffer: file.buffer,
 			mime
 		};
+		throw new WorktreeError("invalid-path", "not an image");
 	}
 	const [base, { path: normalized }] = await Promise.all([resolveDiffBase(root), resolveInRepo(root, path, { follow: false })]);
 	return {
@@ -986,39 +1044,46 @@ async function worktreeSize(abs) {
 	return (await worktreeStat(abs))?.size ?? null;
 }
 /**
-* 已跟踪图片的两侧元数据。**判据的二进制那一半是调用方给的（numstat 的 `-\t-`）**，这里只管
-* 扩展名命中之后的事：旧侧问基准（`cat-file -s`，不存在即 `null`——新增、或基准是空树），新侧
-* `lstat` 工作区（不存在即 `null`——已删除）。重命名的旧侧在 `oldPath`，`old.path` 填成它，前端
-* 拿着直接问 `/api/blob`，不自己拼。
+* 已跟踪图片（以及 SVG 预览）的两侧元数据。**判据是调用方给的**（图片是 numstat 的 `-\t-` ∧
+* 扩展名，SVG 是文本 ∧ 扩展名），这里只管命中之后的事：旧侧问基准（`cat-file -s`，不存在即
+* `null`——新增、或基准是空树），新侧 `lstat` 工作区（不存在即 `null`——已删除）。重命名的旧侧在
+* `oldPath`，`old.path` 填成它，前端拿着直接问 `/api/blob`，不自己拼。
 *
 * **`version` 是内容身份，前端拿它决定要不要重取**：旧侧是基准的 oid（`<base>:<path>` 那个 blob
 * 只在基准换了之后才可能变，而 oid 是 `resolveDiffBase` 那次 `rev-parse` 顺手就有的），新侧是
 * 体积 + mtime（`worktreeVersion`）。
 *
-* **5MB 按侧卡**：任一侧超过就整个回 `too-large`——一张 8MB 的 PNG 说「太大」是真话；`size`
-* 取**两侧里大的那个**（取不到给 0）：固定报工作区那份时，HEAD 里 8MB 的图被换成 120KB 的，提示
-* 会说「too large (file is 120 KB)」，而 Files 里同一个文件正常显示——自相矛盾。
+* 5MB 那道闸不在这里，在 `imagePayload` / `previewOf`：图片超限是整个 `too-large`，SVG 超限只是
+* 不带预览。
 */
-async function imageDiff(root, base, path, abs, oldPath) {
+async function worktreeImageSides(root, base, path, abs, oldPath) {
 	const basePath = oldPath ?? path;
 	const [oldSize, info] = await Promise.all([baseBlobSize(root, base.ref, basePath), worktreeStat(abs)]);
-	return imagePayload(oldSize === null ? null : {
-		path: basePath,
-		size: oldSize,
-		version: base.oid
-	}, info === null ? null : {
-		path,
-		size: info.size,
-		version: worktreeVersion(info)
-	});
+	return {
+		old: oldSize === null ? null : {
+			path: basePath,
+			size: oldSize,
+			version: base.oid
+		},
+		new: info === null ? null : {
+			path,
+			size: info.size,
+			version: worktreeVersion(info)
+		}
+	};
+}
+/** 两侧里大的那个，取不到给 0。 */
+function largestSide({ old, new: fresh }) {
+	return Math.max(old?.size ?? 0, fresh?.size ?? 0);
 }
 /**
-* 两侧元数据 → payload，工作区与提交两条路共用。**5MB 按侧卡**：任一侧超过就整个回 `too-large`；
-* `size` 取两侧里大的那个（取不到给 0）。两份各写时阈值或取哪一侧的体积漂开，同一张图在两个视图
-* 里一个说太大、一个照常画。
+* 两侧元数据 → payload，工作区与提交两条路共用。**5MB 按侧卡**：任一侧超过就整个回 `too-large`
+* ——一张 8MB 的 PNG 说「太大」是真话；`size` 取**两侧里大的那个**：固定报工作区那份时，HEAD 里
+* 8MB 的图被换成 120KB 的，提示会说「too large (file is 120 KB)」，而 Files 里同一个文件正常显示
+* ——自相矛盾。两份各写时阈值或取哪一侧的体积漂开，同一张图在两个视图里一个说太大、一个照常画。
 */
-function imagePayload(old, fresh) {
-	const largest = Math.max(old?.size ?? 0, fresh?.size ?? 0);
+function imagePayload(sides) {
+	const largest = largestSide(sides);
 	if (largest > 5242880) return {
 		kind: "too-large",
 		size: largest,
@@ -1026,11 +1091,17 @@ function imagePayload(old, fresh) {
 	};
 	return {
 		kind: "image",
-		old,
-		new: fresh
+		...sides
 	};
 }
 /**
+* SVG 的预览两侧，与 `imagePayload` 同一道 5MB 闸，**超限只是不带预览**：补丁可以只有几行、照常
+* 能看，而 `/api/blob` 会拒那张图——带上它等于给一枚点了必失败的开关。
+*/
+function previewOf$1(sides) {
+	return largestSide(sides) > 5242880 ? void 0 : sides;
+}
+/**
 * 已跟踪文件的补丁，以及三道拒绝。
 *
 * **已跟踪那一侧卡的是「补丁多大」，不是「文件多大」**：按文件体积拒绝的话，一个 6MB 的
@@ -1041,7 +1112,7 @@ function imagePayload(old, fresh) {
 * 顺序：二进制(numstat)→ 行数(numstat)→ 取补丁并卡字节。二进制先答是因为它比「太大」
 * 更具体（一个 8MB 的 PNG 说「文件过大」等于把原因说错了）；行数排在取补丁之前，是因为它
 * 不用付出取补丁的代价就能拦下 5 万行以上的改动。二进制里扩展名在表里的那一支放行成
-* `image`（`imageDiff`）——扩展名只在 git 已判定二进制之后才查，单看扩展名会把一个内容是
+* `image`（`imagePayload`）——扩展名只在 git 已判定二进制之后才查，单看扩展名会把一个内容是
 * 文本的 `.png` 画成破图。
 *
 * `path` / `oldPath` 是 `resolveInRepo` 归一化后的：图片那一路要把它拼进 `<base>:<path>`，
@@ -1053,53 +1124,109 @@ function imagePayload(old, fresh) {
 * **重命名条目必须同时传新旧两个路径**：只传新路径时 git 看不到另一侧、无法配对，会把
 * 重命名退化成一个全新增文件。两个路径都来自 status 的 `2 ` 记录，无需额外查询。
 */
-async function trackedDiff(root, base, path, abs, oldPath, stat) {
+async function trackedDiff(root, base, path, abs, oldPath, stat, options) {
 	return gatedPatch(root, {
 		range: [base.ref],
 		path,
 		oldPath,
 		stat,
-		image: () => imageDiff(root, base, path, abs, oldPath),
+		options,
+		sides: () => worktreeImageSides(root, base, path, abs, oldPath),
 		size: async () => await worktreeSize(abs) ?? 0
 	});
 }
-async function gatedPatch(root, source) {
-	const { range, path, oldPath, stat } = source;
-	if (stat?.binary) return imageMimeOf(path) === null ? { kind: "binary" } : source.image();
-	if (stat && stat.lines > 5e4) return {
-		kind: "too-large",
-		size: await source.size(),
-		reason: "lines"
-	};
-	const args = oldPath ? [
-		"diff",
-		...range,
-		"-M",
-		"--",
-		path,
-		oldPath
-	] : [
+/**
+* 取补丁那一次的 argv。**`--unified` 与 `--inter-hunk-context=0` 都必须显式**：用户配了 `diff.context`
+* 时 git 照配置给上下文，前端按 3 行推断的文件末尾随之错位；`diff.interHunkContext` 会把相隔几行的
+* 两段并成一个 hunk，前端在整份上下文里重算的折叠就与 `-U3` 那份对不上。`-w` 只给这
+* 一次——numstat 那次带上它时，只改了空白的文件不回记录，`null` 的含义从「不在差异里」变成「没有
+* 非空白的改动」，而它同时是已跟踪判定与两道闸的入口。
+*/
+function patchArgs(source, context) {
+	const { range, path, oldPath, options } = source;
+	return [
 		"diff",
 		...range,
-		"--",
-		path
+		`--unified=${context}`,
+		"--inter-hunk-context=0",
+		...options.ignoreWhitespace ? ["-w"] : [],
+		...oldPath ? [
+			"-M",
+			"--",
+			path,
+			oldPath
+		] : ["--", path]
 	];
+}
+/**
+* 带着上限取一次补丁。超限回 `null`——**超限是这一路要的答案而不是意外**：git 被就地掐断，补丁
+* 一个字节都不会发给前端。非零退出在这里没有第二种解释（路径不存在、基准无效都属于坏请求）。
+*/
+async function fetchPatch(root, args) {
 	let result;
 	try {
 		result = await runGit(args, root, { maxStdoutBytes: MAX_BYTES });
 	} catch (cause) {
-		if (cause instanceof GitError && cause.kind === "overflow") return {
-			kind: "too-large",
-			size: await source.size(),
-			reason: "size"
-		};
+		if (cause instanceof GitError && cause.kind === "overflow") return null;
 		throw cause;
 	}
 	if (result.code !== 0) throw new WorktreeError("not-found", "no diff available for this path");
-	return {
-		kind: "text",
-		patch: result.stdout
+	return result.stdout;
+}
+/**
+* 补丁头里任一侧是符号链接（mode 120000）。git 对链接给的「正文」是目标字符串，`/api/blob` 取到的
+* 也是它——带上预览只会是两张取不回来的图。只看第一个 hunk 之前的头部：正文里出现这串数字不算。
+*/
+function touchesSymlink(patch) {
+	const end = patch.indexOf("\n@@");
+	const header = end === -1 ? patch : patch.slice(0, end);
+	return /^(?:(?:old|new|new file|deleted file) mode 120000|index \S+ 120000)$/m.test(header);
+}
+/**
+* 文本补丁出来之后，SVG 再挂上预览两侧。**只对 svg 才去问两侧**：那是一次 `cat-file -s` 加一次
+* `lstat`，其余文本一次都不欠。符号链接不带（`touchesSymlink`）。
+*/
+async function withPreview(source, payload) {
+	if (!isSvg(source.path) || touchesSymlink(payload.patch)) return payload;
+	const preview = previewOf$1(await source.sides());
+	return preview === void 0 ? payload : {
+		...payload,
+		preview
+	};
+}
+async function gatedPatch(root, source) {
+	const { path, stat } = source;
+	if (stat?.binary) return imageMimeOf(path) === null ? { kind: "binary" } : imagePayload(await source.sides());
+	if (stat && stat.lines > 5e4) return {
+		kind: "too-large",
+		size: await source.size(),
+		reason: "lines"
+	};
+	/**
+	* 整份上下文是 `--unified=<MAX_LINES>`，**过了「补丁不超过 `MAX_LINES` 行」这道闸就一定是整份
+	* 文件**：没包住整份文件的补丁必有一侧连续 `MAX_LINES` 行上下文被收进来，再加至少一行改动就超了。
+	* 过不了闸（含字节超限）时**退回 3 行上下文再取一次、标 `full: false`**，不回 `too-large`：一个
+	* 6MB 的数据文件改一行，3 行上下文的补丁照样看得见。
+	*/
+	if (source.options.fullContext) {
+		const full = await fetchPatch(root, patchArgs(source, MAX_LINES));
+		if (full !== null && countLines(full) <= 5e4) return withPreview(source, {
+			kind: "text",
+			patch: full,
+			full: true
+		});
+	}
+	const patch = await fetchPatch(root, patchArgs(source, 3));
+	if (patch === null) return {
+		kind: "too-large",
+		size: await source.size(),
+		reason: "size"
 	};
+	return withPreview(source, {
+		kind: "text",
+		patch,
+		full: false
+	});
 }
 /** unified diff 的头四行。未跟踪的一切都是「新增」，左侧恒为 /dev/null。 */
 function newFileHeader(path, mode) {
@@ -1155,7 +1282,15 @@ async function untrackedDiff(root, path) {
 			...head,
 			`@@ -0,0 +1,${lines.length} @@`,
 			...body
-		].join("\n")}\n`
+		].join("\n")}\n`,
+		...isSvg(path) && { preview: {
+			old: null,
+			new: {
+				path,
+				size: file.size,
+				version: file.version
+			}
+		} }
 	};
 }
 async function readDiff(root, query) {
@@ -1163,7 +1298,7 @@ async function readDiff(root, query) {
 	const oldPath = query.oldPath ? (await resolveInRepo(root, query.oldPath, { follow: false })).path : void 0;
 	const [base, listed] = await Promise.all([resolveDiffBase(root), inIndex(root, path)]);
 	const stat = await readNumstat(root, [base.ref], path, oldPath);
-	if (listed || stat !== null) return trackedDiff(root, base, path, abs, oldPath, stat);
+	if (listed || stat !== null) return trackedDiff(root, base, path, abs, oldPath, stat, query);
 	return untrackedDiff(root, path);
 }
 /**
@@ -1187,27 +1322,31 @@ async function readCommitDiff(repo, sha, query) {
 		path,
 		oldPath,
 		stat,
-		image: () => commitImageDiff(root, parent, commit.sha, path, oldPath),
+		options: query,
+		sides: () => commitImageSides(root, parent, commit.sha, path, oldPath),
 		size: async () => await baseBlobSize(root, commit.sha, path) ?? await baseBlobSize(root, parent, oldPath ?? path) ?? 0
 	});
 }
 /**
-* 提交里图片的两侧，**都读对象库**：旧侧 `<parent>:<旧路径或路径>`、新侧 `<sha>:<路径>`，与
+* 提交里图片（以及 SVG 预览）的两侧，**都读对象库**：旧侧 `<parent>:<旧路径或路径>`、新侧 `<sha>:<路径>`，与
 * 工作区 diff 的旧侧同一条 `cat-file -s`。`version` 是两端的对象名——提交不可变，这两个身份
 * 永远不会换内容。
 */
-async function commitImageDiff(root, parent, sha, path, oldPath) {
+async function commitImageSides(root, parent, sha, path, oldPath) {
 	const basePath = oldPath ?? path;
 	const [oldSize, newSize] = await Promise.all([baseBlobSize(root, parent, basePath), baseBlobSize(root, sha, path)]);
-	return imagePayload(oldSize === null ? null : {
-		path: basePath,
-		size: oldSize,
-		version: parent
-	}, newSize === null ? null : {
-		path,
-		size: newSize,
-		version: sha
-	});
+	return {
+		old: oldSize === null ? null : {
+			path: basePath,
+			size: oldSize,
+			version: parent
+		},
+		new: newSize === null ? null : {
+			path,
+			size: newSize,
+			version: sha
+		}
+	};
 }
 
 //#endregion
@@ -1229,7 +1368,11 @@ async function readFileContent(root, path) {
 		};
 		case "text": return {
 			kind: "text",
-			content: file.buffer.toString("utf8")
+			content: file.buffer.toString("utf8"),
+			...isSvg(path) && { preview: {
+				size: file.size,
+				version: file.version
+			} }
 		};
 	}
 }
@@ -1310,20 +1453,6 @@ async function listRefs(root) {
 	return { refs: parseRefs(await runGitStrict(REF_ARGS, root)) };
 }
 
-//#endregion
-//#region src/server/shared/protocol.ts
-/**
-* 服务端 SSE 心跳周期（约 15s）。**它是协议的一部分，所以定在这里而不是 http/sse.ts**：
-* 后端拿它当发送周期，前端拿它当「对端还在」的判据。两边各写一个 15000，改周期时只改一边
-* 不会报错、也没有任何用例会红——前端的死连接判定就此静默失准，症状只是「有时候刷不出来」。
-*/
-const HEARTBEAT_MS = 15e3;
-/**
-* 一次搜索最多回多少行命中，到了即 `truncated`。**放在协议里**：前端的截断提示要说出这个数，各写
-* 一份时改了一边，页面上说的就不是真的。
-*/
-const MAX_SEARCH_LINES = 2e3;
-
 //#endregion
 //#region src/server/git/search.ts
 /** 查询的长度上限（UTF-16 码元）。再长就不是「搜一个东西」了，而它整条进 argv。 */
@@ -2492,6 +2621,12 @@ const SECURITY_HEADERS = {
 	].join("; ")
 };
 /**
+* `/api/blob` 回 SVG 时换上的 CSP。`<img>` 里的 SVG 本就不跑脚本、不取外链，但直接打开那条 URL
+* 时它是一份同源文档：`sandbox` 把它放进不透明源，内联脚本与事件属性一律不跑；`style-src
+* 'unsafe-inline'` 只为 SVG 自带的 `<style>` 与 `style=` 属性——它们是画图的一部分。
+*/
+const SVG_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";
+/**
 * 把 token 落成 cookie 的 Set-Cookie 值。`HttpOnly; SameSite=Strict` + 随后 302 掉 query，
 * 避免 token 长期滞留在浏览器历史、地址栏和日志中。不设 `Secure`——那会让
 * http://127.0.0.1 上的 cookie 直接不生效。
@@ -2561,10 +2696,11 @@ function sanitizeMessage(message, repoRoot) {
 	if (home) out = out.split(home).join("~");
 	return out.split("\n")[0]?.trim() ?? "";
 }
-function send(res, status, body, contentType) {
+function send(res, status, body, contentType, headers = {}) {
 	const payload = typeof body === "string" ? Buffer.from(body, "utf8") : body;
 	res.writeHead(status, {
 		...SECURITY_HEADERS,
+		...headers,
 		"Content-Type": contentType,
 		"Content-Length": payload.byteLength
 	});
@@ -2573,6 +2709,25 @@ function send(res, status, body, contentType) {
 function sendJson(res, status, body) {
 	send(res, status, JSON.stringify(body), "application/json; charset=utf-8");
 }
+const PATCH_OPTION_ERROR = "ignoreWhitespace and fullContext only accept 1";
+/**
+* 两个补丁开关：缺省即关，**只认 `1`、其余值回 `null`（400）**。与 `/api/search` 的 `case` / `word`
+* （非 `1` 即关）刻意不同：唯一的调用方是前端，写成 `true` 的笔误在宽松解析下是一个静默不生效的开关。
+*/
+function patchOptionsOf(params) {
+	const flag = (name) => {
+		const value = params.get(name);
+		if (value === null) return false;
+		return value === "1" ? true : null;
+	};
+	const ignoreWhitespace = flag("ignoreWhitespace");
+	const fullContext = flag("fullContext");
+	if (ignoreWhitespace === null || fullContext === null) return null;
+	return {
+		ignoreWhitespace,
+		fullContext
+	};
+}
 async function startServer(repo, options = {}) {
 	/**
 	* 出站错误一律经此发出，**sanitize 就做在这里**。只在兜底的 500 分支上做时，「响应体
@@ -2738,10 +2893,16 @@ async function startServer(repo, options = {}) {
 					sendError(res, 400, "bad-request", "path is required");
 					return;
 				}
+				const options = patchOptionsOf(url.searchParams);
+				if (options === null) {
+					sendError(res, 400, "bad-request", PATCH_OPTION_ERROR);
+					return;
+				}
 				const oldPath = url.searchParams.get("oldPath");
 				sendJson(res, 200, await readDiff(repo.root, {
 					path,
-					...oldPath ? { oldPath } : {}
+					...oldPath ? { oldPath } : {},
+					...options
 				}));
 				return;
 			}
@@ -2766,10 +2927,11 @@ async function startServer(repo, options = {}) {
 				return;
 			}
 			/**
-			* 图片字节，**唯一一个正文不是 JSON 的 API 端点**。`path` / `side` 都必填：`old` 是
-			* diff 基准里的 blob、`new` 是工作区那份；带 `commit` 时两侧都读对象库（第一父 / 提交本身）。只服务图片扩展名表里的路径、`Content-Type`
-			* 按表给精确 MIME（`nosniff` 之下类型错一个字浏览器就不画），非图片一律 400——判据与
-			* 5MB 那道闸都在 git 那侧，这里只把字节发出去。前端加的 `v=` 戳这里不看。
+			* 图片与 SVG 预览的字节，**唯一一个正文不是 JSON 的 API 端点**。`path` / `side` 都必填：
+			* `old` 是 diff 基准里的 blob、`new` 是工作区那份；带 `commit` 时两侧都读对象库（第一父 /
+			* 提交本身）。只服务图片扩展名表里的路径与 svg、`Content-Type` 按表给精确 MIME（`nosniff`
+			* 之下类型错一个字浏览器就不画），其余一律 400——判据与 5MB 那道闸都在 git 那侧，这里只把
+			* 字节发出去。前端加的 `v=` 戳这里不看。
 			*/
 			case "/api/blob": {
 				const path = url.searchParams.get("path");
@@ -2784,7 +2946,8 @@ async function startServer(repo, options = {}) {
 				}
 				const commit = url.searchParams.get("commit");
 				const image = await readImageBytes(repo, path, side, commit ?? void 0);
-				send(res, 200, image.buffer, image.mime);
+				const headers = isSvg(path) ? { "Content-Security-Policy": SVG_CSP } : {};
+				send(res, 200, image.buffer, image.mime, headers);
 				return;
 			}
 			/**
@@ -2805,6 +2968,23 @@ async function startServer(repo, options = {}) {
 				}));
 				return;
 			}
+			/**
+			* 上游有、HEAD 走不到的提交，至多一页、不翻页。两个参数都必填；是不是完整对象名归 `assertOid`，
+			* 与 `/api/commits` 的 `head` 同一把钥匙。
+			*/
+			case "/api/commits/incoming": {
+				const head = url.searchParams.get("head");
+				const upstream = url.searchParams.get("upstream");
+				if (!head || !upstream) {
+					sendError(res, 400, "bad-request", "head and upstream are required");
+					return;
+				}
+				sendJson(res, 200, await listIncoming(repo.root, {
+					head,
+					upstream
+				}));
+				return;
+			}
 			case "/api/commit": {
 				const sha = url.searchParams.get("sha");
 				if (!sha) {
@@ -2822,10 +3002,16 @@ async function startServer(repo, options = {}) {
 					sendError(res, 400, "bad-request", "sha and path are required");
 					return;
 				}
+				const options = patchOptionsOf(url.searchParams);
+				if (options === null) {
+					sendError(res, 400, "bad-request", PATCH_OPTION_ERROR);
+					return;
+				}
 				const oldPath = url.searchParams.get("oldPath");
 				sendJson(res, 200, await readCommitDiff(repo, sha, {
 					path,
-					...oldPath ? { oldPath } : {}
+					...oldPath ? { oldPath } : {},
+					...options
 				}));
 				return;
 			}