@konnga/dsh-hud 0.8.0 → 0.9.0

package/README.md

@@ -67,6 +67,19 @@ dsh-hud · git:(main*) ↑1 ↓2 M4 A1 ?1 │ ●3
 - **看差异**：两栏 —— 左边还是面板，右边是差异。工具栏有 `未暂存` / `已暂存` 页签、`自动换行`、`复制差异`。点 hunk 头可折叠那一段。
 - **看提交**：三栏 —— 面板 │ 这次提交 │ 差异，并自动打开这次提交的第一个文件。`Esc` 或 `✕` 收起。
 - **两条抓握可以拖**：右边缘那条调差异栏宽度（默认 470px）；提交明细栏右边那条调提交明细栏（默认 240px）—— 路径被截断就往左拖。两条宽度都会记住。
+- **看图片改动**：二进制文件里认得出是图片时（PNG / JPEG / GIF / WebP / BMP，**按文件头认，不看扩展名**），差异栏画成两张图并排 —— 也可以切成单张来回看 —— 并给出尺寸变化与字节变化（`1024×768 → 1024×512`、`2.0 KB → 1.0 KB`）。两侧各自说明"为什么画不出来"：超过单侧 4 MB 预览上限、不是可预览的图片、或缺这一侧（新增 / 删除）。未暂存看「索引 → 工作区」，已暂存看「HEAD → 索引」，提交明细看「父提交 → 这次提交」—— 与文本 diff 的页签语义完全一致。
+- **图片缩放**：工具条上是常显的 `−` / 档位 / `＋`：默认「适应宽度」，档位走 25% / 50% / 100% / 150% / 200%（200% 封顶），点档位本身回到「适应宽度」。固定档位按**图片固有像素**算宽度（宽高由宿主一并给出，第一帧就算对，不用等图片加载），超出部分由差异栏横向滚动。档位**会记住**（与「自动换行」一样落盘）。<br>内置的右侧文档预览也有缩放，但它的控件是**藏在"预览区底部 72px 的悬停感应带"里的浮层**（CSS 默认 `opacity:0`，指针离开 420ms 收起），滚轮缩放还必须按 Ctrl/⌘ —— 看不见按钮是正常的；这一排按钮就是为了不依赖它。
+
+### 轮尾的「本轮图片改动」（在内置改动卡片旁边）
+
+内置那张「已编辑 N 个文件」的卡片，点一行是打开本轮的 review tab —— 图片在那里看不见（内置正文对二进制只给一句文案，而且没有给插件留正文槽位）。所以本插件在同一处轮尾放了一条自己的门：
+
+![轮尾的「本轮图片改动」：三张缩略图，命令行旁听来的两张带 ◐ 标记，每张后面跟着一个 ⇄，末尾写「还有 3 个」](docs/images/turn-images.webp)
+
+- **点缩略图 → 在右侧内置文档预览里打开这张图**（图片原生渲染、可缩放）；
+- 右边那个 `⇄` → 打开本插件的面板，看这张图的**前后对比**（内置预览只有当前这一版）；
+- 只列**这一轮**改过的图片（按会话归因里的回合号收窄），最近改的在前，最多 4 张 + `还有 N 个`；这一轮没动过图片时整条不渲染；
+- 归因**两档都收**：写文件/编辑工具改的算确定（不标符号），从 shell 命令里认出来的标 `◐`、悬停给出那条命令 —— 图基本是脚本产出的（`python gen.py`、`cp`、`curl -o`），只收确定档等于收不到东西。
 
 ### 侧栏会话行（悬停或点行尾 `⋯`）
 
@@ -98,10 +111,11 @@ main* ↑0 ↓0 · 已修改 7 未跟踪 2
 
 ## 它不做什么
 
-- **只读**：不写 index、不动工作区与 git 配置，不执行 `add` / `commit` / `checkout` / `fetch`；不读文件内容，不显示凭证。
+- **只读**：不写 index、不动工作区与 git 配置，不执行 `add` / `commit` / `checkout` / `fetch`；不显示凭证。**读文件内容只有一种情形**：看图片改动时读那两侧的字节 —— 只读、只在内存里、走数据 URL 画出来，不落盘、不外链。
 - **归因是两档估计**：经写文件 / 编辑工具的算「确定改过」；从 shell 命令里认出来的算「可能相关」（`>` `>>` `tee`、`sed -i` / `perl -i`、`mv` / `cp` / `rm` / `touch` / `dd of=`、`git checkout|restore <路径>`）。**会漏也会多报**，所以永远标 `◐`，不冒充 `●`；其余命令只记进命令历史，不猜路径。
 - **记录不落盘**：会话改动与工具活动都活在宿主进程里，重启归零；每个会话会写明「自 … 起记录」。
 - **上限**：改动清单 200 条、单会话归因 500 个文件、标签 100 个、最近提交 10 条 —— 超出只计数并标 `truncated`。
+- **图片预览的边界**：只认 PNG / JPEG / GIF / WebP / BMP（按文件头，不认 SVG）；单侧超过 4 MB 只报大小不画图；**只在本插件的差异栏里生效** —— DSH 自带的改动对比页（内置 `deliverables` 的 `changes-review` 页签）没有给"文件正文"留槽位，插件改不了那一页。
 - **审阅签名用 `size + mtimeMs`**：`touch` 一下（内容没变）也会让「已审」失效 —— 宁可让你多看一眼。
 - **计数按文件算**：未跟踪不折叠目录（与编辑器一致）；同一个文件「既暂存又改动」算 1 条。
 

package/lib/client.js

