dsh-quick-toc 0.7.14 → 0.8.1

package/CHANGELOG.en.md

@@ -2,6 +2,22 @@
 
 All notable changes to **dsh-quick-toc** are documented here. Chinese version: [CHANGELOG.md](CHANGELOG.md).
 
+## [0.8.1] - 2026-09-29
+
+### Fixed
+- **The pin on the hover preview could not be clicked**: moving from an outline row towards the card started the fade first, so the card was gone before the pin was reached. Leaving a row now only arms the close, and reaching the card cancels it.
+
+### Changed
+- **The collapsed handle took room from the text in a narrow window**: below a 760-pixel conversation column the collapsed side handle slides back into the divider; the droplet above stays as the way into the outline, and the side handle returns when the window widens.
+
+## [0.8.0] - 2026-09-29
+
+### Changed
+- **The hover preview can be pinned**: a pin button on the card keeps it on screen after the pointer moves away, and its text can be selected; click the pin again, press Escape or click elsewhere to drop it. One pinned card at a time, and it stays where it was put.
+- **Two previews side by side**: while a card is pinned, hovering another row opens a second card next to it — on whichever side has more room — so two places can be compared.
+- **A context menu on outline rows**: right-click a heading row for "Pin this preview / Unpin" and "Jump to the end of this section".
+- **Cards and menus animate in and out**: the pinned card, the hover preview and the row menu all fade in and out instead of appearing or vanishing instantly.
+
 ## [0.7.14] - 2026-09-28
 
 ### Changed

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 **dsh-quick-toc** 的重要变更都记录在这里。英文版见 [CHANGELOG.en.md](CHANGELOG.en.md)。
 
+## [0.8.1] - 2026-09-29
+
+### 修复
+- **悬停预览卡上的图钉无法点击**：鼠标从大纲行移向卡片时会先开始淡出，卡片在图钉被点到之前就已经消失。现在离开行只是预备关闭，指针落到卡片上即取消。
+
+### 变更
+- **窄窗口下折叠把手占用正文**：对话区域宽度不足 760 像素时，折叠态的侧边把手滑回分隔线内；顶部的水滴把手保留，作为打开大纲的入口，窗口变宽后侧边把手自动回来。
+
+## [0.8.0] - 2026-09-29
+
+### 变更
+- **悬停预览可以钉住**：预览卡右上角多了一个图钉，点一下把它钉在屏幕上——鼠标移开也不消失，文字可以选中；再点一次图钉、按 Esc 或点别处取消。同时只保留一张钉住的卡，钉住的位置不会再动。
+- **钉住后可以两处对照**：钉住状态下悬停别的行会同时显示第二张卡，两张不重叠——第二张放在空得多的一侧。
+- **大纲行右键菜单**：在标题行上点右键可以「钉住预览／取消钉住」或「跳到本节末尾」。
+- **卡片与菜单的收放都有动画**：钉住的卡、悬停预览和右键菜单都以淡入淡出出现和消失，不再瞬间弹出或消失。
+
 ## [0.7.14] - 2026-09-28
 
 ### 变更

package/README.en.md

