dsh-quick-toc 0.2.0-beta → 0.3.0

package/README.en.md

@@ -2,18 +2,28 @@
 
 > **English** | [中文](README.md)
 
-A quick conversation TOC plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): extracts Markdown headings (H1–H6) from AI replies into a navigable outline panel, grouped by conversation turn, with auto-follow highlighting.
+A quick conversation TOC plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): extracts Markdown headings (H1–H6) from AI replies into a navigable outline panel, grouped by conversation turn, with auto-follow highlighting, keyword search and in-chat match highlighting.
 
 ## Features
 
-- **Turn-grouped outline** — each user message + its AI replies form one group, with the group's end time as the header
+- **Turn-grouped outline** — each user message + its AI replies form one group, with the group's end time as the header (plus the turn's first-line preview; click it to jump to the turn start)
+- **Keyword search** — a magnifier in the header opens the search box; Enter cycles matches (n/N counter), Esc closes; toggle between **title / full-text** scope
+- **In-chat highlighting** — matched keywords are highlighted in the conversation; the current match gets a distinct highlight and is scrolled to the upper-middle of the viewport; every occurrence counts toward n/N
 - **Auto-follow highlight** — as you scroll the conversation, the turns visible in the viewport light up in the outline (multiple at once); the outline auto-loads and scrolls to keep them visible
 - **Smooth jump** — click a heading to glide to the exact heading position in the conversation
 - **Dockable & resizable** — dock left or right (drag the top bar), resize from the edges/corner, collapse to a draggable edge handle; panel size/position remembered
-- **Scrollbar follows the dock** — scrollbar sits on the left when docked left, right when docked right
 - **Paged rendering** — shows the latest groups first; scrolling to the top of the outline loads older ones
 - **Markdown-aware titles** — inline `**bold**`, *italic*, `` `code` ``, `[links](url)`, `~~strike~~` are stripped from heading text
-- Auto-hides when the conversation has no headings; works in light/dark themes
+- Auto-hides when the conversation has no headings; works in light/dark themes; the inner-shadow card look adapts to the theme (white bevel in dark)
+
+## Compatibility
+
+| Plugin | DSH |
+| --- | --- |
+| **0.3.0** | **≥ 0.1.2-rc.1** (new slot architecture) |
+| 0.2.2 | DSH versions before 0.1.2-rc.1 |
+
+0.3.0 re-targeted the host integration (new slot architecture + `useChat` session data) and **only supports DSH 0.1.2-rc.1 and above**; for older DSH builds install 0.2.2. On install/update the DSH market pre-flights host compatibility from `dsh.compatibility.dshReleases` and `peerDependencies` in package.json and warns on a mismatch.
 
 ## Install
 
@@ -47,9 +57,10 @@ Restart DSH (double-click `restart-dsh.bat` on Windows) and open the Web UI. The
 ## Development
 
 - `lib/client.js` — all UI logic (browser side)
-- `lib/index.js` — host-side no-op entry
+- `lib/index.js` — host-side no-op entry (extend with a version gate if needed)
 - `cordis.patch.yml` — loader patch (official DSH bundle format)
-- Client changes hot-load after a browser hard refresh; loader/patch changes need a DSH restart
+- **Since 0.3.0 the plugin targets the new plugin model**: the panel registers into the session-scoped `conversation.input.overlay` slot (session hooks are contributed via `ctx.uiSession.provide`, `useChat` by ui-chat), and the panel body `createPortal`s to `document.body` as a fixed floating dock; data comes from `props.useChat` (`ChatSnapshot.order` + `nodes`; node shape: `kind: user/assistant-step`, `location.turn`, `data.blocks`)
+- Client changes need a DSH restart (boot rev is content-based)
 
 ## License
 

package/README.md

@@ -2,18 +2,28 @@
 
 > [English](README.en.md) | **中文**
 
-**DeepSeek Harness（DSH）对话大纲插件**：把 AI 回复中的 Markdown 标题（H1–H6）提取成可导航的大纲面板，按对话回合分组，自动跟随阅读位置。
+**DeepSeek Harness（DSH）对话大纲插件**：把 AI 回复中的 Markdown 标题（H1–H6）提取成可导航的大纲面板，按对话回合分组，自动跟随阅读位置，支持关键字搜索与对话内高亮定位。
 
 ## 功能
 
