dsh-quick-toc 0.2.2 → 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 ----------
@@ -223,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; };
@@ -262,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)
@@ -793,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;
@@ -962,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)";
@@ -985,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"
         },
@@ -1306,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",
@@ -1419,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) {
@@ -1540,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": "对话大纲"
     };
@@ -1556,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)}}@keyframes dqt-fade-in{from{opacity:0}to{opacity:1}}@keyframes dqt-fade-out{from{opacity:1}to{opacity:0}}";
+      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.2",
+  "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",