dsh-rewind-plugin 0.7.1 → 0.7.2

package/README.md

@@ -145,6 +145,10 @@ dsh plugin --profile web add dsh-rewind-plugin
 4. **v0.3.3 及更早版本**回退过的会话，压缩对话（compact）不可用。新版本已兼容；受影响的旧会话建议新建会话。
 5. **导轨显示已回退轮次**——DSH `v0.1.2-alpha.1` 新增的右侧导轨，会为已撤回消息保留刻度：点击不跳转、悬浮显示已撤回正文。仅显示差异，无功能影响。
 
+> [!NOTE]
+> 若使用中遇到问题，可开启详细诊断输出，复现后附上控制台 `[dsh-rewind]` 输出便于定位。详见
+> [浏览器诊断与详细输出开关](docs/compat/diagnostics.zh.md)。
+
 ## 安全
 
 本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和代码」时被改写，备份存储于 `~/.dsh/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的全局自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。

package/docs/README.md

@@ -15,6 +15,7 @@ index/navigation entry point.
 | `contract/client-contract.md` | Rewind visibility contract for third-party DOM plugins (`.zh` mirror) | integrators |
 | `compat/audit.md` | Compatibility audit: verified surfaces, recorded findings, probe matrix | maintainers |
 | `compat/troubleshooting.md` | Known issues & repair steps (`.zh` mirror) | users / maintainers |
+| `compat/diagnostics.md` | Browser diagnostics & the verbose output switch (`.zh` mirror) | users / maintainers |
 | `release/release.md` | Release workflow & DSH peer-version alignment (`.zh` mirror) | maintainers |
 
 Repo-root docs outside `docs/`: `SECURITY.md` (security model) and

package/docs/compat/diagnostics.md

@@ -0,0 +1,82 @@
+# Browser diagnostics and the verbose switch
+
+[简体中文](diagnostics.zh.md)
+
+Every browser-side diagnostic this plugin emits goes through one small
+channel, so a report can be captured with a single console filter and a
+verbose mode can be switched on without a plugin rebuild.
+
+## Scope-prefixed output
+
+Diagnostics are printed as `[dsh-rewind:<scope>] ...`. The scope names the
+subsystem, and is also what the verbose switch filters on:
+
+| Scope | What it reports |
+| --- | --- |
+| `hiding` | The row-hiding path (which rows a rewind cuts; the `rewind not hidden` anomaly) |
+| `refill` | The composer refill after a rewind (target seq, mode, used channel, write result) |
+| `portals` | Per-message button mount issues (e.g. no session binding) |
+| `settings` | The snapshot-cleanup settings card |
+
+## Levels
+
+| Level | Default | Meaning |
+| --- | --- | --- |
+| `error` | on | Unexpected/breaking; always printed |
+| `warn` | on | Recoverable anomaly guard (`rewind not hidden`, `refill skipped/refused/threw`); always printed |
+| `info` | off | Event-level lifecycle (one line per rewind / refill) |
+| `debug` | off | Additional event-level detail behind the switch (the hide-set line, one per rewind) |
+
+`error`/`warn` are always printed so an anomaly surfaces even for a user who
+never touched the switch; `info`/`debug` are gated so a normal user's console
+stays clean. Both gated levels emit once per relevant event (a rewind, a
+refill), never per streaming frame — so a rewound session does not flood the
+console even with verbose output switched on.
+
+## Enabling verbose output
+
+The switch lives in the **browser's** `localStorage` under the plugin's own
+key, so it can never enable another plugin/feature and nothing else can wake
+this one. Set it, reload the page, reproduce, then filter the console for
+`[dsh-rewind]`:
+
+```js
+// Every dsh-rewind namespace.
+localStorage['dsh-rewind.debug'] = 'dsh-rewind*'
+
+// Or just the subsystem you care about (exact scope match).
+localStorage['dsh-rewind.debug'] = 'dsh-rewind:refill'
+
+// Several at once (comma-separated).
+localStorage['dsh-rewind.debug'] = 'dsh-rewind:refill,dsh-rewind:hiding'
+```
+
+Reload (`F5`) after setting it. To switch it off:
+
+```js
+delete localStorage['dsh-rewind.debug']
+```
+
+## Capturing a report
+
+1. On the machine/browser page that reproduces the problem, enable the
+   relevant namespace (see above) and reload.
+2. Reproduce once.
+3. In DevTools, filter the Console for `[dsh-rewind]` and copy the output
+   (with the plugin version and the DSH/kernel version).
+
+For a rewind that did not refill the composer, the `refill` scope is what
+matters: its `composer write` line reports whether the draft was restored
+through the harness facade (`facade`) or the DOM fallback (`dom`) and whether
+the write succeeded, which tells a plugin fault apart from a harness-side
+render desync.
+
+## Notes
+
+- The switch is an aid for maintainers and cooperating reporters, **not** a
+  stable public interface; its exact keys and output may change without notice.
+- It is scoped to one browser origin and one browser; enable it where the
+  problem actually occurs.
+
+Related: [audit.md](audit.md) for the verified-compatibility matrix and
+[troubleshooting.md](troubleshooting.md) for the legacy repair steps.

package/docs/compat/diagnostics.zh.md

@@ -0,0 +1,63 @@
+# 浏览器诊断与详细输出开关
+
+[English](diagnostics.md)
+
+本插件在浏览器端输出的所有诊断信息都经由同一条通道，这样可用一个控制台过滤器抓取报告，且无需重建插件即可开启详细输出模式。
+
+## 按作用域前缀输出
+
+诊断以 `[dsh-rewind:<scope>] ...` 形式打印。`scope` 标明子系统，同时也正是详细输出开关的过滤依据：
+
+| scope | 报告内容 |
+| --- | --- |
+| `hiding` | 行隐藏路径（回退切断哪些行；`rewind not hidden` 异常） |
+| `refill` | 回退后的输入框回填（目标 seq、模式、所用通道、写入结果） |
+| `portals` | 每条消息按钮的挂载问题（如无会话绑定） |
+| `settings` | 快照清理设置卡片 |
+
+## 分级
+
+| 级别 | 默认 | 含义 |
+| --- | --- | --- |
+| `error` | 开 | 意外/破坏性；总是打印 |
+| `warn` | 开 | 可恢复的异常护栏（`rewind not hidden`、`refill skipped/refused/threw`）；总是打印 |
+| `info` | 关 | 事件级生命周期（每次回退/回填一行） |
+| `debug` | 关 | 开关控制下的追加事件级细节（隐藏集一行，每次回退一行） |
+
+`error`/`warn` 总是打印，这样即使没碰过开关的用户，异常也会浮现；`info`/`debug` 则受开关控制，保持普通用户控制台干净。两个受控级别都按**相关事件触发一次**（一次回退、一次回填)，不会随流式逐帧打印——所以即使开了详细输出，回退后的会话也不会刷屏。
+
+## 开启详细输出
+
+开关位于**浏览器**的 `localStorage`、且使用插件专属键，因此它不会开启其它插件/功能，别的功能也无法唤醒本插件。设置后刷新页面、复现一次，再把控制台按 `[dsh-rewind]` 过滤即可：
+
+```js
+// 全部 dsh-rewind 命名空间。
+localStorage['dsh-rewind.debug'] = 'dsh-rewind*'
+
+// 或只开所关心的子系统（精确 scope 匹配）。
+localStorage['dsh-rewind.debug'] = 'dsh-rewind:refill'
+
+// 同时开多个（逗号分隔）。
+localStorage['dsh-rewind.debug'] = 'dsh-rewind:refill,dsh-rewind:hiding'
+```
+
+设置后刷新（`F5`）。关闭：
+
+```js
+delete localStorage['dsh-rewind.debug']
+```
+
+## 采集一段报告
+
+1. 在**复现问题的那台机器/那个浏览器页面**，开启相应命名空间（见上）并刷新。
+2. 复现一次。
+3. 在 DevTools 里把 Console 按 `[dsh-rewind]` 过滤，复制输出（连同插件版本、DSH/内核版本）。
+
+对「回退后没回填输入框」这类问题，重点是 `refill` 作用域：其 `composer write` 一行会报告草稿是通过 harness facade（`facade`）还是 DOM 回退（`dom`）恢复、写入是否成功，从而区分「插件没写入」与「harness 侧渲染不同步」。
+
+## 备注
+
+- 该开关是维护者与配合排查者使用的工具，**不是**稳定公开接口；其具体键与输出可能不经通知而改变。
+- 它受单个浏览器 origin、单个浏览器限定；请在实际出问题的地方开启。
+
+相关：[audit.md](audit.md) 为已验证兼容矩阵，[troubleshooting.md](troubleshooting.md) 为历史修复步骤。

package/lib/client.js

@@ -650,8 +650,8 @@ async function previewImpact(session, chatOf, seq) {
   if (!result.ok || result.value?.matched !== true) return null;
   return waitForCommand(session, chatOf, (node) => isPreviewFor(node, seq) && !known.has(node.seq));
 }
-function el(tag, className, text) {
-  const node = document.createElement(tag);
+function el(tag2, className, text) {
+  const node = document.createElement(tag2);
   node.className = className;
   if (text !== void 0) node.textContent = text;
   return node;
@@ -931,6 +931,48 @@ function retractSpan(steering, targetId) {
   return steering.slice(index).map((item) => item.id);
 }
 
+// src/client/log.ts
+var NS = "dsh-rewind";
+var DEBUG_KEY = "dsh-rewind.debug";
+var ALWAYS_ON = /* @__PURE__ */ new Set(["error", "warn"]);
+function switchValue() {
+  try {
+    return window.localStorage.getItem(DEBUG_KEY) ?? "";
+  } catch {
+    return "";
+  }
+}
+function matches(value, ns) {
+  for (const entry of value.split(",")) {
+    const part = entry.trim();
+    if (part === "") continue;
+    if (part === "*" || part === `${NS}*`) return true;
+    if (part.endsWith("*")) {
+      if (ns.startsWith(part.slice(0, -1))) return true;
+    } else if (ns === part) {
+      return true;
+    }
+  }
+  return false;
+}
+function tag(scope) {
+  return `[${NS}:${scope}]`;
+}
+function log(level, scope, message, data) {
+  if (ALWAYS_ON.has(level)) {
+    console[level](tag(scope), message, data);
+    return;
+  }
+  if (!matches(switchValue(), `${NS}:${scope}`)) return;
+  console.info(tag(scope), message, data);
+}
+var rewindLog = {
+  error: (scope, message, data) => log("error", scope, message, data),
+  warn: (scope, message, data) => log("warn", scope, message, data),
+  info: (scope, message, data) => log("info", scope, message, data),
+  debug: (scope, message, data) => log("debug", scope, message, data)
+};
+
 // src/client/portals.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 function fillComposerTextarea(text) {
@@ -985,18 +1027,73 @@ function userNodeOf(chat, key) {
 }
 async function runRewindAndFill(session, seq, mode, currentSessionId, chatOf, setComposerText) {
   const known = knownCommandSeqs(session, chatOf, (node) => isExecutedRewindCommand(node, seq));
-  const result = await session.command(`/rewind @${seq} ${mode}`);
-  if (!result.ok || result.value?.matched !== true) return;
-  const outcome = await waitForCommand(session, chatOf, (node) => isExecutedRewindCommand(node, seq) && !known.has(node.seq), 2e4);
-  if (outcome === null) return;
+  let result;
+  try {
+    result = await session.command(`/rewind @${seq} ${mode}`);
+  } catch (error) {
+    rewindLog.warn("refill", `rewind command threw, skipping refill @${seq}`, error);
+    return;
+  }
+  if (!result.ok || result.value?.matched !== true) {
+    rewindLog.info("refill", `rewind @${seq} not matched, no refill`);
+    return;
+  }
+  let outcome;
+  try {
+    outcome = await waitForCommand(session, chatOf, (node) => isExecutedRewindCommand(node, seq) && !known.has(node.seq), 2e4);
+  } catch (error) {
+    rewindLog.warn("refill", `waiting for rewind @${seq} outcome threw`, error);
+    return;
+  }
+  if (outcome === null) {
+    rewindLog.warn("refill", `rewind @${seq} never settled within timeout, no refill`);
+    return;
+  }
   if (outcome.kind !== "success") {
+    rewindLog.warn("refill", `rewind @${seq} refused`, outcome.text);
     showHint(outcome.text ?? "rewind failed");
     return;
   }
-  if (currentSessionId() !== session.sessionId) return;
-  const text = messageTextAt(chatOf(session), seq);
-  if (text === void 0 || text === "") return;
-  setComposerText(session.sessionId, text);
+  const hidSeqs = (() => {
+    const chat = chatOf(session);
+    return chat === void 0 ? /* @__PURE__ */ new Set() : hiddenSeqsOf(chat);
+  })();
+  if (hidSeqs.size === 0) {
+    rewindLog.warn("hiding", `rewind not hidden (target @${seq})`, { target: seq });
+  } else {
+    rewindLog.debug(
+      "hiding",
+      `rewind hides seqs [${[...hidSeqs].slice(0, 20).join(", ")}${hidSeqs.size > 20 ? "\u2026" : ""}]`,
+      { target: seq }
+    );
+  }
+  if (currentSessionId() !== session.sessionId) {
+    rewindLog.info("refill", `skipped refill @${seq}: session switched during rewind`);
+    return;
+  }
+  let text;
+  try {
+    text = messageTextAt(chatOf(session), seq);
+  } catch (error) {
+    rewindLog.warn("refill", `reading target text for @${seq} threw`, error);
+    return;
+  }
+  if (text === void 0 || text === "") {
+    rewindLog.info("refill", `skipped refill @${seq}: no editable text`);
+    return;
+  }
+  if (composerText().trim() !== "") {
+    rewindLog.info("refill", `skipped refill @${seq}: composer already has a draft`);
+    return;
+  }
+  let ok = false;
+  try {
+    ok = setComposerText(session.sessionId, text);
+  } catch (error) {
+    rewindLog.warn("refill", `composer refill @${seq} threw`, error);
+    return;
+  }
+  rewindLog.info("refill", `rewound to @${seq} (${mode})`, { ok, text: text.slice(0, 80) });
 }
 function composerSurface() {
   return document.querySelector(COMPOSER_TEXTAREA_SELECTOR) ?? document.querySelector(COMPOSER_EDITABLE_SELECTOR);
@@ -1092,40 +1189,6 @@ function sameTargets(left, right) {
     return other.kind === "pending" && target.itemId === other.itemId;
   });
 }
-function hasExecutedRewindCommand(chat) {
-  for (const key of chat.order) {
-    const node = chat.nodes.get(key);
-    if (node === void 0 || node.kind !== "command") continue;
-    const command = node.data;
-    if (command.name !== "rewind") continue;
-    const args = command.args ?? "";
-    if (args.includes("preview") || args.includes("__candidates")) continue;
-    return true;
-  }
-  return false;
-}
-function describeHiding(chat, hiddenSeqs) {
-  const commands = [];
-  for (const key of chat.order) {
-    const node = chat.nodes.get(key);
-    if (node === void 0 || node.kind !== "command") continue;
-    const c = node.data;
-    commands.push(`#${c.seq} name=${c.name} outcome=${c.outcome?.kind ?? "-"} marker=${c.outcome?.sourceEventSeq ?? "-"} args=${JSON.stringify(c.args)}`);
-  }
-  const scoped = hiddenSeqs.size > 0 ? `hidden=[${[...hiddenSeqs].slice(0, 20).join(",")}${hiddenSeqs.size > 20 ? "\u2026" : ""}]` : "";
-  let seats = 0;
-  let resolved = 0;
-  let inHidden = 0;
-  for (const seat of document.querySelectorAll(CHAT_SEAT_SELECTOR)) {
-    seats += 1;
-    const key = seat.dataset.chatAnchorKey;
-    const node = key === void 0 ? void 0 : chat.nodes.get(key);
-    if (node === void 0) continue;
-    resolved += 1;
-    if (hiddenSeqs.has(node.anchorSeq)) inHidden += 1;
-  }
-  return `commands=[${commands.join(" | ")}] ${scoped} seats=${seats} resolved=${resolved} inHidden=${inHidden}`;
-}
 function RewindPortals({ sessionId, sessionOf, chatOf, currentSessionId, t, subscribeLocale, setComposerText }) {
   const [targets, setTargets] = (0, import_react.useState)([]);
   const hidden = (0, import_react.useRef)(/* @__PURE__ */ new WeakSet());
@@ -1146,7 +1209,6 @@ function RewindPortals({ sessionId, sessionOf, chatOf, currentSessionId, t, subs
       const snapshot = session.getSnapshot();
       const chat = chatOf(session);
       const hiddenSeqs = chat === void 0 ? /* @__PURE__ */ new Set() : hiddenSeqsOf(chat);
-      let hiddenCount = 0;
       for (const seat of chat === void 0 ? [] : document.querySelectorAll(CHAT_SEAT_SELECTOR)) {
         const key = seat.dataset.chatAnchorKey;
         const anchor = key !== void 0 ? chat?.nodes.get(key)?.anchorSeq : void 0;
@@ -1154,21 +1216,12 @@ function RewindPortals({ sessionId, sessionOf, chatOf, currentSessionId, t, subs
           seat.style.display = "none";
           seat.dataset.dshRewindHidden = "true";
           hidden.current.add(seat);
-          hiddenCount += 1;
         } else if (hidden.current.has(seat)) {
           seat.style.display = "";
           delete seat.dataset.dshRewindHidden;
           hidden.current.delete(seat);
         }
       }
-      if (hiddenSeqs.size > 0 || hiddenCount > 0) {
-        console.info(
-          `[dsh-rewind] hiding: ${hiddenCount} rows, seqs [${[...hiddenSeqs].slice(0, 20).join(", ")}${hiddenSeqs.size > 20 ? "\u2026" : ""}]`
-        );
-      }
-      if (chat !== void 0 && hiddenCount === 0 && hasExecutedRewindCommand(chat)) {
-        console.warn(`[dsh-rewind] rewind not hidden: ${describeHiding(chat, hiddenSeqs)}`);
-      }
       const durable = chat === void 0 ? [] : collectTargets(chat, hiddenSeqs);
       const next = [...durable, ...collectPendingTargets(snapshot)];
       setTargets((current) => sameTargets(current, next) ? current : next);
@@ -1223,7 +1276,7 @@ function RewindButton({ target, sessionId, sessionOf, chatOf, currentSessionId,
     event.stopPropagation();
     const session = sessionOf(sessionId);
     if (session === void 0) {
-      console.warn("[dsh-rewind] rewind button clicked with no session binding");
+      rewindLog.warn("portals", "rewind button clicked with no session binding");
       return;
     }
     const node = userNodeOf(chatOf(session), target.key);
@@ -1559,14 +1612,14 @@ function SettingsCleanupCard({ api, t }) {
 // src/client/index.ts
 var name = "dsh-rewind";
 var inject = ["slots", "sessions", "locale", "commandUi"];
-var NS = "rewind";
+var NS2 = "rewind";
 var HEADER_ACTIONS_SLOT = "conversation.session.header.actions";
 var COMPOSER_TEXTAREA_SELECTOR2 = "[data-input-scroll] textarea, textarea[data-phase]";
 var COMPOSER_EDITABLE_SELECTOR2 = "[data-composer-input]";
 function apply(ctx) {
   ctx.effect(function* () {
-    yield ctx.locale.register(NS, { zh, en });
-    const t = ctx.locale.bind(NS);
+    yield ctx.locale.register(NS2, { zh, en });
+    const t = ctx.locale.bind(NS2);
     const style = document.createElement("style");
     style.dataset.plugin = "dsh-rewind";
     style.textContent = STYLE;
@@ -1586,15 +1639,23 @@ function apply(ctx) {
       }
     };
     const setComposerText = (sessionId, text) => {
-      const conversation = ctx.get("conversation");
-      const input = conversation?.input;
-      const scope = ctx.sessions.scope?.(sessionId);
-      return writeComposer(
-        text,
-        input !== void 0 && scope !== void 0 ? { setDraft: (draft) => {
-          input.for(scope).setDraft(draft);
-        } } : void 0
-      );
+      try {
+        const conversation = ctx.get("conversation");
+        const input = conversation?.input;
+        const scope = ctx.sessions.scope?.(sessionId);
+        const facade = input !== void 0 && scope !== void 0;
+        const ok = writeComposer(
+          text,
+          facade ? { setDraft: (draft) => {
+            input.for(scope).setDraft(draft);
+          } } : void 0
+        );
+        rewindLog.info("refill", "composer write", { channel: facade ? "facade" : "dom", ok });
+        return ok;
+      } catch (error) {
+        rewindLog.warn("refill", "composer write threw", error);
+        return false;
+      }
     };
     const slots = ctx.slots;
     yield slots.inject(HEADER_ACTIONS_SLOT, () => slots.register(
@@ -1632,13 +1693,13 @@ function apply(ctx) {
             // Match the official cards / dsh-market: locale + inject provide
             // the card its props through the slot renderer (the keyed card owns
             // its internals, but the page feeds it locale + the bound api).
-            locale: NS,
+            locale: NS2,
             inject: () => ({ t, api: cardApi })
           },
           SettingsCleanupCard
         ));
       } catch (error) {
-        console.error("[dsh-rewind] settings card register failed:", error);
+        rewindLog.error("settings", "settings card register failed", error);
       }
     });
     const commandUi = ctx.get("commandUi");

package/lib/types/client/log.d.ts

@@ -0,0 +1,43 @@
+/**
+ * dsh-rewind client logger: a single, namespaced, level-filtered logging
+ * channel for every browser-side diagnostic in this plugin.
+ *
+ * Design (industry-normal layering, kept dependency-free):
+ * - `error` / `warn` are ALWAYS emitted (they are the anomaly guard: rare,
+ *   cheap, and must surface even for a user who never touched the switch).
+ * - `info` / `debug` are gated by a DEBUG switch and further filtered by
+ *   namespace, so verbose detail never floods a normal user's console.
+ *
+ * The DEBUG switch is a runtime, per-origin knob read from
+ * `localStorage['dsh-rewind.debug']` — the convention-debug-scan pattern
+ * (namespace match, comma-separated, `*` wildcard), scoped to an
+ * exclusively-own key so it can never enable any other plugin/feature and no
+ * other feature can wake this one. Because it is read on every call (never
+ * cached), flipping it and reloading takes effect on any published build
+ * without a plugin rebuild.
+ *
+ * Values accepted by the switch (empty/unset = off):
+ * - `dsh-rewind*`  — every dsh-rewind namespace.
+ * - `dsh-rewind:refill` — just one subsystem (exact match).
+ * - `dsh-rewind:refill,dsh-rewind:hiding` — several (comma-separated).
+ *
+ * @module dsh-rewind/client/log
+ */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/**
+ * Emit one diagnostic line. `error`/`warn` always print; `info`/`debug` print
+ * only when the DEBUG switch selects the namespace. Both gated levels are
+ * routed to the always-visible `console.info` rather than `console.debug`,
+ * whose "Verbose" level Chrome filters out by default — otherwise a reporter
+ * who turns the switch on still would not see the line without also changing
+ * the DevTools level filter (mapped to `console.debug`). `data` is spread last
+ * so DevTools' structured view keeps it inspectable (never stringified).
+ */
+export declare function log(level: LogLevel, scope: string, message: string, data?: unknown): void;
+/** Convenience shorthands (typed so call sites read cleanly). */
+export declare const rewindLog: {
+    readonly error: (scope: string, message: string, data?: unknown) => void;
+    readonly warn: (scope: string, message: string, data?: unknown) => void;
+    readonly info: (scope: string, message: string, data?: unknown) => void;
+    readonly debug: (scope: string, message: string, data?: unknown) => void;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "DSH 插件：真正便捷无感的同窗口内对话回退，从不新建分支；自带轻量工作区备份，可一并还原文件（完整 Claude Code /rewind 语义）。 · DSH plugin: genuinely effortless in-window conversation rewind — never forking a new session; ships a lightweight workspace backup that restores files together with the rewind (full Claude Code /rewind semantics).",
   "keywords": [
     "deepseek-harness",