-- **按回合分组** —— 每条用户消息 + 其后续 AI 回复为一组，组头显示该组最后一条消息的结束时间
+- **按回合分组** —— 每条用户消息 + 其后续 AI 回复为一组，组头显示该组最后一条消息的结束时间（附带该回合首行预览，点击可跳到回合开头）
+- **关键字搜索** —— 标题栏放大镜打开搜索框，回车逐个定位（n/N 计数），Esc 关闭；支持 **标题 / 全文** 范围切换
+- **对话内高亮** —— 命中关键字在对话中高亮，当前命中单独标亮并滚动到视口上方约 1/3 处；同一条消息内的多次命中都计入 n/N
 - **自动跟随高亮** —— 滚动对话框时，视口内可见的回合在大纲中自动点亮（多组可同时点亮）；大纲自动加载并滚动，保证正在读的组始终可见
 - **平滑跳转** —— 点击标题平滑滚动到对话中该标题的准确位置
 - **可停靠、可缩放** —— 左右停靠（拖顶部横条移动）、边缘/角部拖拽调整大小、收起成可拖动的边缘把手；大小与位置自动记忆
-- **滚动条跟随停靠方向** —— 停靠左侧时滚动条在左，停靠右侧时在右
 - **分页渲染** —— 默认显示最近几组，大纲滚动到顶部自动加载更早的组
 - **Markdown 清理** —— 标题中的 `**加粗**`、*斜体*、`` `代码` ``、`[链接](url)`、`~~删除线~~` 等行内标记自动剥离
-- 对话无标题时自动隐藏；适配深色 / 浅色主题
+- 对话无标题时自动隐藏；适配深色 / 浅色主题；内阴影卡片质感随主题切换（深色为白色高光）
+
+## 兼容性
+
+| 插件版本 | DSH 版本 |
+| --- | --- |
+| **0.3.0** | **≥ 0.1.2-rc.1**（新 slot 架构） |
+| 0.2.2 | 0.1.2-rc.1 之前的旧版 DSH |
+
+0.3.0 重写了与宿主的对接（新版 slot 架构 + `useChat` 会话数据），**只支持 DSH 0.1.2-rc.1 及以上**；旧版 DSH 请安装 0.2.2。安装/更新时 DSH 市场会根据 package.json 的 `dsh.compatibility.dshReleases` 与 `peerDependencies` 做 host 兼容预检，版本不符会给出提示。
 
 ## 安装
 
@@ -47,9 +57,10 @@ dsh plugin --profile web add <本目录路径>
 ## 开发
 
 - `lib/client.js` —— 全部 UI 逻辑（浏览器端）
-- `lib/index.js` —— 宿主端空入口
+- `lib/index.js` —— 宿主端空入口（版本守卫可在此扩展）
 - `cordis.patch.yml` —— loader patch（符合官方 bundle 规范）
-- 改 client.js 后浏览器硬刷新即可生效；改 loader / patch 需重启 DSH
+- **0.3.0 起对接新版插件模型**：面板注册进会话级 `conversation.input.overlay` 槽（会话级 hook 由 `ctx.uiSession.provide` 贡献，`useChat` 由 ui-chat 贡献），面板本体 `createPortal` 到 `document.body` 渲染成固定浮层；数据入口为 `props.useChat`（`ChatSnapshot.order` + `nodes`，节点形状：`kind: user/assistant-step`、`location.turn`、`data.blocks`）
+- 改 client.js 后需重启 DSH（boot rev 按内容算）
 
 ## License
 

package/lib/client.js

