dsh-context 0.7.2 → 0.8.0

package/README.md

@@ -39,6 +39,10 @@ One stacked bar per model request, finer than per-message. Toggle between **Turn
 
 Above: a real session that grew to ~563k tokens across 48 turns, then compaction (✂) recycled −535.5k in one step, and the conversation continued from a fresh, small window.
 
+In **Step** granularity, hovering any bar shows that single step's context info instantly — its turn/step, timestamp, and estimated vs. provider-reported token counts:
+
+![History chart with a step hover tooltip](https://raw.githubusercontent.com/bowenliang123/dsh-context/main/docs/history-step-hover.png)
+
 ### ⚡ Context events — when and why the window changed
 
 Every compaction, tool-output prune, skill or plugin context injection, and model switch — each with its token delta, turn/step attribution, and timestamp:
@@ -49,6 +53,9 @@ Every compaction, tool-output prune, skill or plugin context injection, and mode
 
 The exact message list the model sees right now, newest first, with a per-message token cost.
 
+## Releasing
+
+Releases are cut by tagging: `git tag vX.Y.Z && gh release create vX.Y.Z`. A [GitHub Actions workflow](.github/workflows/release.yml) then builds, tests, and publishes the package to npm automatically via [npm Trusted Publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) — no long-lived token needed, provenance included.
 
 ## Like it?
 

package/lib/client.js

@@ -19,6 +19,7 @@ var DICT_ZH = {
   "overview.ofWindow": "tokens\uFF08\u7EA6 {p}%\uFF09",
   "overview.estimate": "tokens\uFF08\u4F30\u7B97\uFF09",
   "overview.free": "\u5269\u4F59\u7A97\u53E3",
+  "overview.splitEst": "\xB7 \u5206\u7C7B\u6309\u4F30\u7B97\u6BD4\u4F8B\u5206\u914D",
   "stats.title": "\u4E0A\u4E0B\u6587\u7EDF\u8BA1",
   "stats.hint": "\u7EDF\u8BA1\u5F53\u524D\u4FDD\u7559\u7684\u5386\u53F2\u7A97\u53E3\uFF08\u4E0E\u8D8B\u52BF\u56FE\u4E00\u81F4\uFF09",
   "stats.turns": "\u8F6E\u6B21",
@@ -88,6 +89,7 @@ var DICT_EN = {
   "overview.ofWindow": "tokens (~{p}%)",
   "overview.estimate": "tokens (estimated)",
   "overview.free": "Free window",
+  "overview.splitEst": "\xB7 category split is estimated",
   "stats.title": "Context stats",
   "stats.hint": "Over the retained history window (same as the History chart)",
   "stats.turns": "Turns",
@@ -196,7 +198,14 @@ var STYLES = [
   ".lc-grid { position: absolute; left: 0; right: 0; border-top: 1px dashed var(--dsw-alias-border-l1); pointer-events: none; }",
   ".lc-grid-top { top: 18px; }",
   ".lc-grid-mid { top: 74px; }",
-  ".lc-bar { position: relative; width: 14px; flex: none; height: 100%; display: flex; align-items: flex-end; cursor: pointer; border-radius: 2px; }",
+  ".lc-bar { position: relative; width: 14px; flex: none; height: 100%; display: flex; align-items: flex-end; cursor: pointer; border-radius: 2px; transition: opacity 120ms ease; }",
+  // Turn-aware dimming: while a turn is focused, bars OUTSIDE the active
+  // turn fade to 35% and the whole current turn stays fully opaque.
+  ".lc-chart-dim .lc-bar { opacity: 0.35; }",
+  ".lc-chart-dim .lc-bar-in-turn { opacity: 1; }",
+  ".lc-chart-dim .lc-turn { opacity: 0.35; }",
+  ".lc-chart-dim .lc-turn-on { opacity: 1; }",
+  ".lc-chart-tip { position: absolute; top: 0; transform: translateX(-50%); z-index: 5; white-space: nowrap; background: var(--dsw-alias-bg-layer-2); border: 1px solid var(--dsw-alias-border-l1); border-radius: 6px; padding: 3px 8px; font-size: 12px; color: var(--dsw-alias-label-primary); box-shadow: 0 2px 8px rgba(0,0,0,0.18); pointer-events: none; }",
   ".lc-bar:hover { background: var(--dsw-alias-bg-layer-2); }",
   ".lc-bar-selected { outline: 2px solid var(--dsw-alias-brand-primary); outline-offset: 1px; }",
   ".lc-bar-hovered { outline: 1px dashed var(--dsw-alias-brand-primary); outline-offset: 1px; }",
@@ -205,7 +214,7 @@ var STYLES = [
   ".lc-bar-stack > div { width: 100%; }",
   ".lc-bar-marker { position: absolute; top: -16px; left: 50%; transform: translateX(-50%); font-size: 11px; color: var(--dsw-alias-state-warn-primary); }",
   ".lc-turns { display: flex; gap: 2px; width: max-content; min-width: 100%; margin-top: 4px; }",
-  ".lc-turn { flex: none; box-sizing: border-box; text-align: center; font-size: 10px; line-height: 14px; font-weight: 600; color: #fff; border-radius: 3px; height: 14px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; cursor: default; transition: filter 120ms; }",
+  ".lc-turn { flex: none; box-sizing: border-box; text-align: center; font-size: 10px; line-height: 14px; font-weight: 600; color: #fff; border-radius: 3px; height: 14px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; cursor: default; transition: filter 120ms, opacity 120ms; }",
   ".lc-turn-on { filter: brightness(1.35); box-shadow: 0 0 0 1px rgba(255,255,255,0.4); }",
   ".lc-detail { margin-top: 12px; border-top: 1px solid var(--dsw-alias-border-l1); padding-top: 12px; }",
   ".lc-detail-head { display: flex; flex-wrap: wrap; gap: 6px 16px; margin-bottom: 8px; color: var(--dsw-alias-label-secondary); }",
@@ -269,6 +278,14 @@ function partsOf(breakdown) {
     return { key: c.key, color: c.color, value: breakdown[c.key] || 0 };
   });
 }
+function anchoredParts(parts, target) {
+  if (target === null || target <= 0) return parts;
+  let total = 0;
+  for (const p of parts) total += p.value;
+  if (total <= 0 || total === target) return parts;
+  const scale = target / total;
+  return parts.map((p) => ({ ...p, value: Math.round(p.value * scale) }));
+}
 
 // src/client/format.ts
 function fmt(n) {
@@ -433,7 +450,7 @@ function makeRequestDetail(kit, StackedBar) {
               { className: "lc-bar-track" },
               h("span", { className: "lc-bar-fill", style: { width: (req.total > 0 ? v / req.total * 100 : 0) + "%", background: c.color } })
             ),
-            h("span", { className: "lc-detail-num" }, fmt3(v)),
+            h("span", { className: "lc-detail-num" }, "\u2248" + fmt3(v)),
             h("span", { className: "lc-detail-pct" }, req.total > 0 ? Math.round(v / req.total * 100) + "%" : "")
           );
         })
@@ -524,7 +541,7 @@ function makeStackedBar(kit) {
           const pct = scale > 0 ? p.value / scale * 100 : 0;
           if (p.key === props.hoverKey && p.value > 0) {
             tip = {
-              text: catLabel(p.key) + " " + fmt3(p.value) + " (" + Math.round(p.value / total * 100) + "%)",
+              text: catLabel(p.key) + " \u2248" + fmt3(p.value) + " (" + Math.round(p.value / total * 100) + "%)",
               leftPct: Math.max(12, Math.min(acc + pct / 2, 88))
             };
             break;
@@ -593,7 +610,7 @@ function makeLegend(kit) {
             }
           },
           h("i", { style: { background: p.color } }),
-          catLabel(p.key) + " " + fmt3(p.value),
+          catLabel(p.key) + " \u2248" + fmt3(p.value),
           total > 0 ? h("em", null, Math.round(p.value / total * 100) + "%") : null
         );
       })