@@ -42,7 +42,8 @@ A conversation TOC plugin for [DeepSeek Harness](https://github.com/deepseek-ai/
 
 | Plugin | Supported DSH |
 | --- | --- |
-| **0.7.x** (latest, 0.7.13) | 0.1.5-rc.3, 0.1.7-alpha.1, 0.1.7-alpha.2, 0.1.7-rc.1, 0.1.7-rc.2, 0.2.0-rc.1 |
+| **0.8.x** (latest, 0.8.1) | 0.1.5-rc.3, 0.1.7-alpha.1, 0.1.7-alpha.2, 0.1.7-rc.1, 0.1.7-rc.2, 0.2.0-rc.1 |
+| 0.7.x (0.7.14) | 0.1.5-rc.3, 0.1.7-alpha.1, 0.1.7-alpha.2, 0.1.7-rc.1, 0.1.7-rc.2, 0.2.0-rc.1 |
 | 0.6.x (0.6.3) | 0.1.5-rc.1, 0.1.5-rc.2 |
 | 0.5.x (0.5.1) | 0.1.5-rc.1, 0.1.5-rc.2 |
 | 0.4.x (0.4.1) | 0.1.5-rc.1, 0.1.5-rc.2 |

package/README.md

@@ -42,7 +42,8 @@
 
 | 插件版本 | 支持的 DSH 版本 |
 | --- | --- |
-| **0.7.x**（最新，0.7.13） | 0.1.5-rc.3、0.1.7-alpha.1、0.1.7-alpha.2、0.1.7-rc.1、0.1.7-rc.2、0.2.0-rc.1 |
+| **0.8.x**（最新，0.8.1） | 0.1.5-rc.3、0.1.7-alpha.1、0.1.7-alpha.2、0.1.7-rc.1、0.1.7-rc.2、0.2.0-rc.1 |
+| 0.7.x（0.7.14） | 0.1.5-rc.3、0.1.7-alpha.1、0.1.7-alpha.2、0.1.7-rc.1、0.1.7-rc.2、0.2.0-rc.1 |
 | 0.6.x（0.6.3） | 0.1.5-rc.1、0.1.5-rc.2 |
 | 0.5.x（0.5.1） | 0.1.5-rc.1、0.1.5-rc.2 |
 | 0.4.x（0.4.1） | 0.1.5-rc.1、0.1.5-rc.2 |

package/lib/client.js

@@ -44,6 +44,11 @@ window.__ModuleLoader__.load({
     var Z_PANEL = 14;  // the docked panel
     var Z_SHEET = 16;  // the curtain, which replaces the docked panel while it is up
     var Z_HOVER = 18;  // hover preview card: above both, still inside the free band
+    // A narrow conversation column has no room for a handle floating over the text: below
+    // NARROW_CONV_W the collapsed-panel handle slides back into the divider (its usual
+    // motion) while the droplet above the conversation stays as the way in. Nothing opens
+    // by itself — a resize never overrides the reader's own choice of surface.
+    var NARROW_CONV_W = 760;
     var Z_ERROR = 32;  // crash banner: above our layers and the app's chrome, below
                        // DSH's popovers (100) and modals (1000)
     var EASE = "cubic-bezier(0.22, 0.9, 0.3, 1)"; // smooth non-linear slide
@@ -148,6 +153,11 @@ window.__ModuleLoader__.load({
         "time.yesterday": "昨天",
         "time.beforeYesterday": "前天",
         "preview.truncated": "预览由宿主提供，可能被截断",
+        "preview.pin": "钉住预览",
+        "preview.unpin": "取消钉住",
+        "menu.pin": "钉住预览",
+        "menu.unpin": "取消钉住",
+        "menu.end": "跳到本节末尾",
         "resize.w": "拖拽调整宽度",
         "resize.h": "拖拽调整高度",
         "resize.wh": "拖拽同时调整宽高",
@@ -246,6 +256,11 @@ window.__ModuleLoader__.load({
         // carries the numeric date. Yesterday itself reads as the word in both.
         "time.yesterday": "yesterday",
         "preview.truncated": "Preview comes from the host and may be truncated",
+        "preview.pin": "Pin this preview",
+        "preview.unpin": "Unpin",
+        "menu.pin": "Pin this preview",
+        "menu.unpin": "Unpin this preview",
+        "menu.end": "Jump to the end of this section",
         "resize.w": "Drag to resize the width",
         "resize.h": "Drag to resize the height",
         "resize.wh": "Drag to resize width and height",
@@ -1564,6 +1579,10 @@ window.__ModuleLoader__.load({
       var _s2 = react.useState(null);
       var viewport = _s2[0];
       var setViewport = _s2[1];
+      // how much room the conversation column itself has (the thing a docked panel
+      // squeezes); 0 while it has not been measured yet, which never counts as narrow
+      var convWidth = viewport ? Math.max(0, window.innerWidth - viewport.left - viewport.right) : 0;
+      var narrowWindow = convWidth > 0 && convWidth < NARROW_CONV_W;
       react.useEffect(function () {
         // Self-healing, because the layout AROUND the conversation can change without
         // a resize: the host's own controls move that column about (measured in a real
@@ -1808,7 +1827,7 @@ window.__ModuleLoader__.load({
       var scrollToBottom = function (e) {
         if (e && e.stopPropagation) e.stopPropagation();
         outlineTouchRef.current = Date.now();
-        hoverEnd();
+        hoverEnd(true);
         var el = listRef.current;
         if (!el) return;
         // optimistic: the list is on its way to the newest row, so the button starts
@@ -1894,7 +1913,7 @@ window.__ModuleLoader__.load({
       var backToBrowse = function (e) {
         if (e && e.stopPropagation) e.stopPropagation();
         outlineTouchRef.current = Date.now();
-        hoverEnd();
+        hoverEnd(true);
         var el = listRef.current;
         var tgt = liveTgt();
         if (!el || !tgt) return;
@@ -1960,6 +1979,17 @@ window.__ModuleLoader__.load({
       var setHoverClosing = _sHovOut[1];
       var hoverTimerRef = react.useRef(null);
       var hoverCloseTimerRef = react.useRef(null);
+      // The card carries the pin button, so the pointer has to be able to travel from the
+      // row onto the card without the card fading on the way. Leaving a row therefore only
+      // ARMS the close; the card's own mouseenter disarms it, and the fade starts after a
+      // grace period that a crossing pointer fits into.
+      var HOVER_GRACE_MS = 260;
+      var hoverGraceTimerRef = react.useRef(null);
+      var disarmHoverClose = function () {
+        if (hoverGraceTimerRef.current) { clearTimeout(hoverGraceTimerRef.current); hoverGraceTimerRef.current = null; }
+        if (hoverCloseTimerRef.current) { clearTimeout(hoverCloseTimerRef.current); hoverCloseTimerRef.current = null; }
+        setHoverClosing(false);
+      };
       var hoverStart = function (info, el) {
         // the hover card is a preference: off means it never opens (the outline rows
         // themselves keep their hover tint)
@@ -1968,11 +1998,7 @@ window.__ModuleLoader__.load({
         hoverTimerRef.current = setTimeout(function () {
           var r = el && el.getBoundingClientRect ? el.getBoundingClientRect() : null;
           if (!r || r.width <= 0) return;
-          if (hoverCloseTimerRef.current) {
-            clearTimeout(hoverCloseTimerRef.current);
-            hoverCloseTimerRef.current = null;
-          }
-          setHoverClosing(false);
+          disarmHoverClose();
           setHoverCard({
             title: info.title,
             sub: info.sub,
@@ -1981,21 +2007,177 @@ window.__ModuleLoader__.load({
             ghost: info.ghost,
             top: r.top,
             left: r.left,
-            right: r.right
+            right: r.right,
+            // the row this card describes: pinning keeps it, and the menu labels itself from it
+            key: info.key,
+            idx: info.idx
           });
         }, 260);
       };
-      // leaving fades the card out instead of dropping it on the next frame
-      var hoverEnd = function () {
+      // leaving fades the card out instead of dropping it on the next frame — but only
+      // after a grace period, because the card carries the pin and the pointer has to be
+      // able to travel from the row onto it (an immediate fade made the pin unreachable).
+      var hoverEnd = function (immediate) {
         if (hoverTimerRef.current) clearTimeout(hoverTimerRef.current);
+        if (hoverGraceTimerRef.current) clearTimeout(hoverGraceTimerRef.current);
         if (hoverCloseTimerRef.current) clearTimeout(hoverCloseTimerRef.current);
-        setHoverClosing(true);
-        hoverCloseTimerRef.current = setTimeout(function () {
-          hoverCloseTimerRef.current = null;
-          setHoverCard(null);
-          setHoverClosing(false);
-        }, 240);
+        var grace = immediate ? 0 : HOVER_GRACE_MS;
+        hoverGraceTimerRef.current = setTimeout(function () {
+          hoverGraceTimerRef.current = null;
+          setHoverClosing(true);
+          hoverCloseTimerRef.current = setTimeout(function () {
+            hoverCloseTimerRef.current = null;
+            setHoverCard(null);
+            setHoverClosing(false);
+          }, 240);
+        }, grace);
+      };
+
+      // ---- pinned preview + the row menu (0.8.0) --------------------------------
+      // Pinning freezes one card where it is, so the pointer can move on and a second
+      // row can be hovered next to it: two previews read side by side. One pin at a
+      // time — pinning another row replaces it (the newest pin is the one that stays).
+      var _sPin = react.useState(null);
+      var pinnedCard = _sPin[0];
+      var setPinnedCard = _sPin[1];
+      var pinFromCard = function (card, opts) {
+        if (!card) return;
+        if (pinCloseTimerRef.current) { clearTimeout(pinCloseTimerRef.current); pinCloseTimerRef.current = null; }
+        setPinnedClosing(false);
+        setPinnedCard({
+          title: card.title,
+          sub: card.sub,
+          preview: card.preview,
+          meta: card.meta,
+          ghost: card.ghost,
+          key: card.key,
+          top: card.top,
+          left: card.left,
+          right: card.right,
+          // adopting the card that is already on screen must not re-play its entrance
+          // animation, or pinning would blink the very card the reader is looking at
+          fresh: !!(opts && opts.fresh)
+        });
+        // the card the reader is looking at BECOMES the pinned one: the hover card is
+        // dropped in the same frame, so pinning never moves what is on screen
+        if (hoverCloseTimerRef.current) { clearTimeout(hoverCloseTimerRef.current); hoverCloseTimerRef.current = null; }
+        setHoverClosing(false);
+        setHoverCard(null);
       };
+      // The pinned card STAYS where it was put: scrolling the outline leaves it alone.
+      // Dropping it runs the same fade the hover card uses, so nothing ever pops out.
+      var _sPinClose = react.useState(false);
+      var pinnedClosing = _sPinClose[0];
+      var setPinnedClosing = _sPinClose[1];
+      var pinCloseTimerRef = react.useRef(null);
+      var unpinCard = function () {
+        if (!pinnedCard || pinCloseTimerRef.current) return;
+        setPinnedClosing(true);
+        pinCloseTimerRef.current = setTimeout(function () {
+          pinCloseTimerRef.current = null;
+          setPinnedCard(null);
+          setPinnedClosing(false);
+        }, 180);
+      };
+      // the pinned card measures itself so the second card can be placed against it
+      var pinnedRef = react.useRef(null);
+      // the card keeps the row it describes, so the menu can say pin/unpin for it
+      var isPinned = function (key) { return !!pinnedCard && !!key && pinnedCard.key === key; };
+
+      // A right-click on an outline row opens a small menu instead of the browser's:
+      // pin/unpin this row's preview and jump to the end of its section.
+      var _sMenu = react.useState(null);
+      var rowMenu = _sMenu[0];
+      var setRowMenu = _sMenu[1];
+      // the menu closes through a short fade like every other card
+      var _sMenuClose = react.useState(false);
+      var menuClosing = _sMenuClose[0];
+      var setMenuClosing = _sMenuClose[1];
+      var menuCloseTimerRef = react.useRef(null);
+      var openRowMenu = function (e, info, key, idx) {
+        if (e && e.preventDefault) e.preventDefault();
+        if (e && e.stopPropagation) e.stopPropagation();
+        var x = e && typeof e.clientX === "number" ? e.clientX : 0;
+        var y = e && typeof e.clientY === "number" ? e.clientY : 0;
+        if (menuCloseTimerRef.current) { clearTimeout(menuCloseTimerRef.current); menuCloseTimerRef.current = null; }
+        setMenuClosing(false);
+        // pinning from the menu puts the card where the row is, not under the pointer
+        var rect = e && e.currentTarget && e.currentTarget.getBoundingClientRect ? e.currentTarget.getBoundingClientRect() : null;
+        setRowMenu({
+          x: x,
+          y: y,
+          info: info,
+          key: key,
+          idx: idx,
+          rowTop: rect ? rect.top : undefined,
+          rowLeft: rect ? rect.left : undefined,
+          rowRight: rect ? rect.right : undefined
+        });
+      };
+      var closeRowMenu = function () {
+        if (!rowMenu || menuCloseTimerRef.current) return;
+        setMenuClosing(true);
+        menuCloseTimerRef.current = setTimeout(function () {
+          menuCloseTimerRef.current = null;
+          setRowMenu(null);
+          setMenuClosing(false);
+        }, 150);
+      };
+      // Esc / a click anywhere else closes the menu and drops the pin; a pinned card
+      // also goes away when the panel closes or the surface switches (below).
+      // The listeners are bound ONCE and read the live state through a ref: when they were
+      // re-bound on every state change the registered closure ran one step behind (Esc
+      // closed the menu a second time and never reached the pin).
+      var latestPin = react.useRef({});
+      latestPin.current = {
+        pinned: !!pinnedCard,
+        menu: !!rowMenu,
+        unpin: unpinCard,
+        closeMenu: closeRowMenu
+      };
+      react.useEffect(function () {
+        var onDown = function (ev) {
+          var L = latestPin.current;
+          if (!L.pinned && !L.menu) return;
+          // a right-click is how the row menu opens: it must not drop the pin the reader
+          // is comparing against
+          if (ev.button === 2) return;
+          var t = ev.target;
+          if (t && t.closest && (t.closest("[data-dqt-pin]") || t.closest("[data-dqt-menu]"))) return;
+          L.closeMenu();
+          if (L.pinned && t && t.closest && t.closest("[data-dqt-pinned]")) return;
+          L.unpin();
+        };
+        var onKey = function (ev) {
+          var L = latestPin.current;
+          if (ev.key !== "Escape") return;
+          // Esc takes the menu first, then the pin; only when neither is up does it
+          // reach the panel's own handler and close the panel.
+          if (L.menu) { L.closeMenu(); ev.stopPropagation(); ev.preventDefault(); return; }
+          if (L.pinned) { L.unpin(); ev.stopPropagation(); ev.preventDefault(); }
+        };
+        document.addEventListener("mousedown", onDown, true);
+        document.addEventListener("keydown", onKey, true);
+        return function () {
+          document.removeEventListener("mousedown", onDown, true);
+          document.removeEventListener("keydown", onKey, true);
+        };
+      }, []);
+      // a pinned card belongs to the surface it was pinned on: closing the panel or
+      // switching between the panel and the curtain drops it (through the same fade).
+      // These act on the TRANSITION only — a plain re-run must never touch a live pin.
+      var wasOpenRef = react.useRef(open);
+      react.useEffect(function () {
+        if (wasOpenRef.current === open) return;
+        wasOpenRef.current = open;
+        if (!open) unpinCard();
+      }, [open]);
+      var wasSheetRef = react.useRef(sheetOpen);
+      react.useEffect(function () {
+        if (wasSheetRef.current === sheetOpen) return;
+        wasSheetRef.current = sheetOpen;
+        unpinCard();
+      }, [sheetOpen]);
 
       // ---- the outline belongs to the CHAT view only: when the center column
       // switches to another view (trajectory / context / plugin views), fade the
@@ -2969,7 +3151,7 @@ window.__ModuleLoader__.load({
         autoGestureRef.current = Date.now();   // a wheel tick is a reader gesture
         var el = listRef.current;
         if (!el) return;
-        hoverEnd();
+        hoverEnd(true);
         if (e.deltaY >= 0) {
           // still scrolling down at the very end of the outline: say so. Outline
           // mode only — the search list has its own persistent hint line.
@@ -3006,7 +3188,7 @@ window.__ModuleLoader__.load({
         var upward = el.scrollTop < lastScrollTopRef.current - 2;
         if (upward) {
           if (hint === "more") setHint("");
-          if (hoverCard) hoverEnd();
+          if (hoverCard) hoverEnd(true);
         }
         lastScrollTopRef.current = el.scrollTop;
         syncBackBtn(el);   // reached the remembered place by hand? the button is done
@@ -4747,6 +4929,8 @@ window.__ModuleLoader__.load({
         onOpenTurn: openTurn,
         hoverStart: hoverStart,
         hoverEnd: hoverEnd,
+        // right-click on a row: pin its preview / jump to the end of its section
+        rowMenu: openRowMenu,
         // the curtain is wide: rows switch to a one-line, multi-part layout that
         // puts the section's opening text out to the right instead of under the
         // title (see renderItem / renderResultRow)
@@ -6009,7 +6193,10 @@ window.__ModuleLoader__.load({
       // vanishing ON the divider line. `open` also drives it (fade + slide home) and
       // `edgeGone` keeps the element in the tree until that motion has played.
       var EDGE_W = 26;
-      var edgeShown = !open && handleShown && chatViewActive;
+      // a narrow conversation column leaves no room for a handle floating over the text:
+      // below the threshold it slides back into the divider (its usual motion), while the
+      // droplet above the conversation stays put as the way in
+      var edgeShown = !open && handleShown && chatViewActive && !narrowWindow;
       var edgeLineLeft = viewport ? viewport.left : 0;
       var edgeLineRight = viewport ? viewport.right + 52 : 60;   // clear of the milestone rail
       var edgeEl = (!open || !edgeGone) ? react_jsx_runtime.jsx("div", {
@@ -6197,42 +6384,110 @@ window.__ModuleLoader__.load({
       // Rendered INSIDE the body portal (position: fixed) so the outline's own
       // scroll container can never clip it, and pointer-events: none so it can
       // never steal the hover that opened it.
-      var hoverEl = null;
-      if (hoverCard && open) {
+      // One card body, used for both the hover card and the pinned one: same width,
+      // same fields, same layering. `opts.pinned` turns it into the frozen copy (it
+      // takes pointer events, so its text can be selected and its pin can be clicked);
+      // the hover card stays click-through except for its pin button.
+      var renderPreviewCard = function (card, opts) {
         var cardW = 264;
-        var cardTop = Math.max(8, Math.min(hoverCard.top - 4, window.innerHeight - 210));
-        var cardLeft = dockRight
-          ? Math.max(8, hoverCard.left - cardW - 10)
-          : Math.min(window.innerWidth - cardW - 8, hoverCard.right + 10);
-        var cardBody = hoverCard.preview || hoverCard.sub || "";
-        var cardChildren = [
+        var top = Math.max(8, Math.min(card.top - 4, window.innerHeight - 210));
+        var left = dockRight
+          ? Math.max(8, card.left - cardW - 10)
+          : Math.min(window.innerWidth - cardW - 8, card.right + 10);
+        // With a card already pinned, a second one on the same band would cover it: put
+        // the hover card on whichever side of the pinned card has more room (measured,
+        // so a short pinned card does not push the second one further than needed).
+        if (!opts.pinned && pinnedCard && pinnedVisible && !pinnedClosing) {
+          var pinRect = pinnedRef.current && pinnedRef.current.getBoundingClientRect ? pinnedRef.current.getBoundingClientRect() : null;
+          var pinTop = pinRect && pinRect.height > 0 ? pinRect.top : Math.max(8, Math.min(pinnedCard.top - 4, window.innerHeight - 210));
+          var pinH = pinRect && pinRect.height > 0 ? pinRect.height : 210;
+          var pinLeft = pinRect && pinRect.width > 0
+            ? pinRect.left
+            : (dockRight ? Math.max(8, pinnedCard.left - cardW - 10) : Math.min(window.innerWidth - cardW - 8, pinnedCard.right + 10));
+          var overlaps = Math.abs(pinLeft - left) < cardW && top < pinTop + pinH + 6 && pinTop < top + 210 + 6;
+          if (overlaps) {
+            var belowRoom = window.innerHeight - 8 - (pinTop + pinH + 8);
+            var aboveRoom = pinTop - 8 - 8;
+            top = belowRoom >= aboveRoom
+              ? Math.max(8, Math.min(pinTop + pinH + 8, window.innerHeight - 210 - 8))
+              : Math.max(8, pinTop - 210 - 8);
+          }
+        }
+        var body = card.preview || card.sub || "";
+        var kids = [
           react_jsx_runtime.jsx("div", {
-            style: { fontSize: 12, fontWeight: 600, color: C.text, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" },
-            children: hoverCard.title
-          }, "hc-t")
+            style: { display: "flex", alignItems: "flex-start", gap: 6 },
+            children: [
+              react_jsx_runtime.jsx("div", {
+                style: { flex: "1 1 auto", minWidth: 0, fontSize: 12, fontWeight: 600, color: C.text, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" },
+                children: card.title
+              }, "hc-t"),
+              react_jsx_runtime.jsx("button", {
+                "data-dqt-pin": opts.pinned ? "on" : "off",
+                title: opts.pinned ? T("preview.unpin") : T("preview.pin"),
+                onClick: function (e) {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  if (opts.pinned) unpinCard();
+                  else pinFromCard(card);
+                },
+                style: {
+                  flex: "none",
+                  width: 20,
+                  height: 20,
+                  marginTop: -2,
+                  marginRight: -4,
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  border: "none",
+                  borderRadius: 6,
+                  background: opts.pinned ? C.hover : "transparent",
+                  color: opts.pinned ? C.text : C.muted,
+                  cursor: "pointer",
+                  // the hover card is click-through except for this button, so reaching
+                  // for it does not depend on the row staying hovered
+                  pointerEvents: "auto",
+                  padding: 0,
+                  fontSize: 11,
+                  lineHeight: "20px"
+                },
+                children: opts.pinned ? "\u25c9" : "\u25cb"
+              }, "hc-pin")
+            ]
+          }, "hc-head")
         ];
-        if (hoverCard.meta) {
-          cardChildren.push(react_jsx_runtime.jsx("div", {
+        if (card.meta) {
+          kids.push(react_jsx_runtime.jsx("div", {
             style: { fontSize: 10, color: C.muted, opacity: 0.8, marginTop: 2, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" },
-            children: hoverCard.meta
+            children: card.meta
           }, "hc-m"));
         }
-        cardChildren.push(react_jsx_runtime.jsx("div", {
+        kids.push(react_jsx_runtime.jsx("div", {
           style: { fontSize: 11, lineHeight: "16px", color: C.text, opacity: 0.9, marginTop: 4, maxHeight: 116, overflow: "hidden" },
-          children: cardBody || (hoverCard.ghost ? T("turn.loadTip") : "")
+          children: body || (card.ghost ? T("turn.loadTip") : "")
         }, "hc-b"));
-        if (hoverCard.ghost) {
-          cardChildren.push(react_jsx_runtime.jsx("div", {
+        if (card.ghost) {
+          kids.push(react_jsx_runtime.jsx("div", {
             style: { fontSize: 10, color: C.muted, opacity: 0.7, marginTop: 4 },
             children: T("preview.truncated")
           }, "hc-n"));
         }
-        hoverEl = react_jsx_runtime.jsx("div", {
-          className: "dqt-hover" + (hoverClosing ? " dqt-hover-closing" : ""),
+        return react_jsx_runtime.jsx("div", {
+          className: "dqt-hover" + (opts.closing ? " dqt-hover-closing" : "") + (opts.pinned ? " dqt-hover-pinned" : "")
+            // a card adopted from the hover card is already on screen: skip its entrance
+            + (opts.pinned && !card.fresh ? " dqt-hover-static" : ""),
+          "data-dqt-pinned": opts.pinned ? "on" : undefined,
+          ref: opts.pinned ? pinnedRef : undefined,
+          onMouseEnter: opts.pinned ? undefined : function () {
+            // the pointer reached the card: keep it open so its pin can be clicked
+            disarmHoverClose();
+          },
+          onMouseLeave: opts.pinned ? undefined : function () { hoverEnd(); },
           style: {
             position: "fixed",
-            top: cardTop,
-            left: cardLeft,
+            top: top,
+            left: left,
             width: cardW,
             padding: "8px 10px",
             borderRadius: 8,
@@ -6243,11 +6498,107 @@ window.__ModuleLoader__.load({
             boxShadow: "0 8px 24px rgba(0,0,0,0.28)",
             // above the panel and the curtain — it is a sibling of both in this
             // portal, and both sit below it in the layer band we claim
-            zIndex: Z_HOVER,
-            pointerEvents: "none"
+            zIndex: Z_HOVER + (opts.pinned ? 1 : 0),
+            // a fading card is inert: it must not swallow the click that dismissed it.
+            // While it is up the card IS clickable — it carries the pin, and the pointer
+            // has to be able to get there from the row.
+            pointerEvents: opts.closing ? "none" : "auto",
+            userSelect: opts.pinned ? "text" : "none"
+          },
+          children: kids
+        }, opts.pinned ? "pinned-card" : "hover-card");
+      };
+
+      // The pinned card is FROZEN where it was put: scrolling the outline leaves it alone,
+      // and it only leaves the screen through the same fade the hover card uses.
+      var pinnedVisible = !!(pinnedCard && open);
+      var pinnedEl = pinnedVisible
+        ? renderPreviewCard(pinnedCard, { pinned: true, closing: pinnedClosing })
+        : null;
+      var hoverEl = null;
+      if (hoverCard && open) hoverEl = renderPreviewCard(hoverCard, { pinned: false, closing: hoverClosing });
+
+      // ---- the row menu ---------------------------------------------------------
+      // Small, fixed-position, keyboard-reachable: ↑/↓ move, Enter runs, Esc closes.
+      var rowMenuEl = null;
+      if (rowMenu && open) {
+        var menuW = 208;
+        var menuH = 76;
+        var menuLeft = Math.max(8, Math.min(rowMenu.x, window.innerWidth - menuW - 8));
+        var menuTop = Math.max(8, Math.min(rowMenu.y, window.innerHeight - menuH - 8));
+        var menuItems = [
+          {
+            id: "pin",
+            label: isPinned(rowMenu.key) ? T("menu.unpin") : T("menu.pin"),
+            run: function () {
+              if (isPinned(rowMenu.key)) unpinCard();
+              else pinFromCard({
+                title: rowMenu.info.title,
+                sub: rowMenu.info.sub,
+                preview: rowMenu.info.preview,
+                meta: rowMenu.info.meta,
+                ghost: rowMenu.info.ghost,
+                key: rowMenu.key,
+                // pin it where its ROW is, not where the right-click landed
+                top: rowMenu.rowTop !== undefined ? rowMenu.rowTop : rowMenu.y,
+                left: rowMenu.rowLeft !== undefined ? rowMenu.rowLeft : rowMenu.x,
+                right: rowMenu.rowRight !== undefined ? rowMenu.rowRight : rowMenu.x
+              }, { fresh: true });
+              closeRowMenu();
+            }
+          },
+          {
+            id: "end",
+            label: T("menu.end"),
+            run: function () {
+              var key = rowMenu.key;
+              var idx = rowMenu.idx;
+              closeRowMenu();
+              if (typeof endJumpRow === "function") endJumpRow(key, idx === undefined ? 0 : idx);
+            }
+          }
+        ];
+        rowMenuEl = react_jsx_runtime.jsx("div", {
+          "data-dqt-menu": "on",
+          className: "dqt-rowmenu" + (menuClosing ? " dqt-rowmenu-closing" : ""),
+          role: "menu",
+          style: {
+            position: "fixed",
+            top: menuTop,
+            left: menuLeft,
+            width: menuW,
+            padding: 4,
+            borderRadius: 8,
+            background: C.panelBg,
+            color: C.text,
+            border: "1px solid " + C.panelBorder,
+            boxShadow: "0 10px 28px rgba(0,0,0,0.32)",
+            zIndex: Z_HOVER + 2,
+            // a fading menu must not swallow the click that dismissed it
+            pointerEvents: menuClosing ? "none" : "auto"
           },
-          children: cardChildren
-        }, "hover-card");
+          children: menuItems.map(function (item) {
+            return react_jsx_runtime.jsx("button", {
+              role: "menuitem",
+              "data-dqt-menu-item": item.id,
+              onClick: function (e) { e.preventDefault(); e.stopPropagation(); item.run(); },
+              style: {
+                display: "block",
+                width: "100%",
+                textAlign: "left",
+                padding: "6px 8px",
+                border: "none",
+                borderRadius: 6,
+                background: "transparent",
+                color: C.text,
+                cursor: "pointer",
+                fontSize: 12,
+                lineHeight: "18px"
+              },
+              children: item.label
+            }, "menu-" + item.id);
+          })
+        }, "row-menu");
       }
 
       // ---- the curtain shell ---------------------------------------------------
@@ -6333,7 +6684,7 @@ window.__ModuleLoader__.load({
 
       return react_dom.createPortal(
         react_jsx_runtime.jsx(ErrorBoundary, {
-          children: [sheetShellEl, edgeEl, topHandleEl, hoverEl]
+          children: [sheetShellEl, edgeEl, topHandleEl, pinnedEl, hoverEl, rowMenuEl]
         }),
         document.body
       );
@@ -6419,7 +6770,10 @@ window.__ModuleLoader__.load({
         sub: n.sub || "",
         preview: n.preview || "",
         meta: [n.time, path ? path.path : ""].filter(Boolean).join("  ·  "),
-        ghost: false
+        ghost: false,
+        // what pinning and the row menu need to act on this very row
+        key: n.key,
+        idx: n.idx
       };
       var rows;
       if (wide) {
@@ -6520,6 +6874,9 @@ window.__ModuleLoader__.load({
             if (b) b.style.opacity = "0";
             if (extra && extra.hoverEnd) extra.hoverEnd();
           },
+          onContextMenu: function (e) {
+            if (extra && extra.rowMenu) extra.rowMenu(e, hoverInfo, n.key, n.idx);
+          },
           "data-jump-key": n.key,
           "data-jump-idx": n.idx !== undefined ? String(n.idx) : "0",
           // keyboard navigation walks the ORDER of these rows inside the list
@@ -7646,9 +8003,17 @@ window.__ModuleLoader__.load({
         // re-renders (which rewrite inline styles) cannot restart or cancel them
         ".dqt-levels-pop{animation:dqt-pop-in 0.22s cubic-bezier(0.22, 0.9, 0.3, 1) both;will-change:transform,opacity}" +
         // hover preview card: fades in place, and fades OUT when the pointer
-        // leaves (both as stylesheet classes so re-renders cannot cancel them)
+        // leaves (both as stylesheet classes so re-renders cannot cancel them).
+        // The pinned card wears the same two classes, so pinning, unpinning, Esc, a
+        // click outside and a panel close all animate; `.dqt-hover-static` is for the
+        // card that is ADOPTED from the hover card (it is already on screen, so it must
+        // not re-play the entrance and blink).
         ".dqt-hover{animation:dqt-fade-in 0.12s linear both}" +
-        ".dqt-hover-closing{animation:dqt-fade-out 0.16s cubic-bezier(0.2, 0.9, 0.3, 1) both}" +
+        ".dqt-hover-static{animation:none}" +
+        ".dqt-hover-closing{animation:dqt-fade-out 0.16s cubic-bezier(0.2, 0.9, 0.3, 1) both;pointer-events:none}" +
+        // the outline row menu: same vocabulary as the level picker (a small pop)
+        ".dqt-rowmenu{animation:dqt-pop-in 0.14s cubic-bezier(0.22, 0.9, 0.3, 1) both;will-change:transform,opacity}" +
+        ".dqt-rowmenu-closing{animation:dqt-pop-out 0.14s cubic-bezier(0.2, 0.9, 0.3, 1) both;pointer-events:none;will-change:transform,opacity}" +
         // transient edge banner over the bottom of the outline list
         "@keyframes dqt-toast-in{from{opacity:0;transform:translateY(5px)}to{opacity:1;transform:none}}" +
         "@keyframes dqt-toast-out{from{opacity:1;transform:none}to{opacity:0;transform:none}}" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-quick-toc",
-  "version": "0.7.14",
+  "version": "0.8.1",
   "description": "Conversation TOC for DeepSeek Harness (DSH): a whole-session, turn-grouped Markdown outline with hover previews, a level filter, a full-width curtain, jump-to-end buttons, title/full-text/cross-session search and a Chinese/English interface.",
   "type": "module",
   "main": "lib/index.js",