@@ -6,11 +6,16 @@ window.__ModuleLoader__.load({
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     let react = require("react");
     let react_jsx_runtime = require("react/jsx-runtime");
-    require("@deepseek-ai/dsh-client-runtime/client");
+    let react_dom = require("react-dom"); // createPortal -> panel stays a top-level overlay (highest pointer priority)
+    // DSH 0.1.2-rc.1: the old @deepseek-ai/dsh-client-runtime package is gone.
+    // Runtime hooks (useChat etc.) now arrive as session-scope slot props —
+    // no runtime package to require here anymore.
 
     // ---------- constants ----------
     var PANEL_WIDTH = 288;
-    var Z_BASE = 950;
+    // Very high base so the portal-rendered panel (top-level stacking context)
+    // always sits above DSH content and its transcript width handles.
+    var Z_BASE = 2200;
     var EASE = "cubic-bezier(0.22, 0.9, 0.3, 1)"; // smooth non-linear slide
 
     // ---------- markdown helpers ----------
@@ -135,6 +140,18 @@ window.__ModuleLoader__.load({
       return null;
     }
 
+    // count every occurrence of q (case-insensitive) inside text
+    function countOccurrences(text, q) {
+      var lower = text.toLowerCase();
+      var count = 0;
+      var idx = 0;
+      while ((idx = lower.indexOf(q, idx)) !== -1) {
+        count++;
+        idx += q.length;
+      }
+      return count;
+    }
+
     // find the conversation's "load older messages" button (scoped to the
     // conversation scrollport so panel buttons are never matched)
     function findLoadOlderButton() {
@@ -148,6 +165,58 @@ window.__ModuleLoader__.load({
       return null;
     }
 
+    // ---- search keyword highlight in the conversation ----
+    var highlightSpans = [];
+
+    function clearHighlights() {
+      for (var i = 0; i < highlightSpans.length; i++) {
+        var s = highlightSpans[i];
+        if (s.parentNode) {
+          var t = document.createTextNode(s.textContent);
+          s.parentNode.replaceChild(t, s);
+        }
+      }
+      highlightSpans = [];
+    }
+
+    // wrap every occurrence of q (case-insensitive) inside row's text nodes;
+    // the occurrence at `currentOcc` gets a distinct "current" highlight
+    function highlightRow(row, q, currentOcc) {
+      if (!row || !q) return;
+      var walker = document.createTreeWalker(row, NodeFilter.SHOW_TEXT, null);
+      var textNodes = [];
+      while (walker.nextNode()) textNodes.push(walker.currentNode);
+      var occ = 0;
+      for (var i = 0; i < textNodes.length; i++) {
+        var node = textNodes[i];
+        var text = node.nodeValue;
+        if (!text) continue;
+        var lower = text.toLowerCase();
+        var idx = lower.indexOf(q);
+        if (idx < 0) continue;
+        var frag = document.createDocumentFragment();
+        var before = text.slice(0, idx);
+        if (before) frag.appendChild(document.createTextNode(before));
+        var mark = document.createElement("span");
+        if (occ === currentOcc) {
+          mark.className = "dqt-current";
+          mark.style.background = "rgba(79,140,255,0.55)";
+          mark.style.boxShadow = "0 0 0 1px rgba(79,140,255,0.85)";
+        } else {
+          mark.style.background = "rgba(79,140,255,0.32)";
+        }
+        mark.style.borderRadius = "2px";
+        mark.style.color = "inherit";
+        mark.textContent = text.slice(idx, idx + q.length);
+        frag.appendChild(mark);
+        highlightSpans.push(mark);
+        occ++;
+        var after = text.slice(idx + q.length);
+        if (after) frag.appendChild(document.createTextNode(after));
+        node.parentNode.replaceChild(frag, node);
+      }
+    }
+
     // ---------- theme colors: DSH CSS variables (adapt to light/dark) ----------
     var C = {
       panelBg: "var(--dsw-alias-bg-base, rgba(24, 28, 36, 0.96))",
@@ -159,6 +228,42 @@ window.__ModuleLoader__.load({
       chip: "rgba(79, 140, 255, 0.18)"
     };
 
+    // ---- theme scheme detection (for the panel's 3D inner shadow) ----
+    // Prefer a positive dark signal from the OS preference, then DSH's theme
+    // attribute/class, then the --dsw-alias-bg-base luminance as a last resort.
+    // Failed-open to light so a light card never gets a dark inner shadow by
+    // mistake; the caller flips to the white bevel only on a confident dark read.
+    function isDarkScheme() {
+      try {
+        // DSH's authoritative dark marker: <body data-ds-dark-theme> is set when
+        // the dark scheme is active (system OR manual). Check it first.
+        var body = document.body;
+        if (body) {
+          if (body.hasAttribute && body.hasAttribute("data-ds-dark-theme")) return true;
+          var cls = body.className || "";
+          if (/dark|theme-dark/i.test(cls)) return true;
+          var attr = (body.getAttribute("data-theme") || body.getAttribute("data-color-scheme") || "").toLowerCase();
+          if (attr === "dark" || /dark/.test(attr)) return true;
+        }
+        if (typeof matchMedia === "function" && matchMedia("(prefers-color-scheme: dark)").matches) return true;
+        var root = body || document.documentElement;
+        var cs = getComputedStyle(root).colorScheme;
+        if (typeof cs === "string" && /dark/i.test(cs)) return true;
+        var v = getComputedStyle(root).getPropertyValue("--dsw-alias-bg-base");
+        var m = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(v);
+        if (m) return (Number(m[1]) + Number(m[2]) + Number(m[3])) < 384;
+      } catch (e) {}
+      return false;
+    }
+    // Inner shadow: computed per-render (not once) so it follows the live theme.
+    // Dark scheme -> soft WHITE bevel (recessed card highlight); light -> soft
+    // dark shade. Outer shadow stays off (clip-path would clip it).
+    function innerShadow() {
+      return isDarkScheme()
+        ? "inset 0 0 0 1px rgba(255,255,255,0.16), inset 0 1px 0 rgba(255,255,255,0.12), inset 0 -10px 16px rgba(255,255,255,0.08)"
+        : "inset 0 0 0 1px rgba(0,0,0,0.08), inset 0 2px 10px rgba(0,0,0,0.18)";
+    }
+
     // ---------- error boundary ----------
     var ErrorBoundary = (function () {
       if (!react.Component) return function (p) { return p.children; };
@@ -198,13 +303,17 @@ window.__ModuleLoader__.load({
 
     // ---------- component ----------
     function OutlinePanel(props) {
-      var useSession = props.useSession;
-      if (!useSession) {
-        console.warn("[dsh-quick-toc] useSession prop missing");
+      // DSH 0.1.2-rc.1: the conversation moved out of the session snapshot —
+      // it is now the session-scope `chat` hook (ChatSnapshot: order + nodes
+      // map + legacy projection), contributed by dsh-client-ui-chat. Same node
+      // shape as before (kind user/assistant-step, location.turn, data.blocks).
+      var useChat = props.useChat;
+      if (!useChat) {
+        console.warn("[dsh-quick-toc] useChat prop missing (requires DSH >= 0.1.2-rc.1)");
         return null;
       }
-      var order = useSession(function (s) { return s.chat.order; });
-      var nodes = useSession(function (s) { return s.chat.nodes; });
+      var order = useChat(function (s) { return s.order; });
+      var nodes = useChat(function (s) { return s.nodes; });
 
       // ---- hooks (ALL before any conditional return) ----
       // collapsed by default; user expands via the edge handle (default dock: left)
@@ -343,6 +452,22 @@ window.__ModuleLoader__.load({
       var searching = _s17[0];
       var setSearching = _s17[1];
       var searchTimerRef = react.useRef(null);
+      // search scope: "title" (default) or "full" (user messages + AI replies)
+      var _s18 = react.useState("title");
+      var searchScope = _s18[0];
+      var setSearchScope = _s18[1];
+      // previous scope kept briefly so the old label cross-fades with the new one
+      var _s19 = react.useState(null);
+      var prevScope = _s19[0];
+      var setPrevScope = _s19[1];
+      var scopeTimerRef = react.useRef(null);
+      var toggleScope = function () {
+        setPrevScope(searchScope);
+        setSearchScope(searchScope === "title" ? "full" : "title");
+        setMatchIdx(0);
+        if (scopeTimerRef.current) clearTimeout(scopeTimerRef.current);
+        scopeTimerRef.current = setTimeout(function () { setPrevScope(null); }, 300);
+      };
       var openSearch = function () {
         setSearchOpen(true);
         setSearchAnim("enter");
@@ -350,6 +475,7 @@ window.__ModuleLoader__.load({
       var closeSearch = function () {
         setSearchAnim("out");
         setQuery("");
+        clearHighlights();
         setTimeout(function () {
           setSearchOpen(false);
           setSearchAnim("hidden");
@@ -369,6 +495,7 @@ window.__ModuleLoader__.load({
         setQuery(v);
         setMatchIdx(0);
         setSearching(true);
+        clearHighlights();
         if (searchTimerRef.current) clearTimeout(searchTimerRef.current);
         searchTimerRef.current = setTimeout(function () { setSearching(false); }, 220);
       };
@@ -545,9 +672,10 @@ window.__ModuleLoader__.load({
         var turnTimes = {};
         var turnUserKey = {};
         var turnUserText = {};
+        var turnUserFull = {};
         if (!order || !nodes) return result;
         // first pass: per-turn time — the LAST message of the turn wins (end time);
-        // also remember each turn's user message key + first-line preview
+        // also remember each turn's user message key + first-line preview + full text
         for (var i = 0; i < order.length; i++) {
           var k0 = order[i];
           var n0 = nodes.get(k0);
@@ -558,11 +686,12 @@ window.__ModuleLoader__.load({
           if (n0.kind === "user" && turnUserKey[tid0] === undefined) {
             turnUserKey[tid0] = k0;
             turnUserText[tid0] = previewText(extractUserText(n0), 30);
+            turnUserFull[tid0] = extractUserText(n0);
           }
           var t0 = getNodeTime(n0);
           if (t0) turnTimes[tid0] = t0;
         }
-        // second pass: group assistant headings by turn
+        // second pass: group assistant headings + full reply texts by turn
         for (var j = 0; j < order.length; j++) {
           var key = order[j];
           var node = nodes.get(key);
@@ -576,11 +705,15 @@ window.__ModuleLoader__.load({
               time: turnId !== null ? (turnTimes[turnId] || "") : "",
               userKey: turnId !== null ? (turnUserKey[turnId] || "") : "",
               userText: turnId !== null ? (turnUserText[turnId] || "") : "",
+              userFull: turnId !== null ? (turnUserFull[turnId] || "") : "",
+              msgs: [],
               headings: []
             };
             result.push(current);
           }
-          var parsed = parseHeadings(extractReplyText(node));
+          var text = extractReplyText(node);
+          current.msgs.push({ key: key, text: text });
+          var parsed = parseHeadings(text);
           var hIdx = 0;
           for (var k = 0; k < parsed.length; k++) {
             current.headings.push({ level: parsed[k].level, title: parsed[k].title, key: key, idx: hIdx });
@@ -661,7 +794,11 @@ window.__ModuleLoader__.load({
         return function () { sp.removeEventListener("scroll", update); };
       }, [keyToGroup]);
 
-      // ---- search matches: headings whose title contains the query ----
+      // ---- search matches ----
+      // "title" scope: heading titles only; "full" scope: also the user
+      // message and every AI reply text of each turn.
+      // Every occurrence counts (multiple hits inside one message = multiple
+      // matches), so the n/N counter reflects the real total.
       var matches = react.useMemo(function () {
         var q = query.trim().toLowerCase();
         if (!q) return [];
@@ -670,13 +807,30 @@ window.__ModuleLoader__.load({
           var g = groups[gi];
           for (var j = 0; j < g.headings.length; j++) {
             var h = g.headings[j];
-            if (h.title.toLowerCase().indexOf(q) >= 0) {
+            var n = countOccurrences(h.title, q);
+            for (var c = 0; c < n; c++) {
               out.push({ gi: gi, title: h.title, key: h.key, idx: h.idx });
             }
           }
+          if (searchScope === "full") {
+            if (g.userKey && g.userFull) {
+              var nu = countOccurrences(g.userFull, q);
+              for (var cu = 0; cu < nu; cu++) {
+                out.push({ gi: gi, title: previewText(g.userFull, 30), key: g.userKey, idx: undefined });
+              }
+            }
+            for (var m = 0; m < g.msgs.length; m++) {
+              var msg = g.msgs[m];
+              if (!msg.text) continue;
+              var nm = countOccurrences(msg.text, q);
+              for (var cm = 0; cm < nm; cm++) {
+                out.push({ gi: gi, title: previewText(msg.text, 30), key: msg.key, idx: undefined });
+              }
+            }
+          }
         }
         return out;
-      }, [groups, query]);
+      }, [groups, query, searchScope]);
 
       // ---- nothing to show without headings ----
       if (groups.length === 0) return null;
@@ -684,24 +838,20 @@ window.__ModuleLoader__.load({
       // ---- geometry: always position by `left` (px) so dock-switch & slide share one animated transition
       var dockRight = dock === "right";
       var panelLeft;
-      if (open) {
-        panelLeft = dockRight
-          ? window.innerWidth - (viewport ? viewport.right + 48 : 60) - panelW
-          : (viewport ? viewport.left + 8 : 8);
+      if (dockRight) {
+        // RIGHT dock: keep the panel's VISIBLE right edge pinned at the SAME
+        // line when collapsed as when expanded (the expand edge is correct).
+        // open:   left = openRight,           visible right edge = openRight+panelW
+        // closed: left = openRight + panelW,  clip-right panelW hides it fully,
+        //         so the visible right edge stays at openRight+panelW -> the
+        //         collapse shrinks toward that line and vanishes exactly there.
+        var openRight = window.innerWidth - (viewport ? viewport.right + 48 : 60) - panelW;
+        panelLeft = open ? openRight : (openRight + panelW);
+      } else if (open) {
+        // LEFT dock open (left dock is the confirmed-correct reference — untouched)
+        panelLeft = (viewport ? viewport.left + 8 : 8);
       } else {
-        // collapsed position:
-        //  left dock  -> slide just past the left sidebar edge (stop there)
-        //  right dock -> boundary is the right sidebar when it is open,
-        //                otherwise the screen's right edge
-        if (dockRight) {
-          // with the right sidebar open, slide INTO the sidebar area (covered
-          // by the cover wall); otherwise fly off the screen's right edge
-          panelLeft = (viewport && viewport.right > 80)
-            ? (window.innerWidth - viewport.right)
-            : window.innerWidth + 24;
-        } else {
-          panelLeft = (viewport ? viewport.left - panelW - 8 : -(panelW + 48));
-        }
+        panelLeft = (viewport ? viewport.left - panelW - 8 : -(panelW + 48));
       }
       var vMaxH = viewport ? Math.max(200, viewport.height - 28) : "72vh";
       var baseTopPx = (viewport ? viewport.top + 14 : window.innerHeight * 0.12) + panelY;
@@ -754,13 +904,38 @@ window.__ModuleLoader__.load({
         sp.scrollTo({ top: t, behavior: "smooth" });
       };
 
-      // jump to the n-th match, cycling; also reveal the group in the outline
+      // jump to the n-th match, cycling; also reveal the group in the outline.
+      // ONE smooth scroll straight to the current occurrence (no competing
+      // scrolls): highlight first, then position the mark at the upper-middle
       var goToMatch = function (n) {
         if (matches.length === 0) return;
         var i = ((n % matches.length) + matches.length) % matches.length;
         setMatchIdx(i);
         var m = matches[i];
-        jump(m.key, m.idx);
+        var q = query.trim().toLowerCase();
+        clearHighlights();
+        var r = findRowStrict(m.key);
+        if (r && q) {
+          // occurrence index within the target message (consecutive in matches)
+          var occ = 0;
+          for (var p = i - 1; p >= 0 && matches[p].key === m.key; p--) occ++;
+          highlightRow(r, q, occ);
+          var markEl = r.querySelector(".dqt-current");
+          var sp = r.closest ? r.closest("[data-conversation-scroll]") : null;
+          if (sp && markEl) {
+            var target = markEl.getBoundingClientRect().top - sp.getBoundingClientRect().top + sp.scrollTop - sp.clientHeight * 0.35;
+            // stick-to-bottom nudge (same as jump): break the 25px floor hold
+            var floor = Math.max(0, sp.scrollHeight - sp.clientHeight);
+            if (floor - sp.scrollTop <= 25 && Math.abs(target - sp.scrollTop) > 60) {
+              sp.scrollTop = Math.max(0, floor - 26);
+            }
+            sp.scrollTo({ top: Math.max(0, target), behavior: "smooth" });
+          } else {
+            jump(m.key, m.idx);
+          }
+        } else {
+          jump(m.key, m.idx);
+        }
         setVisibleCount(function (prev) {
           return Math.max(prev, Math.min(groups.length, groups.length - m.gi));
         });
@@ -828,9 +1003,12 @@ window.__ModuleLoader__.load({
       // like being covered by the sidebar (the sidebar stays untouched):
       //  left dock  -> clipped from the left up to the sidebar line
       //  right dock -> clipped from the right at the screen/sidebar line
+      // LEFT dock keeps its original clip (collapse left). RIGHT dock clips the
+      // LEFT side so the panel closes toward its right (dock) edge in place.
       var panelClip = "inset(0 0 0 0px)";
       if (!open) {
         if (dockRight) {
+          // mirror of LEFT: clip the RIGHT side (panel flies right, shrinking from its right)
           panelClip = "inset(0 " + panelW + "px 0 0)";
         } else {
           panelClip = "inset(0 0 0 " + (panelW + 8) + "px)";
@@ -851,13 +1029,15 @@ window.__ModuleLoader__.load({
           background: C.panelBg,
           border: "none",
           borderRadius: 12,
-          boxShadow: "0 2px 10px rgba(0,0,0,0.18)",
           zIndex: Z_BASE,
           overflow: "hidden",
           color: C.text,
           opacity: panelOpacity,
           clipPath: panelClip,
-          boxShadow: "none",
+          // inner shadow only (no outer): theme-aware (white bevel in dark mode,
+          // soft shade in light) — outer shadow would be clipped by the collapse
+          // clip-path and the panel edges.
+          boxShadow: innerShadow(),
           transition: panelTransition,
           pointerEvents: "auto"
         },
@@ -1043,26 +1223,69 @@ window.__ModuleLoader__.load({
                   transition: "opacity 0.2s ease, transform 0.2s ease"
                 },
                 children: [
-              react_jsx_runtime.jsx("input", {
-                ref: searchRef,
-                value: query,
-                onChange: function (e) { onQueryChange(e.target.value); },
-                onKeyDown: function (e) {
-                  if (e.key === "Enter") { goToMatch(matchIdx + 1); e.preventDefault(); }
-                  if (e.key === "Escape") { closeSearch(); }
-                },
-                placeholder: "搜索标题，回车定位…",
+              // input with a custom animated placeholder: the box stays static,
+              // only the placeholder text fades when the scope switches
+              react_jsx_runtime.jsx("div", {
                 style: {
+                  position: "relative",
                   flex: 1,
                   minWidth: 0,
+                  display: "flex",
+                  alignItems: "center",
                   background: "var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,0.14))",
-                  border: "none",
-                  borderRadius: 6,
-                  padding: "3px 8px",
-                  fontSize: 12,
-                  color: C.text,
-                  outline: "none"
-                }
+                  borderRadius: 999,
+                  padding: "6px 12px"
+                },
+                children: [
+                  react_jsx_runtime.jsx("input", {
+                    ref: searchRef,
+                    value: query,
+                    onChange: function (e) { onQueryChange(e.target.value); },
+                    onKeyDown: function (e) {
+                      if (e.key === "Enter") { goToMatch(matchIdx + 1); e.preventDefault(); }
+                      if (e.key === "Escape") { closeSearch(); }
+                    },
+                    style: {
+                      flex: 1,
+                      minWidth: 0,
+                      width: "100%",
+                      background: "transparent",
+                      border: "none",
+                      outline: "none",
+                      fontSize: 13,
+                      color: C.text,
+                      padding: 0
+                    }
+                  }),
+                  (!query) ? react_jsx_runtime.jsx("span", {
+                    style: {
+                      position: "absolute",
+                      left: 12,
+                      pointerEvents: "none",
+                      fontSize: 13,
+                      color: "var(--dsw-alias-label-tertiary, rgba(128,128,128,0.7))"
+                    },
+                    children: [
+                      "搜索",
+                      react_jsx_runtime.jsx("span", {
+                        style: { position: "relative", display: "inline-block" },
+                        children: [
+                          react_jsx_runtime.jsx("span", {
+                            key: searchScope,
+                            style: { display: "inline-block", animation: "dqt-fade-in 0.25s linear" },
+                            children: searchScope === "title" ? "标题" : "全文"
+                          }),
+                          (prevScope && prevScope !== searchScope) ? react_jsx_runtime.jsx("span", {
+                            key: "old-" + prevScope,
+                            style: { position: "absolute", left: 0, top: 0, opacity: 0, animation: "dqt-fade-out 0.25s linear forwards" },
+                            children: prevScope === "title" ? "标题" : "全文"
+                          }) : null
+                        ]
+                      }),
+                      "，回车定位…"
+                    ]
+                  }) : null,
+                ]
               }),
               searching ? react_jsx_runtime.jsx("span", {
                 style: { width: 13, height: 13, flex: "none", display: "flex", alignItems: "center", justifyContent: "center" },
@@ -1083,6 +1306,43 @@ window.__ModuleLoader__.load({
               }) : react_jsx_runtime.jsx("span", {
                 style: { fontSize: 11, color: C.muted, flex: "none", minWidth: 30, textAlign: "center" },
                 children: matches.length > 0 ? ((matchIdx % matches.length) + 1) + "/" + matches.length : ""
+              }),
+              // scope toggle: 标题 <-> 全文 (round pill; background fades,
+              // label text cross-fades old->new)
+              react_jsx_runtime.jsx("button", {
+                onClick: toggleScope,
+                title: searchScope === "title" ? "当前：仅搜索标题。点击切换为全文搜索" : "当前：全文搜索。点击切换为仅标题",
+                style: {
+                  flex: "none",
+                  width: 34,
+                  height: 34,
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  borderRadius: "50%",
+                  fontSize: 11,
+                  color: searchScope === "full" ? "var(--dsw-alias-brand-primary, #4f8cff)" : C.muted,
+                  background: searchScope === "full" ? "rgba(79,140,255,0.18)" : "var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,0.14))",
+                  border: "none",
+                  cursor: "pointer",
+                  whiteSpace: "nowrap",
+                  transition: "background 0.25s ease"
+                },
+                children: react_jsx_runtime.jsx("span", {
+                  style: { position: "relative", display: "inline-flex", alignItems: "center", justifyContent: "center" },
+                  children: [
+                    react_jsx_runtime.jsx("span", {
+                      key: searchScope,
+                      style: { animation: "dqt-fade-in 0.25s linear", display: "block" },
+                      children: searchScope === "title" ? "标题" : "全文"
+                    }),
+                    (prevScope && prevScope !== searchScope) ? react_jsx_runtime.jsx("span", {
+                      key: "old-" + prevScope,
+                      style: { position: "absolute", opacity: 0, animation: "dqt-fade-out 0.25s linear forwards", display: "block" },
+                      children: prevScope === "title" ? "标题" : "全文"
+                    }) : null
+                  ]
+                })
               })
                 ]
               })
@@ -1092,6 +1352,7 @@ window.__ModuleLoader__.load({
           // the scrollbar follows the dock side (rtl flips it to the left)
           react_jsx_runtime.jsx("div", {
             ref: listRef,
+            className: "dqt-list",
             style: {
               overflowY: "auto",
               padding: "6px 8px",
@@ -1205,9 +1466,10 @@ window.__ModuleLoader__.load({
         })
       }) : null;
 
-      return react_jsx_runtime.jsx(ErrorBoundary, {
-        children: [panelEl, edgeEl]
-      });
+      return react_dom.createPortal(
+        react_jsx_runtime.jsx(ErrorBoundary, { children: [panelEl, edgeEl] }),
+        document.body
+      );
     }
 
     function renderItem(n, depth, jump, C, uid) {
@@ -1326,15 +1588,6 @@ window.__ModuleLoader__.load({
       return out;
     }
 
-    function OutlineOverlay(props) {
-      var SessionProvider = props.SessionProvider;
-      var renderSlot = props.renderSlot;
-      return react_jsx_runtime.jsx(SessionProvider, {
-        empty: function () { return null; },
-        children: function () { return renderSlot("quick-toc.panel", {}); }
-      });
-    }
-
     var zh = {
       "panel.title": "对话大纲"
     };
@@ -1342,38 +1595,48 @@ window.__ModuleLoader__.load({
       "panel.title": "Conversation Outline"
     };
 
-    var inject = ["slots", "sessions", "locale"];
+    var inject = ["slots", "locale"];
 
     function apply(ctx) {
       ctx.effect(function () {
         return ctx.locale.register("dsh-quick-toc", { zh: zh, en: en });
       }, "dsh-quick-toc: dictionaries");
-      ctx.slots.inject("shell.overlay", function () {
+      // DSH 0.1.2-rc.1: session-scoped hooks (useChat/useSession/sessionId) only arrive
+      // inside a declared session slot. Register the panel into the session-scoped
+      // conversation.input.overlay (list/additive) so it receives useChat; the panel
+      // itself renders a fixed, frame-floating dock, so the overlay seat is just the
+      // hook source (it is NOT the panel's visual container).
+      ctx.slots.inject("conversation.input.overlay", function () {
         return ctx.slots.register({
-          name: "shell.overlay",
+          name: "conversation.input.overlay",
           id: "quick-toc",
           order: 90,
-          children: { "quick-toc.panel": { kind: "single", scope: "session" } }
-        }, OutlineOverlay);
-      });
-      ctx.slots.inject("quick-toc.panel", function () {
-        return ctx.slots.register({
-          name: "quick-toc.panel",
           locale: "dsh-quick-toc"
         }, OutlinePanel);
       });
     }
 
+    exports.name = "dsh-quick-toc"; // runner attributes slot entries to this registrant
     exports.apply = apply;
     exports.inject = inject;
 
-    // inject the small keyframe stylesheet once (spinner rotation)
+    // inject the small keyframe + panel-scrollbar stylesheet once
     (function () {
       if (typeof document === "undefined") return;
       if (document.getElementById("dsh-quick-toc-css")) return;
       var s = document.createElement("style");
       s.id = "dsh-quick-toc-css";
-      s.textContent = "@keyframes dqt-spin{to{transform:rotate(360deg)}}";
+      s.textContent = "@keyframes dqt-spin{to{transform:rotate(360deg)}}@keyframes dqt-fade-in{from{opacity:0}to{opacity:1}}@keyframes dqt-fade-out{from{opacity:1}to{opacity:0}}" +
+        // Hide the native scrollbar entirely (no arrow buttons, no grey bar) —
+        // custom webkit scrollbar styling was not reliably suppressing the
+        // default arrows, so a hidden native bar + the panel's inner shadow gives
+        // the cleanest look. Scrolling still works (auto-follow + wheel-load-older).
+        ".dqt-list{scrollbar-width:none;-ms-overflow-style:none}" +
+        ".dqt-list::-webkit-scrollbar{display:none;width:0;height:0}" +
+        ".dqt-list::-webkit-scrollbar-button{display:none;height:0;width:0}" +
+        ".dqt-list::-webkit-scrollbar-track{background:transparent}" +
+        ".dqt-list::-webkit-scrollbar-thumb{background:transparent}" +
+        ".dqt-list::-webkit-scrollbar-corner{background:transparent}";
       document.head.appendChild(s);
     })();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-quick-toc",
-  "version": "0.2.0-beta",
+  "version": "0.3.0",
   "description": "Quick conversation TOC for DeepSeek Harness: markdown heading outline grouped by turn, with auto-follow highlight and smooth jump navigation",
   "type": "module",
   "main": "lib/index.js",
@@ -8,8 +8,12 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
+    "README.en.md",
     "LICENSE"
   ],
+  "engines": {
+    "dsh": ">=0.1.2-rc.1"
+  },
   "exports": {
     ".": "./lib/index.js",
     "./client": "./lib/client.js",
@@ -21,13 +25,23 @@
     },
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-chat",
         "@deepseek-ai/dsh-client-ui-conversation",
         "@deepseek-ai/dsh-client-ui-layout"
       ],
       "platform": "web"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.1.2-rc.1": "compatible"
+      }
     }
   },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-ui-chat": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.2-rc.1"
+  },
   "license": "MIT",
   "keywords": [
     "dsh",