@@ -639,8 +656,13 @@ function makeTrendChart(kit) {
   return function TrendChart(props) {
     const requests = props.requests;
     const markers = props.markers;
+    const anchorOf = (req) => typeof req.prompt === "number" && req.prompt > 0 && req.total > 0 ? req.prompt / req.total : 1;
+    const barTotalOf = (req) => typeof req.prompt === "number" && req.prompt > 0 ? req.prompt : req.total;
     let maxTotal = 1;
-    for (const req of requests) if (req.total > maxTotal) maxTotal = req.total;
+    for (const req of requests) {
+      const bt = barTotalOf(req);
+      if (bt > maxTotal) maxTotal = bt;
+    }
     const groups = [];
     for (const req of requests) {
       let grp = groups.length > 0 ? groups[groups.length - 1] : null;
@@ -679,6 +701,12 @@ function makeTrendChart(kit) {
       }
       updateEdges(el);
     });
+    const tipOf = (req) => {
+      const head = req.stepCount !== void 0 && req.stepCount > 1 ? tr("tip.turn", { t: req.turn ?? 0, n: req.stepCount }) : tr("tip.step", { t: req.turn ?? 0, s: req.step ?? 0 });
+      return head + " \xB7 " + fmtTime2(req.time) + " \xB7 " + tr("tip.total", { n: fmt3(req.total) }) + (req.prompt !== void 0 ? " \xB7 " + tr("tip.actual", { n: fmt3(req.prompt) }) : "");
+    };
+    const hoveredIdx = props.hoveredSeq !== null ? requests.findIndex((r) => r.seq === props.hoveredSeq) : -1;
+    const hoveredReq = hoveredIdx >= 0 ? requests[hoveredIdx] : null;
     return h(
       "div",
       { className: "lc-chartrow" },
@@ -692,7 +720,9 @@ function makeTrendChart(kit) {
       h(
         "div",
         {
-          className: "lc-chart-scroll",
+          // Turn-aware dim scope: while a turn is focused (bar or strip hover),
+          // bars and strip blocks OUTSIDE the active turn fade to 35%.
+          className: "lc-chart-scroll" + (props.activeTurn !== null ? " lc-chart-dim" : ""),
           ref: scrollRef,
           onScroll: (e) => {
             updateEdges(e.currentTarget);
@@ -705,9 +735,12 @@ function makeTrendChart(kit) {
         // clears the preview (a pinned selection, if any, takes over again).
         h(
           "div",
-          { className: "lc-chart", onMouseLeave: () => {
-            props.onHover(null);
-          } },
+          {
+            className: "lc-chart",
+            onMouseLeave: () => {
+              props.onHover(null);
+            }
+          },
           h("div", { className: "lc-grid lc-grid-top" }),
           h("div", { className: "lc-grid lc-grid-mid" }),
           requests.map((req, i) => {
@@ -716,7 +749,6 @@ function makeTrendChart(kit) {
             const selected = props.selectedSeq === req.seq;
             const hovered = props.hoveredSeq === req.seq;
             const inTurn = props.activeTurn !== null && (req.turn ?? 0) === props.activeTurn;
-            const tip = (req.stepCount !== void 0 && req.stepCount > 1 ? tr("tip.turn", { t: req.turn ?? 0, n: req.stepCount }) : tr("tip.step", { t: req.turn ?? 0, s: req.step ?? 0 })) + " \xB7 " + fmtTime2(req.time) + "\n" + tr("tip.total", { n: fmt3(req.total) }) + (req.prompt !== void 0 ? tr("tip.actual", { n: fmt3(req.prompt) }) : "") + "\n" + CATS.map((c) => catLabel(c.key) + " " + fmt3(req[c.key] || 0)).join(" / ");
             return h(
               "div",
               {
@@ -725,7 +757,6 @@ function makeTrendChart(kit) {
                 // keep the same fixed width as step bars.
                 className: "lc-bar" + (selected ? " lc-bar-selected" : "") + (hovered ? " lc-bar-hovered" : "") + (inTurn ? " lc-bar-in-turn" : ""),
                 style: { width: BAR_W + "px" },
-                title: tip,
                 onClick: () => {
                   props.onSelect(selected ? null : req.seq);
                 },
@@ -743,7 +774,7 @@ function makeTrendChart(kit) {
                 "div",
                 { className: "lc-bar-stack" },
                 CATS.map((c) => {
-                  const v = req[c.key] || 0;
+                  const v = (req[c.key] || 0) * anchorOf(req);
                   if (!v) return null;
                   return h("div", { key: c.key, style: { height: Math.max(1, Math.round(v / maxTotal * CHART_H)) + "px", background: c.color } });
                 })
@@ -751,6 +782,12 @@ function makeTrendChart(kit) {
             );
           })
         ),
+        // Instant hover tooltip, glued to its bar's column (it lives in the
+        // scrolling content, so it follows the bar while the chart scrolls).
+        hoveredReq !== null ? h("div", {
+          className: "lc-chart-tip",
+          style: { left: hoveredIdx * (BAR_W + BAR_GAP) + BAR_W / 2 + "px" }
+        }, tipOf(hoveredReq)) : null,
         // Turn strip: one COLOR BLOCK per turn, spanning exactly its bars'
         // columns, so the partition reads at a glance and lines up with the
         // steps above. Hovering a block highlights that turn's bars in the
@@ -785,6 +822,7 @@ function makeTrendChart(kit) {
 }
 
 // src/client/components/contextView.ts
+var viewScroll = /* @__PURE__ */ new Map();
 function makeContextView(ctx, kit) {
   const { t, tr, fmt: fmt3, fmtTime: fmtTime2, catLabel } = kit;
   const StackedBar = makeStackedBar(kit);
@@ -809,6 +847,26 @@ function makeContextView(ctx, kit) {
     React.useEffect(() => {
       dataRef.current = data;
     }, [data]);
+    const rootRef = React.useRef(null);
+    const scrollerRef = React.useRef(null);
+    const restoredRef = React.useRef(null);
+    React.useLayoutEffect(() => {
+      if (typeof sessionId !== "string" || sessionId === "" || data === null) return;
+      if (restoredRef.current === sessionId) return;
+      restoredRef.current = sessionId;
+      const scroller = rootRef.current !== null ? rootRef.current.closest("[data-conversation-scroll]") : null;
+      if (scroller === null) return;
+      scrollerRef.current = scroller;
+      scroller.scrollTop = viewScroll.get(sessionId) ?? 0;
+    }, [sessionId, data]);
+    React.useLayoutEffect(() => {
+      return () => {
+        if (typeof sessionId !== "string" || sessionId === "") return;
+        const scroller = scrollerRef.current;
+        if (scroller === null) return;
+        viewScroll.set(sessionId, scroller.scrollTop);
+      };
+    }, [sessionId]);
     React.useEffect(() => {
       if (typeof sessionId !== "string" || sessionId === "") return void 0;
       let alive = true;
@@ -850,10 +908,10 @@ function makeContextView(ctx, kit) {
     }, []);
     void tick;
     if (error) {
-      return h("div", { className: "lc-root" }, h("div", { className: "lc-empty" }, t("error") + error));
+      return h("div", { className: "lc-root", ref: rootRef }, h("div", { className: "lc-empty" }, t("error") + error));
     }
     if (!data) {
-      return h("div", { className: "lc-root" }, h("div", { className: "lc-empty" }, t("loading")));
+      return h("div", { className: "lc-root", ref: rootRef }, h("div", { className: "lc-empty" }, t("loading")));
     }
     const current = data.current;
     const requests = data.requests || [];
@@ -880,10 +938,18 @@ function makeContextView(ctx, kit) {
         break;
       }
     }
-    const windowPct = data.contextWindow ? Math.min(100, Math.round(current.total / data.contextWindow * 100)) : null;
+    const occ = data.occupancy;
+    const projected = occ !== void 0 && typeof occ.projectedTokens === "number" ? occ.projectedTokens : void 0;
+    const lastReq = displayRequests.length > 0 ? displayRequests[displayRequests.length - 1] : null;
+    const derived = lastReq !== null && typeof lastReq.prompt === "number" ? lastReq.prompt + (current.total - lastReq.total) : void 0;
+    const occupancyTokens = projected ?? derived ?? null;
+    const occupancyWindow = occ !== void 0 && typeof occ.contextWindow === "number" ? occ.contextWindow : data.contextWindow;
+    const headline = occupancyTokens ?? current.total;
+    const headlinePct = occupancyWindow ? Math.min(100, Math.round(headline / occupancyWindow * 100)) : null;
+    const parts = anchoredParts(partsOf(current), occupancyTokens !== null && headline > 0 ? headline : null);
     return h(
       "div",
-      { className: "lc-root" },
+      { className: "lc-root", ref: rootRef },
       // ---- session context stats (over the retained window) ----
       h(StatsBoard, { requests, events }),
       // ---- overview ----
@@ -903,20 +969,12 @@ function makeContextView(ctx, kit) {
         h(
           "div",
           { className: "lc-overview-num" },
-          h("b", null, fmt3(current.total)),
-          h("span", null, data.contextWindow ? " / " + fmt3(data.contextWindow) + " " + tr("overview.ofWindow", { p: windowPct ?? 0 }) : " " + t("overview.estimate")),
-          // The provider-reported prompt of the last request is the best
-          // ground truth for what the model actually received; the fixed
-          // density heuristic can undercount CJK-heavy content, so show the
-          // real number alongside the estimate.
-          displayRequests.length > 0 && displayRequests[displayRequests.length - 1].prompt !== void 0 ? h(
-            "span",
-            { className: "lc-actual" },
-            tr("overview.actual", { n: fmt3(displayRequests[displayRequests.length - 1].prompt ?? 0) })
-          ) : null
+          h("b", null, fmt3(headline)),
+          h("span", null, occupancyWindow ? " / " + fmt3(occupancyWindow) + " " + tr("overview.ofWindow", { p: headlinePct ?? 0 }) : " " + t("overview.estimate")),
+          occupancyTokens !== null ? h("span", { className: "lc-card-sub" }, t("overview.splitEst")) : null
         ),
-        h(StackedBar, { parts: partsOf(current), height: 16, max: data.contextWindow, hoverKey: hoverCat, onHoverKey: setHoverCat }),
-        h(Legend, { parts: partsOf(current), hoverKey: hoverCat, onHoverKey: setHoverCat }),
+        h(StackedBar, { parts, height: 16, max: occupancyWindow, hoverKey: hoverCat, onHoverKey: setHoverCat }),
+        h(Legend, { parts, hoverKey: hoverCat, onHoverKey: setHoverCat }),
         data.toolList && data.toolList.length > 0 ? h(
           "div",
           { className: "lc-tools" },

package/lib/index.js

@@ -94,6 +94,9 @@ function createFold() {
     provider: void 0,
     lastModel: void 0,
     contextWindow: void 0,
+    pressureTokens: void 0,
+    sampledSurfaceTokens: void 0,
+    occupancyWindow: void 0,
     requests: [],
     // one entry per answered model call
     events: [],
@@ -147,8 +150,22 @@ function applySurface(st, ev, type, data, message) {
     const utext = firstText(message?.content);
     if (utext !== "") node.text = utext;
   }
+  const shadowedSeqs = st.pendingShadowedSeqs;
+  st.pendingShadowedSeqs = void 0;
   const op = ev.surfaceOp;
   if (op !== null && typeof op === "object" && op.op === "replace") {
+    if (Array.isArray(shadowedSeqs) && shadowedSeqs.length > 0) {
+      const shadowed = new Set(shadowedSeqs);
+      const kept = [];
+      for (const n of st.surface) {
+        if (shadowed.has(n.seq)) st.sums[n.cat] -= n.tokens;
+        else kept.push(n);
+      }
+      st.surface = kept;
+      st.sums[cat] += node.tokens;
+      st.surface.push(node);
+      return node;
+    }
     let si = -1;
     let ei = -1;
     for (let i = 0; i < st.surface.length; i++) {
@@ -169,6 +186,16 @@ function applySurface(st, ev, type, data, message) {
   st.sums[cat] += node.tokens;
   return node;
 }
+function pressureOf(usage) {
+  if (usage === void 0 || typeof usage.inputTokens !== "number") return void 0;
+  return usage.inputTokens + (usage.cacheReadTokens || 0) + (usage.cacheWriteTokens || 0);
+}
+function sampleUsage(st, usage) {
+  const pressureTokens = pressureOf(usage);
+  if (pressureTokens === void 0) return;
+  st.pressureTokens = pressureTokens;
+  st.sampledSurfaceTokens = st.sums.user + st.sums.inject + st.sums.assistant + st.sums.tool;
+}
 function foldInto(st, events) {
   for (let e = st.n; e < events.length; e++) {
     const ev = events[e];
@@ -196,6 +223,7 @@ function foldInto(st, events) {
         if (data && typeof data.contextWindow === "number") st.contextWindow = data.contextWindow;
         if (data && typeof data.model === "string") st.model = data.model;
         if (data && typeof data.provider === "string") st.provider = data.provider;
+        st.occupancyWindow = data && typeof data.contextWindow === "number" ? data.contextWindow : void 0;
         break;
       case "tool/call":
         if (data && data.callId !== void 0 && typeof data.name === "string") st.callNames[String(data.callId)] = data.name;
@@ -227,8 +255,14 @@ function foldInto(st, events) {
         applySurface(st, ev, ev.type, data, toolMsg);
         break;
       }
+      case "assistant/chunk": {
+        const chunk = data?.chunk;
+        if (chunk !== void 0 && chunk.type === "usage") sampleUsage(st, chunk.usage);
+        break;
+      }
       case "assistant/message": {
         const usage = data?.usage;
+        sampleUsage(st, usage);
         const total = st.systemTokens + st.toolsTokens + st.sums.user + st.sums.inject + st.sums.assistant + st.sums.tool;
         const record = {
           turn: data && typeof data.turn === "number" ? data.turn : void 0,
@@ -253,6 +287,9 @@ function foldInto(st, events) {
         break;
       }
       case "compaction/summary":
+        if (data && Array.isArray(data.shadowedSeqs)) {
+          st.pendingShadowedSeqs = data.shadowedSeqs.filter((s) => typeof s === "number");
+        }
         st.events.push({
           seq: ev.seq,
           time: ev.time,
@@ -262,6 +299,9 @@ function foldInto(st, events) {
         });
         break;
       case "compaction/prune":
+        if (data && Array.isArray(data.shadowedSeqs)) {
+          st.pendingShadowedSeqs = data.shadowedSeqs.filter((s) => typeof s === "number");
+        }
         st.events.push({
           seq: ev.seq,
           time: ev.time,
@@ -284,6 +324,7 @@ function foldInto(st, events) {
 // src/host/snapshot.ts
 function buildResult(st) {
   const surfaceTotal = st.sums.user + st.sums.inject + st.sums.assistant + st.sums.tool;
+  const projectedTokens = st.pressureTokens !== void 0 && st.sampledSurfaceTokens !== void 0 ? Math.max(0, st.pressureTokens + surfaceTotal - st.sampledSurfaceTokens) : void 0;
   const result = {
     ok: true,
     model: st.model,
@@ -298,6 +339,13 @@ function buildResult(st) {
       tool: st.sums.tool,
       total: surfaceTotal + st.systemTokens + st.toolsTokens
     },
+    occupancy: {
+      ...st.pressureTokens === void 0 ? {} : { pressureTokens: st.pressureTokens },
+      surfaceTokens: surfaceTotal,
+      ...st.sampledSurfaceTokens === void 0 ? {} : { sampledSurfaceTokens: st.sampledSurfaceTokens },
+      ...projectedTokens === void 0 ? {} : { projectedTokens },
+      ...st.occupancyWindow === void 0 ? {} : { contextWindow: st.occupancyWindow }
+    },
     toolList: st.toolList,
     requests: st.requests,
     events: st.events,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Context insight panel for DeepSeek Harness: see what the model's context window is made of and how it evolves — composition, per-request history, compactions, injections, and model switches.",
   "author": "bowenliang123",
   "repository": {