@@ -120,6 +120,31 @@ window.__ModuleLoader__.load({
       "diff.copied": "已复制",
       "diff.empty": "这一侧没有差异",
       "diff.binary": "二进制文件，没有可显示的文本差异",
+      // ── 图片预览（二进制改动里认得出的那几种） ──
+      "image.loading": "读取图片…",
+      "image.pair": "并排",
+      "image.flip": "切换",
+      "image.beforeWorktree": "索引",
+      "image.afterWorktree": "工作区",
+      "image.beforeIndex": "HEAD",
+      "image.afterIndex": "索引",
+      "image.beforeCommit": "父提交",
+      "image.afterCommit": "这次提交",
+      "image.dims": "{w}×{h}",
+      "image.dimsChanged": "尺寸 {from} → {to}",
+      "image.tooLarge": "超过 {limit} MB 预览上限（{size}）",
+      "image.notImage": "不是可预览的图片（{size}）",
+      "image.missing": "这一侧没有这个文件",
+      "image.zoomOut": "缩小",
+      "image.zoomIn": "放大",
+      "image.fitWidth": "适应宽度",
+      "image.zoomValue": "{percent}%",
+      // ── 轮尾的「本轮图片改动」条 ──
+      "turnImages.title": "本轮图片改动",
+      "turnImages.titleSession": "本会话图片改动",
+      "turnImages.open": "在内置预览里打开",
+      "turnImages.compare": "在 dsh-hud 里前后对比",
+      "turnImages.more": "还有 {n} 个",
       "diff.truncated": "差异过大，仅显示前面部分",
       "diff.untrackedHint": "未跟踪文件，与空文件对比",
       "diff.commitHint": "这次提交相对其父提交的差异（只读）",
@@ -231,6 +256,31 @@ window.__ModuleLoader__.load({
       "diff.copied": "Copied",
       "diff.empty": "No changes on this side",
       "diff.binary": "Binary file — no text diff to show",
+      // ── Image preview (binary changes we can recognise) ──
+      "image.loading": "Reading image…",
+      "image.pair": "Side by side",
+      "image.flip": "Flip",
+      "image.beforeWorktree": "index",
+      "image.afterWorktree": "worktree",
+      "image.beforeIndex": "HEAD",
+      "image.afterIndex": "index",
+      "image.beforeCommit": "parent",
+      "image.afterCommit": "this commit",
+      "image.dims": "{w}×{h}",
+      "image.dimsChanged": "size {from} → {to}",
+      "image.tooLarge": "over the {limit} MB preview limit ({size})",
+      "image.notImage": "not a previewable image ({size})",
+      "image.missing": "not present on this side",
+      "image.zoomOut": "Zoom out",
+      "image.zoomIn": "Zoom in",
+      "image.fitWidth": "Fit width",
+      "image.zoomValue": "{percent}%",
+      // ── Turn-tail "images this turn" strip ──
+      "turnImages.title": "Images this turn",
+      "turnImages.titleSession": "Images this session",
+      "turnImages.open": "Open in the built-in preview",
+      "turnImages.compare": "Compare before/after in dsh-hud",
+      "turnImages.more": "{n} more",
       "diff.truncated": "Diff is large; showing the beginning only",
       "diff.untrackedHint": "Untracked file, diffed against an empty file",
       "diff.commitHint": "What this commit changed against its parent (read-only)",
@@ -321,11 +371,14 @@ window.__ModuleLoader__.load({
       added: "var(--dsw-alias-state-success-primary, #3fb950)",
       deleted: "var(--dsw-alias-state-error-primary, #f06a6a)",
       // 与 codex-hud 的 `statEntries` 一一对应：R→cyan、C→brightBlue（我们的品牌蓝就是这个位）、
-      // T→magenta、?→dim。M/A/D/! 本来就一致（yellow/green/red/critical）。
+      // T→magenta、?→灰。M/A/D/! 本来就一致（yellow/green/red/critical）。
+      // `?` 用 `label-secondary` 而不是 `label-dimmed`：后者是**反相的表面色**（浅 #e1e5ee、深 #43454a），
+      // 当文字压在面板底色上只有 1.26:1 / 1.64:1 —— 看不见（issue：未跟踪计数读不出来）。
+      // secondary 仍是中性灰、比彩色状态弱一档，但浅 5.8:1 / 深 10.4:1 都读得清。
       renamed: "var(--dsh-hud-cyan, #22d3ee)",
       copied: "var(--dsw-alias-brand-primary, #4b8bf5)",
       typeChanged: "var(--dsh-hud-magenta, #d946ef)",
-      untracked: "var(--dsw-alias-label-dimmed, #8a8f98)",
+      untracked: "var(--dsw-alias-label-secondary, #8a8f98)",
       conflicted: "var(--dsw-alias-state-error-primary, #f06a6a)",
     };
 
@@ -359,6 +412,29 @@ window.__ModuleLoader__.load({
 
     /* --------------------------------------------------------- 本地 UI 状态 */
 
+    /** 固定缩放档位：与内置文档预览的菜单一致（25% / 50% / 100% / 150% / 200%）。 */
+    var ZOOM_STEPS = [0.25, 0.5, 1, 1.5, 2];
+
+    /** 落盘/读回的缩放值：只认档位里的数，其他一律当"适应宽度"。 */
+    function readZoom(ui) {
+      return ui && ZOOM_STEPS.indexOf(ui.zoom) >= 0 ? ui.zoom : null;
+    }
+
+    /**
+     * 走一档缩放。
+     *
+     * `null`（适应宽度）出发：`＋` 从 100% 开始、`−` 从 50% 开始 —— 和"适应宽度"的直觉一致，
+     * 不用先经过 25% 才知道按了有反应。
+     */
+    function stepZoom(current, direction) {
+      if (current === null || current === undefined) return direction > 0 ? 1 : 0.5;
+      var index = ZOOM_STEPS.indexOf(current);
+      if (index < 0) return direction > 0 ? 1 : 0.5;
+      var next = index + (direction > 0 ? 1 : -1);
+      if (next < 0 || next >= ZOOM_STEPS.length) return current;
+      return ZOOM_STEPS[next];
+    }
+
     function readUi() {
       try {
         var raw = window.localStorage.getItem(UI_KEY);
@@ -754,6 +830,7 @@ window.__ModuleLoader__.load({
           open: state.panelOpen,
           pos: state.pos,
           wrap: state.diff ? state.diff.wrap === true : false,
+          zoom: state.diff && ZOOM_STEPS.indexOf(state.diff.zoom) >= 0 ? state.diff.zoom : null,
           diffWidth: state.diffWidth,
           commitWidth: state.commitWidth,
         });
@@ -783,11 +860,12 @@ window.__ModuleLoader__.load({
         if (!state.cwd || !change || !change.file) return Promise.resolve();
         var cwd = state.cwd;
         var wrap = state.diff ? state.diff.wrap === true : readUi().wrap === true;
+        var zoom = state.diff && ZOOM_STEPS.indexOf(state.diff.zoom) >= 0 ? state.diff.zoom : readZoom(readUi());
         set({
           // 工作区差异与「某次提交的明细」是互斥的两种右栏内容，换过去就收起明细。
           commit: null,
           cursor: change.file,
-          diff: { source: "worktree", phase: "loading", path: change.path, file: change.file, origPath: change.origFile || null, data: null, side: "worktree", wrap: wrap, hunk: 0, collapsed: [], errorCode: null },
+          diff: { source: "worktree", phase: "loading", path: change.path, file: change.file, origPath: change.origFile || null, data: null, side: "worktree", wrap: wrap, zoom: zoom, hunk: 0, collapsed: [], errorCode: null },
         });
 
         diffInflight = Promise.resolve()
@@ -815,6 +893,7 @@ window.__ModuleLoader__.load({
                   data: value,
                   side: worktreeRows > 0 || indexRows === 0 ? "worktree" : "index",
                   wrap: current.wrap,
+                  zoom: current.zoom,
                   hunk: 0,
                   collapsed: [],
                   errorCode: null,
@@ -956,6 +1035,7 @@ window.__ModuleLoader__.load({
             data: null,
             side: "commit",
             wrap: wrap,
+            zoom: state.diff && ZOOM_STEPS.indexOf(state.diff.zoom) >= 0 ? state.diff.zoom : readZoom(readUi()),
             hunk: 0,
             collapsed: [],
             errorCode: null,
@@ -1012,6 +1092,52 @@ window.__ModuleLoader__.load({
         set({ diff: null });
       }
 
+      /* --------------------------------------------------- 图片预览（二进制） */
+
+      /**
+       * 图片两侧的缓存：键与请求一一对应。
+       *
+       * 一张图的 base64 可能上兆，所以命中就不重取；条目数有上限（超了整表清空，
+       * 和宿主的 `CACHE_MAX_ENTRIES` 同一个思路：宁可少缓存，也不要无界增长）。
+       */
+      var imagePairs = new Map();
+      var IMAGE_CACHE_MAX = 8;
+
+      /**
+       * 同步看一眼缓存：命中就返回条目，否则 null。
+       *
+       * 有了它，`ImageDiff` 的**第一次渲染**就能把已经取过的图画出来 ——
+       * 关掉再打开同一张图不该先闪一下"读取图片…"，也不该再发一次请求。
+       */
+      function cachedImagePair(request) {
+        if (request === null || request === undefined) return null;
+        var entry = imagePairs.get(imagePairKey(request));
+        return entry === undefined ? null : entry;
+      }
+
+      /** 供 `ImageDiff` 用：取一个二进制改动两侧的字节与尺寸（同一个请求只发一次）。 */
+      function loadImagePair(request) {
+        var key = imagePairKey(request);
+        var cached = imagePairs.get(key);
+        if (cached !== undefined) return Promise.resolve(cached);
+
+        return Promise.resolve()
+          .then(function () {
+            return ctx.connection.rpc.call(CHANNEL, "image", { args: request });
+          })
+          .then(function (result) {
+            var entry = result && result.ok === true && result.value
+              ? { phase: "ready", value: result.value }
+              : { phase: "error", code: result && result.error && result.error.details ? result.error.details.code : null };
+            if (imagePairs.size >= IMAGE_CACHE_MAX) imagePairs.clear();
+            imagePairs.set(key, entry);
+            return entry;
+          })
+          .catch(function () {
+            return { phase: "error", code: "transport" };
+          });
+      }
+
       /**
        * 收起右栏。提交明细把差异包在里面，所以它优先整体退掉；
        * 只有工作区差异时才只是关掉差异。
@@ -1134,6 +1260,19 @@ window.__ModuleLoader__.load({
         persist();
       }
 
+      /**
+       * 图片缩放的档位（`null` = 适应宽度）。
+       *
+       * 放在 store 而不是组件里：一来记住（和"自动换行"一样落盘），二来组件的 hooks
+       * 在这个假 React 里驱动不了嵌套状态 —— store 的状态任何位置都读得到。
+       */
+      function setZoom(value) {
+        if (!state.diff) return;
+        var next = value === null || ZOOM_STEPS.indexOf(value) >= 0 ? value : null;
+        set({ diff: Object.assign({}, state.diff, { zoom: next }) });
+        persist();
+      }
+
       /** dock 行的位置变了才写，避免每次测量都触发重渲染。 */
       function setAnchorTop(top) {
         if (state.anchorTop === top) return;
@@ -1624,10 +1763,14 @@ window.__ModuleLoader__.load({
         setCommitWidth: setCommitWidth,
         persistLayout: persist,
         openDiff: openDiff,
+        loadImagePair: loadImagePair,
+        cachedImagePair: cachedImagePair,
+        loadSessionChanges: loadSessionChanges,
         closeDiff: closeDiff,
         closeDetail: closeDetail,
         setDiffSide: setDiffSide,
         toggleDiffWrap: toggleDiffWrap,
+        setZoom: setZoom,
         openCommit: openCommit,
         openCommitDiff: openCommitDiff,
         toggleCommit: toggleCommit,
@@ -2237,10 +2380,432 @@ window.__ModuleLoader__.load({
      * 差异视图：两侧页签（宿主半一次把两侧都取回来了，切页签不再发请求）、
      * 自动换行、复制差异。全部只读——它只是把 git 的输出画出来。
      */
+    /* ------------------------------------------------ 图片预览（二进制改动） */
+
+    /** 图片请求的缓存键：把请求的每个字段都带上，免得两侧共用一个键。 */
+    function imagePairKey(request) {
+      return [request.cwd || "", request.path || "", request.origPath || "", request.side || "", request.sha || ""].join("\u0000");
+    }
+
+    /**
+     * 由 diff 状态推出 `image` 请求；推不出（没有 cwd / 文件）返回 null。
+     *
+     * 页签语义与文本 diff 完全一致：未暂存看「索引 → 工作区」，已暂存看「HEAD → 索引」，
+     * 提交明细按 sha 取，所以两个视图里"未暂存 / 已暂存"指的是同一件事。
+     */
+    function imageRequest(diff, cwd) {
+      if (!diff || !diff.file || !cwd) return null;
+      var request = { cwd: cwd, path: diff.file };
+      if (diff.origPath) request.origPath = diff.origPath;
+      if (diff.source === "commit" && diff.sha) request.sha = diff.sha;
+      else request.side = diff.side === "index" ? "index" : "worktree";
+      return request;
+    }
+
+    /** 两侧的标签跟着"看的到底是哪两条记录"走。 */
+    function imageLabels(diff, t) {
+      if (diff.source === "commit") return { before: t("image.beforeCommit"), after: t("image.afterCommit") };
+      if (diff.side === "index") return { before: t("image.beforeIndex"), after: t("image.afterIndex") };
+      return { before: t("image.beforeWorktree"), after: t("image.afterWorktree") };
+    }
+
+    /** 字节数：十进制 KB/MB，和文件管理器里看到的一致。 */
+    function formatBytes(bytes) {
+      if (typeof bytes !== "number" || !isFinite(bytes) || bytes < 0) return "?";
+      if (bytes < 1000) return String(bytes) + " B";
+      if (bytes < 1000 * 1000) return (bytes / 1000).toFixed(1) + " KB";
+      return (bytes / 1000 / 1000).toFixed(2) + " MB";
+    }
+
+    /** 一侧画不出来时的原因文案（每一侧各有各的原因）。 */
+    function sideReasonText(side, t) {
+      if (side.kind === "too-large") {
+        return t("image.tooLarge", {
+          limit: String(Math.round((typeof side.limit === "number" ? side.limit : 0) / 1024 / 1024)),
+          size: formatBytes(side.bytes),
+        });
+      }
+      if (side.kind === "not-image") return t("image.notImage", { size: formatBytes(side.bytes) });
+      return t("image.missing");
+    }
+
+    /**
+     * 两张都画不出来时说什么：能说清原因就说原因，否则退回原来那句话。
+     * "太大"优先于"不是图" —— 前者才是用户会想处理的那件事。
+     */
+    function imageFallbackText(t, before, after) {
+      var sides = [before, after];
+      var tooLarge = sides.filter(function (side) { return side.kind === "too-large"; })[0];
+      if (tooLarge !== undefined) return sideReasonText(tooLarge, t);
+      var notImage = sides.filter(function (side) { return side.kind === "not-image"; })[0];
+      if (notImage !== undefined) return sideReasonText(notImage, t);
+      return t("diff.binary");
+    }
+
+    /**
+     * 二进制（图片）改动的预览：并排两张图，或按需在两张之间切换。
+     *
+     * 只在文本 diff 报 `binary` 时挂上来。字节来自宿主的 `image` 端点（只读），
+     * 这里只负责画：单侧画不出来就画那一侧的原因，两侧都不行才退回原来那句话。
+     */
+    function ImageDiff(props) {
+      var t = props.t;
+      var store = props.store;
+      var diff = props.diff;
+      var request = imageRequest(diff, props.cwd);
+      var key = request === null ? null : imagePairKey(request);
+      // 先同步看缓存：已经取过的图第一帧就画出来，不闪"读取图片…"。
+      var viewRef = React.useState(function () {
+        return store.cachedImagePair ? store.cachedImagePair(request) : null;
+      });
+      var modeRef = React.useState("pair");
+      var flipRef = React.useState("after");
+
+      React.useEffect(function () {
+        if (key === null) return undefined;
+        var cancelled = false;
+        var cached = store.cachedImagePair ? store.cachedImagePair(request) : null;
+        if (cached !== null) {
+          viewRef[1](cached);
+          return undefined;
+        }
+        viewRef[1](null);
+        store.loadImagePair(request).then(function (entry) {
+          if (!cancelled) viewRef[1](entry);
+        });
+        return function () { cancelled = true; };
+      }, [key]);
+
+      if (key === null) return h("div", { className: "dshh-empty", "data-dsh-hud": "image" }, t("diff.binary"));
+
+      var view = viewRef[0];
+      if (view === null) return h("div", { className: "dshh-empty", "data-dsh-hud": "image" }, t("image.loading"));
+      if (view.phase === "error") return h("div", { className: "dshh-empty", "data-dsh-hud": "image" }, errorText(view.code, t));
+
+      var value = view.value || {};
+      var before = value.before || { kind: "missing" };
+      var after = value.after || { kind: "missing" };
+      if (before.kind !== "image" && after.kind !== "image") {
+        return h("div", { className: "dshh-empty", "data-dsh-hud": "image" }, imageFallbackText(t, before, after));
+      }
+
+      var labels = imageLabels(diff, t);
+      var mode = modeRef[0];
+      var flip = flipRef[0];
+      // 缩放住在 store 里（和"自动换行"一样记住）：`null` = 适应宽度，数字 = 固定档位。
+      var zoom = diff.zoom === undefined ? null : diff.zoom;
+      var cells = mode === "pair"
+        ? [{ key: "before", label: labels.before, side: before }, { key: "after", label: labels.after, side: after }]
+        : [{ key: flip, label: flip === "after" ? labels.after : labels.before, side: flip === "after" ? after : before }];
+
+      function cell(entry) {
+        var side = entry.side;
+        var body = side.kind === "image"
+          ? h("img", {
+              className: "dshh-img",
+              alt: entry.label,
+              // 缩放：适应宽度交给 CSS（`max-width:100%`）；固定档位按**固有像素**算宽度，
+              // 因为宿主已经把宽高一起给我们了 —— 不用等图片加载就能算对。
+              style: zoom === null || typeof side.width !== "number"
+                ? undefined
+                : { width: Math.round(side.width * zoom) + "px", maxWidth: "none" },
+              src: "data:" + side.mime + ";base64," + String(side.base64 || ""),
+            })
+          : h("div", { className: "dshh-imgNote" }, sideReasonText(side, t));
+        return h("div", { className: "dshh-imgCell", key: entry.key },
+          h("div", { className: "dshh-imgLabel" }, entry.label),
+          body);
+      }
+
+      function tab(id, label) {
+        var active = mode === id;
+        return h("button", {
+          type: "button",
+          className: "dshh-tab" + (active ? " dshh-tabActive" : ""),
+          "aria-pressed": active ? "true" : "false",
+          onClick: function () { modeRef[1](id); },
+        }, label);
+      }
+
+      // 尺寸变了才是这张图最值得一眼看到的信息（改图最常见的就是换尺寸）。
+      var dimsChanged = before.kind === "image" && after.kind === "image"
+        && typeof before.width === "number" && typeof after.width === "number"
+        && (before.width !== after.width || before.height !== after.height)
+        ? h("span", { className: "dshh-imgDims" }, t("image.dimsChanged", {
+            from: t("image.dims", { w: String(before.width), h: String(before.height) }),
+            to: t("image.dims", { w: String(after.width), h: String(after.height) }),
+          }))
+        : null;
+      var bytes = before.kind === "image" && after.kind === "image"
+        ? h("span", { className: "dshh-imgBytes" }, formatBytes(before.bytes) + " → " + formatBytes(after.bytes))
+        : null;
+
+      // 缩放按钮：内置那个文档预览把缩放藏在"预览区底部 72px 的悬停感应带"里
+      // （CSS 默认 opacity:0，还得 Ctrl+滚轮），这里给一排看得见、点的着的。
+      var zoomControls = h("span", { className: "dshh-imgZoom", "data-dsh-hud": "image-zoom" }, [
+        h("button", {
+          key: "out",
+          type: "button",
+          className: "dshh-imgZoomBtn",
+          title: t("image.zoomOut"),
+          "data-dsh-hud": "image-zoom-out",
+          onClick: function () { store.setZoom(stepZoom(zoom, -1)); },
+        }, "−"),
+        h("button", {
+          key: "value",
+          type: "button",
+          className: "dshh-imgZoomBtn dshh-imgZoomValue",
+          title: t("image.fitWidth"),
+          "data-dsh-hud": "image-zoom-value",
+          onClick: function () { store.setZoom(null); },
+        }, zoom === null ? t("image.fitWidth") : t("image.zoomValue", { percent: String(Math.round(zoom * 100)) })),
+        h("button", {
+          key: "in",
+          type: "button",
+          className: "dshh-imgZoomBtn",
+          title: t("image.zoomIn"),
+          "data-dsh-hud": "image-zoom-in",
+          onClick: function () { store.setZoom(stepZoom(zoom, 1)); },
+        }, "＋"),
+      ]);
+
+      return h("div", { className: "dshh-imgWrap", "data-dsh-hud": "image" },
+        h("div", { className: "dshh-imgMeta" },
+          tab("pair", t("image.pair")),
+          mode === "flip"
+            ? h("button", {
+                type: "button",
+                className: "dshh-tab",
+                title: t("image.flip"),
+                "data-dsh-hud": "image-flip",
+                onClick: function () { flipRef[1](flip === "after" ? "before" : "after"); },
+              }, t("image.flip"))
+            : null,
+          zoomControls,
+          dimsChanged,
+          bytes),
+        h("div", {
+          className: "dshh-imgPair" + (mode === "flip" ? " dshh-imgPairSingle" : "") + (zoom === null ? "" : " dshh-imgPairZoomed"),
+        }, cells.map(cell)));
+    }
+
+    /* ----------------------------------------- 轮尾：本轮改过的图片（一条门） */
+
+    /** 图片类文件的扩展名。这里只做粗筛 —— 真正"是不是图"由宿主按文件头判断。 */
+    var IMAGE_FILE_EXTENSIONS = ["png", "jpg", "jpeg", "gif", "webp", "bmp", "ico", "avif"];
+
+    /** 按扩展名粗筛"这看起来是张图"。 */
+    function looksLikeImage(file) {
+      if (typeof file !== "string") return false;
+      var dot = file.lastIndexOf(".");
+      if (dot < 0 || dot === file.length - 1) return false;
+      return IMAGE_FILE_EXTENSIONS.indexOf(file.slice(dot + 1).toLowerCase()) >= 0;
+    }
+
+    /** 只取文件名（chip 上放不下整条路径）。 */
+    function baseNameOf(file) {
+      var parts = String(file).split("/");
+      return parts[parts.length - 1] || String(file);
+    }
+
+    /**
+     * 槽位给的是宿主的 `TurnLocation`。
+     *
+     * 形状属于宿主内部约定（槽位文档只说"receives the Turn"），所以这里宽松取值：
+     * 取不到就回 null，由调用方退到"本会话"的说法，而不是整条不显示。
+     */
+    function turnNumberOf(turn) {
+      if (typeof turn === "number" && isFinite(turn)) return turn;
+      if (turn && typeof turn === "object" && typeof turn.turn === "number") return turn.turn;
+      return null;
+    }
+
+    /**
+     * 从会话改动里挑出"这一轮改过的图片"，最近的在前。
+     *
+     * **两档都收**：`●` 确定改过（写文件 / 编辑工具）与 `◐` 命令旁听（`>`、`tee`、`cp`、`rm`…）。
+     * 只收确定档不够用 —— 图几乎都是脚本/命令产出的（`python gen.py`、`cp`、`curl -o`），
+     * 那些永远进不了确定档，而"点一下看图"对它们一样有用。`◐` 是猜的，所以 chip 上带 `◐`、
+     * 悬停给出那条命令（措辞与面板里改动清单一致）。
+     *
+     * 回合号拿不到（`turnNumberOf` 回 null）就不按回合收窄，退回"本会话最近的图片改动"。
+     *
+     * @returns `{ files, exact }`；`exact` 为 false 表示标题该说"本会话"而不是"本轮"。
+     */
+    function imageChangesOf(changes, turnNumber) {
+      if (changes === null || changes === undefined) return { files: [], exact: turnNumber !== null };
+      var confirmed = changes.files ? changes.files : {};
+      var guessed = changes.possible ? changes.possible : {};
+      var picked = [];
+      var seen = {};
+
+      for (var file in confirmed) {
+        if (!Object.prototype.hasOwnProperty.call(confirmed, file)) continue;
+        if (!looksLikeImage(file)) continue;
+        var record = confirmed[file] || {};
+        if (turnNumber !== null) {
+          var turns = Array.isArray(record.turns) ? record.turns : [];
+          if (turns.indexOf(turnNumber) < 0 && record.lastTurn !== turnNumber) continue;
+        }
+        seen[file] = true;
+        picked.push({
+          file: file,
+          name: baseNameOf(file),
+          tier: "confirmed",
+          reason: "",
+          at: typeof record.lastAt === "number" ? record.lastAt : 0,
+        });
+      }
+
+      for (var guess in guessed) {
+        if (!Object.prototype.hasOwnProperty.call(guessed, guess)) continue;
+        if (seen[guess] === true) continue;
+        if (!looksLikeImage(guess)) continue;
+        var item = guessed[guess] || {};
+        // 命令旁听只记"最近一次"的回合号（没有 turns 列表），所以只能按 lastTurn 收窄。
+        if (turnNumber !== null && item.lastTurn !== turnNumber) continue;
+        seen[guess] = true;
+        picked.push({
+          file: guess,
+          name: baseNameOf(guess),
+          tier: "possible",
+          reason: typeof item.reason === "string" ? item.reason : "",
+          at: typeof item.lastAt === "number" ? item.lastAt : 0,
+        });
+      }
+
+      picked.sort(function (left, right) { return right.at - left.at; });
+      return { files: picked, exact: turnNumber !== null };
+    }
+
+    /** 缩略图用哪一侧的字节：优先工作区，其次基线（新增/删除时只有一侧有）。 */
+    function thumbSideOf(entry) {
+      if (entry === null || entry.phase !== "ready" || !entry.value) return null;
+      var pair = entry.value;
+      if (pair.after && pair.after.kind === "image") return pair.after;
+      if (pair.before && pair.before.kind === "image") return pair.before;
+      return null;
+    }
+
+    /**
+     * 轮尾那条「本轮图片改动」：每项一张缩略图 + 文件名。
+     *
+     * 内置的改动卡片点一行是打开 review tab（图片在那儿看不见），这条是补上的门：
+     * **点缩略图 → 槽位给的 `openFile(path)`**，即内置的右侧文档预览（图片原生渲染、可缩放）；
+     * 旁边那个 `⇄` 才打开 dsh-hud 面板看前后两张 —— 前后对比只有我们有。
+     */
+    function TurnImages(props) {
+      var t = props.t;
+      var store = props.store;
+      var sessionId = props.sessionId;
+      var useSessions = props.useSessions;
+      var openFile = props.openFile;
+      var turnNumber = turnNumberOf(props.turn);
+
+      // useSessions 是选择器 hook：选择器参数是必需的。
+      var sessions = typeof useSessions === "function" ? useSessions(function (snapshot) { return snapshot; }) : null;
+      var summary = sessionId !== undefined && sessions && sessions.byId ? sessions.byId[sessionId] : undefined;
+      var cwd = summary ? summary.cwd : undefined;
+
+      var state = useStore(store);
+      // 缩略图要等字节；缓存本身不在快照里，所以取完自增一下触发重画。
+      var tick = React.useState(0);
+      var bump = tick[1];
+
+      // 轮尾每个已完成的回合都会挂一次：绑定会话 + 没取过会话改动就取一次（宿主侧是内存读，很便宜）。
+      React.useEffect(function () {
+        if (sessionId === undefined || cwd === undefined) return undefined;
+        store.bindSession(sessionId, cwd);
+        if (state.sessionChanges === undefined || state.sessionChanges.phase === "idle") store.loadSessionChanges();
+        return undefined;
+      }, [sessionId, cwd]);
+
+      var picked = imageChangesOf(state.sessionChanges, turnNumber);
+      var shown = picked.files.slice(0, 4);
+      var keys = shown.map(function (entry) { return entry.file; }).join("\u0000");
+
+      React.useEffect(function () {
+        if (keys === "" || cwd === undefined) return undefined;
+        var cancelled = false;
+        var wanted = shown.map(function (entry) {
+          return { cwd: cwd, path: entry.file, side: "worktree" };
+        }).filter(function (request) {
+          return store.cachedImagePair(request) === null;
+        });
+        if (wanted.length === 0) return undefined;
+        Promise.all(wanted.map(function (request) { return store.loadImagePair(request); })).then(function () {
+          if (!cancelled) bump(function (count) { return count + 1; });
+        });
+        return function () { cancelled = true; };
+      }, [keys, cwd]);
+
+      // 会话改动还没到、或这一轮没动过图：整条不渲染（不在每条轮尾留个空壳）。
+      if (state.sessionChanges === undefined || state.sessionChanges.phase !== "ready") return null;
+      if (shown.length === 0) return null;
+
+      var rest = picked.files.length - shown.length;
+
+      function chip(entry) {
+        var thumb = thumbSideOf(cwd === undefined ? null : store.cachedImagePair({ cwd: cwd, path: entry.file, side: "worktree" }));
+        var dot = entry.name.lastIndexOf(".");
+        var extension = dot > 0 ? entry.name.slice(dot + 1).toUpperCase() : "?";
+        // `◐` 是命令旁听来的（猜的）：说清这一点，并把那条命令放进悬停里。
+        var hint = entry.file + " · " + t("turnImages.open");
+        if (entry.tier === "possible" && entry.reason !== "") hint += " · " + t("session.possibleTitle", { reason: entry.reason });
+        return h("span", {
+          key: entry.file,
+          className: "dshh-imgstripItem",
+          "data-dsh-hud": "turn-image",
+          "data-file": entry.file,
+          "data-tier": entry.tier,
+        }, [
+          h("button", {
+            key: "open",
+            type: "button",
+            className: "dshh-imgstripOpen",
+            title: hint,
+            onClick: function () { if (typeof openFile === "function") openFile(entry.file); },
+          }, [
+            thumb === null
+              ? h("span", { key: "ph", className: "dshh-imgstripThumb dshh-imgstripThumbEmpty" }, extension)
+              : h("img", {
+                  key: "img",
+                  className: "dshh-imgstripThumb",
+                  alt: entry.name,
+                  src: "data:" + thumb.mime + ";base64," + String(thumb.base64 || ""),
+                }),
+            entry.tier === "possible"
+              ? h("span", { key: "tier", className: "dshh-imgstripTier", title: hint }, "◐")
+              : null,
+            h("span", { key: "name", className: "dshh-imgstripName" }, entry.name),
+          ]),
+          h("button", {
+            key: "compare",
+            type: "button",
+            className: "dshh-imgstripCompare",
+            title: t("turnImages.compare"),
+            "data-dsh-hud": "turn-image-compare",
+            onClick: function () {
+              store.openPanel(true);
+              store.openDiff({ file: entry.file, path: entry.file, origFile: null });
+            },
+          }, "⇄"),
+        ]);
+      }
+
+      return h("div", { className: "dshh-imgstrip", "data-dsh-hud": "turn-images" }, [
+        h("span", { key: "title", className: "dshh-imgstripTitle" }, picked.exact ? t("turnImages.title") : t("turnImages.titleSession")),
+        h("span", { key: "items", className: "dshh-imgstripItems" }, shown.map(chip)),
+        rest > 0 ? h("span", { key: "more", className: "dshh-imgstripMore" }, t("turnImages.more", { n: String(rest) })) : null,
+      ]);
+    }
+
     function DiffView(props) {
       var t = props.t;
       var diff = props.diff;
       var store = props.store;
+      // 图片预览要按工作区发请求；文本 diff 用不到它。
+      var cwd = props.cwd;
 
       var copiedRef = React.useState(false);
       var copied = copiedRef[0];
@@ -2308,7 +2873,8 @@ window.__ModuleLoader__.load({
       } else if (!data) {
         body = h("div", { className: "dshh-empty" }, t("diff.empty"));
       } else if (data.binary === true) {
-        body = h("div", { className: "dshh-empty" }, t("diff.binary"));
+        // 二进制里最常被改的就是图：能认出来就画出来，认不出才退回那句话。
+        body = h(ImageDiff, { t: t, store: store, diff: diff, cwd: cwd });
       } else if (rows.length === 0) {
         body = h("div", { className: "dshh-empty" }, t("diff.empty"));
       } else {
@@ -3310,7 +3876,7 @@ window.__ModuleLoader__.load({
               onPointerDown: function (event) { onGripPointerDown("commit", event); },
             })
             : null,
-          diffMode ? h(DiffView, { t: t, diff: state.diff, store: store }) : null)
+          diffMode ? h(DiffView, { t: t, diff: state.diff, store: store, cwd: state.cwd }) : null)
         : listBody;
 
       return h("div", { className: "dshh-panel", "data-dsh-hud": "panel", style: panelStyle },
@@ -3446,14 +4012,17 @@ window.__ModuleLoader__.load({
       ".dshh-rowhover{display:flex;flex-direction:column;gap:2px;font-size:11px;",
       "color:var(--dsw-alias-label-secondary,#8a8f98);min-width:0;}",
       ".dshh-rowhoverLine{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}",
+      // 「已审 x/y」是个可点控件：同样不能用 label-dimmed（反相表面色，1.26:1 / 1.64:1），
+      // 平时用次级文字色，悬停才升到正文色。
       ".dshh-review{flex:none;margin-left:auto;padding:0 2px;font-size:10.5px;cursor:pointer;",
-      "color:var(--dsw-alias-label-dimmed,rgba(138,143,152,0.65));}",
+      "color:var(--dsw-alias-label-secondary,#8a8f98);}",
       ".dshh-review:hover{color:var(--dsw-alias-label-primary,#e5e7eb);}",
       ".dshh-reviewOn{color:var(--dsw-alias-state-success-primary,#3fb950);}",
       ".dshh-reviewStale{color:var(--dsw-alias-state-warn-primary,#d9a63c);}",
       ".dshh-ctag{flex:0 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;",
       "font-family:ui-monospace,Consolas,monospace;font-size:11px;color:var(--dsw-alias-state-warn-primary,#d9a63c);}",
-      ".dshh-markerOther{color:var(--dsw-alias-label-dimmed,rgba(138,143,152,0.6));}",
+      // 行首的 `○`（与本会话无关）：要"最不显眼"，但同样得看得见 —— 与上面同一个理由。
+      ".dshh-markerOther{color:var(--dsw-alias-label-secondary,#8a8f98);}",
       // 工具活动胶囊：与 Git 胶囊同形，但它是只读读数，指针不该是“可点”。
       // 与 codex-hud 对齐的几支色（它的默认配色表：git=magenta、gitBranch=cyan、project=yellow）：
       // 产品没有青/品红的语义变量（只有 button-info-*，那是按钮用的），所以这两支写死值，
@@ -3520,6 +4089,57 @@ window.__ModuleLoader__.load({
       ".dshh-cwhen{flex:none;font-size:10.5px;color:var(--dsw-alias-label-secondary,#8a8f98);}",
       ".dshh-note{font-size:11px;color:var(--dsw-alias-label-secondary,#8a8f98);}",
       ".dshh-empty{padding:14px 12px;font-size:12px;color:var(--dsw-alias-label-secondary,#8a8f98);}",
+      // ---- 图片预览（二进制改动） ----
+      ".dshh-imgWrap{flex:1 1 auto;min-height:0;overflow:auto;padding:10px;display:flex;flex-direction:column;gap:8px;}",
+      ".dshh-imgMeta{display:flex;align-items:center;gap:8px;flex-wrap:wrap;font-size:11px;",
+      "color:var(--dsw-alias-label-secondary,#8a8f98);}",
+      ".dshh-imgDims{color:var(--dsw-alias-state-warn-primary,#d9a63c);}",
+      ".dshh-imgBytes{font-family:ui-monospace,Consolas,monospace;}",
+      ".dshh-imgPair{display:flex;gap:10px;align-items:flex-start;flex-wrap:wrap;}",
+      ".dshh-imgPairSingle{flex-wrap:nowrap;}",
+      // 固定档位（非"适应宽度"）时：图片按固有像素算宽度，容器随内容撑开，外层横向滚动。
+      ".dshh-imgPairZoomed{flex-wrap:nowrap;width:max-content;align-items:flex-start;}",
+      ".dshh-imgPairZoomed .dshh-imgCell{flex:0 0 auto;}",
+      ".dshh-imgPairZoomed .dshh-img{max-height:none;}",
+      ".dshh-imgZoom{display:inline-flex;align-items:center;gap:2px;margin-left:auto;}",
+      ".dshh-imgZoomBtn{border:1px solid var(--dsw-alias-border-l1,rgba(127,127,127,0.25));",
+      "background:var(--dsw-alias-bg-layer-1,transparent);color:inherit;cursor:pointer;font:inherit;",
+      "min-width:22px;height:20px;padding:0 6px;border-radius:5px;display:inline-flex;align-items:center;justify-content:center;}",
+      ".dshh-imgZoomBtn:hover{color:var(--dsw-alias-label-primary,#e5e7eb);",
+      "border-color:var(--dsw-alias-border-l2,rgba(127,127,127,0.45));}",
+      ".dshh-imgZoomValue{min-width:74px;font-variant-numeric:tabular-nums;}",
+      ".dshh-imgCell{flex:1 1 150px;min-width:0;display:flex;flex-direction:column;gap:4px;}",
+      ".dshh-imgLabel{font-size:11px;color:var(--dsw-alias-label-secondary,#8a8f98);}",
+      ".dshh-imgNote{font-size:11px;color:var(--dsw-alias-label-secondary,#8a8f98);padding:6px 0;}",
+      // 透明像素要有底色才看得出边界：棋盘格由四段半透明渐变拼出来，两种主题都不用另配颜色。
+      ".dshh-img{max-width:100%;max-height:420px;object-fit:contain;border-radius:6px;",
+      "border:1px solid var(--dsw-alias-border-l1,rgba(127,127,127,0.28));",
+      "background-image:linear-gradient(45deg,rgba(127,127,127,0.12) 25%,transparent 25%),",
+      "linear-gradient(-45deg,rgba(127,127,127,0.12) 25%,transparent 25%),",
+      "linear-gradient(45deg,transparent 75%,rgba(127,127,127,0.12) 75%),",
+      "linear-gradient(-45deg,transparent 75%,rgba(127,127,127,0.12) 75%);",
+      "background-size:16px 16px;background-position:0 0,0 8px,8px -8px,-8px 0;}",
+      // ---- 轮尾「本轮图片改动」条 ----
+      ".dshh-imgstrip{display:flex;align-items:center;gap:8px;flex-wrap:wrap;font-size:11px;",
+      "color:var(--dsw-alias-label-secondary,#8a8f98);}",
+      ".dshh-imgstripTitle{flex:none;}",
+      ".dshh-imgstripItems{display:flex;gap:6px;flex-wrap:wrap;}",
+      ".dshh-imgstripItem{display:inline-flex;align-items:center;gap:2px;padding:2px 4px 2px 2px;",
+      "border:1px solid var(--dsw-alias-border-l1,rgba(127,127,127,0.25));border-radius:8px;",
+      "background:var(--dsw-alias-bg-layer-1,transparent);}",
+      ".dshh-imgstripOpen{display:inline-flex;align-items:center;gap:6px;border:0;background:transparent;",
+      "color:inherit;cursor:pointer;padding:0;font:inherit;}",
+      ".dshh-imgstripOpen:hover{color:var(--dsw-alias-label-primary,#e5e7eb);}",
+      ".dshh-imgstripThumb{width:28px;height:28px;object-fit:cover;border-radius:5px;display:block;",
+      "background:var(--dsw-alias-bg-layer-2,rgba(127,127,127,0.14));}",
+      ".dshh-imgstripThumbEmpty{align-items:center;justify-content:center;font-size:8px;letter-spacing:0.02em;",
+      "display:flex;color:var(--dsw-alias-label-secondary,#8a8f98);}",
+      ".dshh-imgstripName{max-width:150px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}",
+      ".dshh-imgstripTier{flex:none;opacity:.7;}",
+      ".dshh-imgstripCompare{border:0;background:transparent;color:inherit;cursor:pointer;padding:0 2px;",
+      "font:inherit;opacity:.7;}",
+      ".dshh-imgstripCompare:hover{opacity:1;color:var(--dsw-alias-brand-primary,#4b8bf5);}",
+      ".dshh-imgstripMore{flex:none;}",
       ".dshh-footer{display:flex;justify-content:space-between;gap:8px;padding:6px 10px;flex:none;",
       "border-top:1px solid var(--dsw-alias-border-l1,rgba(127,127,127,0.22));",
       "font-size:10.5px;color:var(--dsw-alias-label-secondary,#8a8f98);}",
@@ -3730,6 +4350,20 @@ window.__ModuleLoader__.load({
           },
         }, HudDockPill);
       });
+
+      // 轮尾（内置「已编辑 N 个文件」卡片所在的那条尾巴）的一扇门：本轮动过图，
+      // 点缩略图就在内置文档预览里打开；`⇄` 才进本面板看前后对比。
+      ctx.slots.inject("conversation.chat.turnTail", function () {
+        return ctx.slots.register({
+          name: "conversation.chat.turnTail",
+          id: "dsh-hud-turn-images",
+          order: 30,
+          locale: NS,
+          inject: function (sessionId) {
+            return { store: store, sessionId: sessionId };
+          },
+        }, TurnImages);
+      });
     }
 
     exports.apply = apply;

package/lib/index.js

@@ -17,6 +17,9 @@
  *   - `diff { cwd, path, origPath? }` → 一个改动文件的**两侧** unified diff
  *     （工作区 / 已暂存），已解析成带行号的 rows；未跟踪文件与 `--no-index` 对齐，
  *     文本按行截断、行数有上限，二进制只报 `binary`。
+ *   - `image { cwd, path, origPath?, side?, sha? }` → 图片改动**两侧**的字节与像素尺寸
+ *     （`kind` 为 `image` / `too-large` / `not-image` / `missing`），给二进制预览用；
+ *     单侧上限 `MAX_IMAGE_BYTES`，超限只回报字节数。
  *   - `log { cwd, count? }` → 最近提交（短 sha、作者、日期、refs、标题），条数钳制 1..50。
  *   - `commit { cwd, sha }` → 某次提交的元信息与改动清单（相对**第一个父提交**，
  *     合并提交也按第一父提交看），清单形状与 `status.changes` 一致。
@@ -916,6 +919,270 @@ export async function readCommitDiff(cwd, sha, file, origFile = null) {
   }
 }
 
+/* --------------------------------------------- 二进制预览（图片，只读） */
+
+/**
+ * 单侧图片预览的字节上限。
+ *
+ * 超限不等于"看不了这个改动"：仍然回报真实字节数，只是不把内容塞进 JSON
+ * （base64 还要再涨 1/3，RPC 体量必须有界）。
+ */
+export const MAX_IMAGE_BYTES = 4 * 1024 * 1024
+
+/** PNG 的签名（8 字节）。 */
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+/**
+ * 从**内容**而不是扩展名认图片类型（扩展名会骗人：`.png` 里放 gif 很常见）。
+ *
+ * @param buffer - 文件头若干字节。
+ * @returns MIME 字符串，认不出返回 null。
+ */
+export function sniffImageMime(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 12) return null
+  if (buffer.length >= 8 && buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return 'image/png'
+  if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) return 'image/jpeg'
+  const gif = buffer.subarray(0, 6).toString('latin1')
+  if (gif === 'GIF87a' || gif === 'GIF89a') return 'image/gif'
+  if (buffer.subarray(0, 4).toString('latin1') === 'RIFF' && buffer.subarray(8, 12).toString('latin1') === 'WEBP') return 'image/webp'
+  if (buffer.subarray(0, 2).toString('latin1') === 'BM') return 'image/bmp'
+  return null
+}
+
+/** PNG：IHDR 紧跟签名，宽高各 4 字节大端。 */
+function pngSize(buffer) {
+  if (buffer.length < 24) return null
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
+}
+
+/** GIF：逻辑屏幕描述符，宽高各 2 字节小端。 */
+function gifSize(buffer) {
+  if (buffer.length < 10) return null
+  return { width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) }
+}
+
+/**
+ * JPEG：从头扫段，找 SOFn（C0–CF，但 C4/C8/CC 不是）里的高/宽。
+ *
+ * 段长字段是**含自身两字节**的长度，所以下一段起点是 `index + 2 + length`；
+ * 填充 0xFF、TEM 与 RSTn 都没有长度字段，只前进一字节。
+ */
+function jpegSize(buffer) {
+  let index = 2
+  while (index + 9 < buffer.length) {
+    if (buffer[index] !== 0xff) {
+      index += 1
+      continue
+    }
+    const marker = buffer[index + 1]
+    if (marker === 0xff || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+      index += 1
+      continue
+    }
+    const isFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc
+    if (isFrame) return { width: buffer.readUInt16BE(index + 7), height: buffer.readUInt16BE(index + 5) }
+    const length = buffer.readUInt16BE(index + 2)
+    if (length < 2) return null
+    index += 2 + length
+  }
+  return null
+}
+
+/** WebP：VP8X 是 24 位减一、VP8（有损）内嵌 14 位、VP8L（无损）打包在 32 位里。 */
+function webpSize(buffer) {
+  if (buffer.length < 30) return null
+  const chunk = buffer.subarray(12, 16).toString('latin1')
+  if (chunk === 'VP8X') return { width: buffer.readUIntLE(24, 3) + 1, height: buffer.readUIntLE(27, 3) + 1 }
+  if (chunk === 'VP8 ' && buffer[23] === 0x9d && buffer[24] === 0x01 && buffer[25] === 0x2a) {
+    return { width: buffer.readUInt16LE(26) & 0x3fff, height: buffer.readUInt16LE(28) & 0x3fff }
+  }
+  if (chunk === 'VP8L' && buffer[20] === 0x2f) {
+    const packed = buffer.readUInt32LE(21)
+    return { width: (packed & 0x3fff) + 1, height: ((packed >> 14) & 0x3fff) + 1 }
+  }
+  return null
+}
+
+/** BMP：BITMAPINFOHEADER 的宽为有符号、高可为负（自上而下）。 */
+function bmpSize(buffer) {
+  if (buffer.length < 26) return null
+  const width = buffer.readInt32LE(18)
+  const height = buffer.readInt32LE(22)
+  if (width <= 0 || height === 0) return null
+  return { width, height: Math.abs(height) }
+}
+
+/**
+ * 读出图片的像素尺寸。纯函数，只读头部，认不出返回 `null`（绝不抛）。
+ *
+ * @param buffer - 文件内容（头部足够即可，但这里拿的是完整内容）。
+ * @param mime - `sniffImageMime` 的结果。
+ * @returns `{ width, height }` 或 null。
+ */
+export function readImageSize(buffer, mime) {
+  try {
+    if (mime === 'image/png') return pngSize(buffer)
+    if (mime === 'image/jpeg') return jpegSize(buffer)
+    if (mime === 'image/gif') return gifSize(buffer)
+    if (mime === 'image/webp') return webpSize(buffer)
+    if (mime === 'image/bmp') return bmpSize(buffer)
+    return null
+  }
+  catch {
+    return null
+  }
+}
+
+/**
+ * `runGit` 的字节版。
+ *
+ * `cat-file blob` 的输出是任意二进制，按 utf8 解码会毁掉它（非法序列变成 U+FFFD，
+ * 再编码回去就不是原文件了），所以这条路径必须单独走 buffer 编码。
+ */
+function runGitBytes(cwd, args, maxBytes) {
+  return new Promise((resolve) => {
+    execFile(
+      'git',
+      args,
+      { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: maxBytes, windowsHide: true, encoding: 'buffer' },
+      (error, stdout, stderr) => {
+        if (!error) {
+          resolve({ ok: true, stdout })
+          return
+        }
+        resolve({
+          ok: false,
+          stdout,
+          stderr: stderr ? stderr.toString('utf8') : '',
+          killed: Boolean(error.killed) || Boolean(error.signal),
+          code: typeof error.code === 'number' ? error.code : (error.code ?? null),
+          message: error instanceof Error ? error.message : String(error),
+        })
+      },
+    )
+  })
+}
+
+/** 一个 git 对象的字节数；对象不存在（新文件还没有索引副本）返回 null。 */
+async function gitBlobSize(repoRoot, spec) {
+  const result = await runGit(repoRoot, ['cat-file', '-s', spec])
+  if (!result.ok) return null
+  const size = Number.parseInt(result.stdout.trim(), 10)
+  return Number.isFinite(size) && size >= 0 ? size : null
+}
+
+/** 判断一侧的内容：能预览就带上 base64 与像素尺寸，否则只说"为什么不能"。 */
+function describeSide(buffer) {
+  const bytes = buffer.length
+  const mime = sniffImageMime(buffer)
+  if (mime === null) return { kind: 'not-image', bytes }
+  const size = readImageSize(buffer, mime)
+  return {
+    kind: 'image',
+    mime,
+    bytes,
+    width: size === null ? null : size.width,
+    height: size === null ? null : size.height,
+    base64: buffer.toString('base64'),
+  }
+}
+
+/** 读工作区里的一个文件；不是普通文件、或超过上限，都只回报状态。 */
+async function readWorktreeSide(repoRoot, file) {
+  const full = path.resolve(repoRoot, file)
+  const rootPrefix = repoRoot.endsWith(path.sep) ? repoRoot : repoRoot + path.sep
+  // validateDiffPath 已经挡掉绝对路径与 `..`；这里再确认落在仓库内（软链接不越界）。
+  if (!full.startsWith(rootPrefix)) return { kind: 'missing' }
+  let stats
+  try {
+    stats = await fs.promises.stat(full)
+  }
+  catch {
+    return { kind: 'missing' }
+  }
+  if (!stats.isFile()) return { kind: 'missing' }
+  if (stats.size > MAX_IMAGE_BYTES) return { kind: 'too-large', bytes: stats.size, limit: MAX_IMAGE_BYTES }
+  try {
+    return describeSide(await fs.promises.readFile(full))
+  }
+  catch {
+    return { kind: 'missing' }
+  }
+}
+
+/** 读一个 git 对象（`<rev>:<path>`，rev 为空串即索引）：不存在即 missing，超限只回报字节数。 */
+async function readGitSide(repoRoot, rev, file) {
+  const spec = `${rev}:${file}`
+  const size = await gitBlobSize(repoRoot, spec)
+  if (size === null) return { kind: 'missing' }
+  if (size > MAX_IMAGE_BYTES) return { kind: 'too-large', bytes: size, limit: MAX_IMAGE_BYTES }
+  const result = await runGitBytes(repoRoot, ['cat-file', 'blob', spec], MAX_IMAGE_BYTES + 64 * 1024)
+  if (!result.ok) {
+    if (result.killed) throw Object.assign(new Error('git cat-file timed out'), { code: 'timeout' })
+    return { kind: 'missing' }
+  }
+  return describeSide(result.stdout)
+}
+
+/**
+ * 读一个二进制（图片）改动的两侧字节与像素尺寸，全部只读。
+ *
+ * `side` 与文本 diff 的两枚页签一一对应，这样"未暂存 / 已暂存"在两个视图里指的是同一件事：
+ *   - `worktree`（未暂存）：基线 = 索引 `:<path>`，新 = 工作区文件；
+ *   - `index`（已暂存）：基线 = `HEAD`，新 = 索引 `:<path>`；
+ *   - 给了 `sha`（提交明细）：基线 = 第一父提交（根提交则为空），新 = 该提交。
+ *
+ * 两侧各自回答"能不能预览"：`kind` 为 `image` / `too-large` / `not-image` / `missing`。
+ * 任一侧不可预览都不算失败 —— 另一侧照样能看。
+ *
+ * @param cwd - 会话工作区（绝对路径）。
+ * @param file - 仓库内相对路径。
+ * @param origFile - 重命名/复制的原路径，可选。
+ * @param side - `'worktree'` | `'index'`，给了 sha 时忽略。
+ * @param sha - 提交 sha（提交明细用），可选。
+ * @returns `{ repo, path, origPath, side, sha, before, after }`。
+ */
+export async function readImagePair(cwd, file, origFile = null, side = 'worktree', sha = null) {
+  const base = { path: file, origPath: origFile ?? null, side: sha === null ? side : 'commit', sha }
+  const empty = { repo: null, ...base, before: { kind: 'missing' }, after: { kind: 'missing' } }
+
+  if (sha !== null) {
+    const commit = await resolveCommit(cwd, sha)
+    if (!commit.repo) return empty
+    return {
+      repo: commit.repo,
+      shortSha: commit.shortSha,
+      ...base,
+      before: commit.base === null ? { kind: 'missing' } : await readGitSide(commit.repo, commit.base, origFile ?? file),
+      after: await readGitSide(commit.repo, commit.sha, file),
+    }
+  }
+
+  const root = await runGit(cwd, ['rev-parse', '--show-toplevel'])
+  if (!root.ok) {
+    if (root.killed) throw Object.assign(new Error('git rev-parse timed out'), { code: 'timeout' })
+    if (root.code === 'ENOENT' && !fs.existsSync(cwd)) throw Object.assign(new Error('cwd does not exist'), { code: 'no-cwd' })
+    if (root.code === 'ENOENT') throw Object.assign(new Error('git executable not found'), { code: 'git-missing' })
+    return empty
+  }
+
+  const repoRoot = root.stdout.split('\n')[0].trim()
+  if (side === 'index') {
+    return {
+      repo: repoRoot,
+      ...base,
+      before: await readGitSide(repoRoot, 'HEAD', origFile ?? file),
+      after: await readGitSide(repoRoot, '', file),
+    }
+  }
+  return {
+    repo: repoRoot,
+    ...base,
+    before: await readGitSide(repoRoot, '', origFile ?? file),
+    after: await readWorktreeSide(repoRoot, file),
+  }
+}
+
 /* ------------------------------------------------- 会话改动（按会话归因） */
 
 /**
@@ -1655,6 +1922,36 @@ const ENDPOINTS = {
     return readDiff(cwd.value, file.value, origFile)
   },
 
+  /**
+   * 图片预览：一个二进制改动两侧的字节与像素尺寸。
+   *
+   * `diff` 对二进制只回一句 `binary: true`（文本 diff 里没有可看的东西），
+   * 浏览器半靠这个端点把"改了哪张图、尺寸变没变"画出来。只读，不写 index / 工作区。
+   */
+  async image(args) {
+    const input = args && typeof args === 'object' ? args : {}
+    const cwd = validateCwd(input.cwd)
+    if (!cwd.ok) throw Object.assign(new Error(cwd.message), { code: cwd.code })
+    const file = validateDiffPath(input.path)
+    if (!file.ok) throw Object.assign(new Error(file.message), { code: file.code })
+
+    let origFile = null
+    if (input.origPath !== undefined && input.origPath !== null && input.origPath !== '') {
+      const checked = validateDiffPath(input.origPath, 'origPath')
+      if (!checked.ok) throw Object.assign(new Error(checked.message), { code: checked.code })
+      origFile = checked.value
+    }
+
+    let sha = null
+    if (input.sha !== undefined && input.sha !== null && input.sha !== '') {
+      const checked = validateCommitSha(input.sha)
+      if (!checked.ok) throw Object.assign(new Error(checked.message), { code: checked.code })
+      sha = checked.value
+    }
+
+    return readImagePair(cwd.value, file.value, origFile, input.side === 'index' ? 'index' : 'worktree', sha)
+  },
+
   async log(args) {
     const input = args && typeof args === 'object' ? args : {}
     const cwd = validateCwd(input.cwd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konnga/dsh-hud",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "DeepSeek Harness 的只读工作区 Git 面板：分支、ahead/behind、改动清单与差异，外加「这个会话改过哪些文件、审到哪了、跑了什么工具」。A read-only workspace Git panel for DeepSeek Harness — branch, changed files, diffs, plus per-session change attribution, review progress, and tool activity.",
   "type": "module",
   "main": "lib/index.js",