@co0ontty/wand 1.26.0 → 1.29.1

package/dist/web-ui/content/scripts.js

@@ -123,6 +123,9 @@
         sidebarPinned: (function() {
           try { return localStorage.getItem("wand-sidebar-pinned") === "true"; } catch (e) { return false; }
         })(),
+        sidebarCollapsed: (function() {
+          try { return localStorage.getItem("wand-sidebar-collapsed") === "true"; } catch (e) { return false; }
+        })(),
         modalOpen: false,
         presetValue: "",
         cwdValue: "",
@@ -150,6 +153,11 @@
         showInstallPrompt: false,
         ws: null,
         wsConnected: false,
+        // 上一次从服务器收到任意 WS 消息（包括 ping）的时间戳。心跳 stale 检测
+        // 用它来判断半开连接：长时间没消息 → forceReconnect。0 表示尚未连接过。
+        lastWsMessageAt: 0,
+        // 心跳检查 timer 句柄。每 10s 跑一次 evaluateWsHeartbeatStale()。
+        wsHeartbeatCheckTimer: null,
         _updateBubbleShown: false,
         notificationHistory: {},
         delayedNotificationTimer: null,
@@ -199,15 +207,14 @@
         // Whether the commit is also tagged is controlled by `makeTag` independently —
         // that keeps "commit + tag, push later" possible.
         quickCommitForm: { customMessage: "", makeTag: false, tag: "", primaryAction: "commit" },
-        quickCommitActionMenuOpen: false,
-        // Secondary "tag the existing HEAD" panel (inline drawer).
-        quickCommitTagHeadOpen: false,
+        // Which inline panel/dropdown is open. Only one can be open at a time, so a
+        // single field beats juggling three sibling booleans with mutual-exclusion code.
+        // Values: null | "action" | "push" | "tag-head".
+        quickCommitOpenMenu: null,
         quickCommitTagHeadForm: { tag: "", push: false },
         quickCommitTagHeadSubmitting: false,
         quickCommitTagHeadGenerating: false,
         quickCommitTagHeadError: "",
-        // Secondary "push only" controls.
-        quickCommitPushMenuOpen: false,
         quickCommitPushing: false,
         quickCommitPushError: "",
         // Telegram 风格的"贴底"状态：true = 用户当前贴在底部，新消息会自然出现；
@@ -1027,6 +1034,11 @@
       function syncOnForeground(reason, force) {
         if (!state.config) return Promise.resolve();
         if (document.hidden) return Promise.resolve();
+        // 切回前台时立刻评估一次心跳 stale。setInterval 在 background 会被
+        // 浏览器节流（最低 1Hz，部分浏览器更慢），所以如果挂了 1 分钟回来，
+        // 不主动跑这一次的话要等到下一个 10s tick 才会发现，前 10s 会继续
+        // 往一条死 socket 上推消息。
+        evaluateWsHeartbeatStale();
         // On Android resume the previous WS may still report OPEN/CONNECTING
         // for a few seconds because the close frame hasn't been delivered
         // yet (TCP keepalive / Doze suspended the network stack). Force a
@@ -1168,6 +1180,10 @@
               if (_apkVersion) {
                 checkApkAutoUpdate();
               }
+              // macOS DMG auto-update check on startup
+              if (_macAppVersion) {
+                checkDmgAutoUpdate();
+              }
               if (state.claudeHistoryExpanded && !state.claudeHistoryLoaded) {
                 loadClaudeHistory();
               }
@@ -1412,6 +1428,9 @@
                   '<button id="sidebar-pin-btn" class="btn btn-ghost btn-sm sidebar-pin-toggle' + (state.sidebarPinned ? ' pinned' : '') + '" type="button" title="' + (state.sidebarPinned ? '取消固定侧栏' : '固定侧栏') + '">' +
                     '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17h14v-1.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1v4.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24z"/></svg>' +
                   '</button>' +
+                  '<button id="sidebar-collapse-btn" class="btn btn-ghost btn-sm sidebar-collapse-toggle" type="button" title="收起为窄条" aria-label="收起为窄条">' +
+                    '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="14 6 8 12 14 18"/><line x1="4" y1="5" x2="4" y2="19"/></svg>' +
+                  '</button>' +
                   '<button id="close-drawer-button" class="btn btn-ghost btn-icon sidebar-close drawer-close-btn" type="button" aria-label="关闭菜单"><svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" aria-hidden="true"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg></button>' +
                 '</div>' +
               '</div>' +
@@ -1816,13 +1835,11 @@
           tag: "",
           primaryAction: readSavedPrimaryAction(),
         };
-        state.quickCommitActionMenuOpen = false;
-        state.quickCommitTagHeadOpen = false;
+        state.quickCommitOpenMenu = null;
         state.quickCommitTagHeadForm = { tag: "", push: false };
         state.quickCommitTagHeadSubmitting = false;
         state.quickCommitTagHeadGenerating = false;
         state.quickCommitTagHeadError = "";
-        state.quickCommitPushMenuOpen = false;
         state.quickCommitPushing = false;
         state.quickCommitPushError = "";
         closeWorktreeMergeModal();
@@ -1839,10 +1856,8 @@
         quickCommitEscHandler = function(e) {
           if (e.key === "Escape" && state.quickCommitOpen && !state.quickCommitSubmitting && !state.quickCommitTagHeadSubmitting && !state.quickCommitPushing) {
             // First Esc closes any open dropdown; second closes the modal.
-            if (state.quickCommitActionMenuOpen || state.quickCommitPushMenuOpen || state.quickCommitTagHeadOpen) {
-              state.quickCommitActionMenuOpen = false;
-              state.quickCommitPushMenuOpen = false;
-              state.quickCommitTagHeadOpen = false;
+            if (state.quickCommitOpenMenu) {
+              state.quickCommitOpenMenu = null;
               rerenderQuickCommitModal();
               return;
             }
@@ -1853,18 +1868,16 @@
         if (quickCommitDocClickHandler) document.removeEventListener("click", quickCommitDocClickHandler, true);
         quickCommitDocClickHandler = function(e) {
           if (!state.quickCommitOpen) return;
+          // tag-head is an inline drawer, not a dropdown — clicking outside shouldn't close it.
+          if (state.quickCommitOpenMenu !== "action" && state.quickCommitOpenMenu !== "push") return;
           var modalEl = document.getElementById("quick-commit-modal");
           if (!modalEl) return;
-          var anyMenuOpen = state.quickCommitActionMenuOpen || state.quickCommitPushMenuOpen;
-          if (!anyMenuOpen) return;
-          // Click on the toggle itself? leave it to the toggle handler.
           var t = e.target;
           while (t && t !== modalEl) {
             if (t.dataset && (t.dataset.qcDropdownToggle || t.dataset.qcDropdownMenu)) return;
             t = t.parentNode;
           }
-          state.quickCommitActionMenuOpen = false;
-          state.quickCommitPushMenuOpen = false;
+          state.quickCommitOpenMenu = null;
           rerenderQuickCommitModal();
         };
         document.addEventListener("click", quickCommitDocClickHandler, true);
@@ -1878,9 +1891,7 @@
         state.quickCommitOpen = false;
         state.quickCommitSubmitting = false;
         state.quickCommitError = "";
-        state.quickCommitActionMenuOpen = false;
-        state.quickCommitPushMenuOpen = false;
-        state.quickCommitTagHeadOpen = false;
+        state.quickCommitOpenMenu = null;
         var modal = document.getElementById("quick-commit-modal");
         if (modal) modal.classList.add("hidden");
         if (focusTrapHandler) {
@@ -1918,7 +1929,6 @@
         var cancelBtn = document.getElementById("quick-commit-cancel-btn");
         if (cancelBtn) cancelBtn.addEventListener("click", closeQuickCommitModal);
 
-        // ── Section 1: commit form ──
         var submitBtn = document.getElementById("quick-commit-submit-btn");
         if (submitBtn) submitBtn.addEventListener("click", submitQuickCommit);
         var aiBtn = document.getElementById("quick-commit-ai-btn");
@@ -1938,12 +1948,10 @@
           state.quickCommitForm.tag = tagInput.value;
         });
 
-        // ── Primary action split-button (caret + dropdown) ──
         var actionCaret = document.getElementById("quick-commit-action-caret");
         if (actionCaret) actionCaret.addEventListener("click", function(e) {
           e.stopPropagation();
-          state.quickCommitActionMenuOpen = !state.quickCommitActionMenuOpen;
-          state.quickCommitPushMenuOpen = false;
+          state.quickCommitOpenMenu = state.quickCommitOpenMenu === "action" ? null : "action";
           rerenderQuickCommitModal();
         });
         var actionMenu = document.getElementById("quick-commit-action-menu");
@@ -1957,29 +1965,27 @@
                   state.quickCommitForm.primaryAction = value;
                   savePrimaryAction(value);
                 }
-                state.quickCommitActionMenuOpen = false;
+                state.quickCommitOpenMenu = null;
                 rerenderQuickCommitModal();
               });
             })(actionItems[i]);
           }
         }
 
-        // ── Section 2: Tag HEAD inline panel ──
         var tagHeadToggle = document.getElementById("quick-commit-tag-head-toggle");
         if (tagHeadToggle) tagHeadToggle.addEventListener("click", function() {
-          state.quickCommitTagHeadOpen = !state.quickCommitTagHeadOpen;
-          if (state.quickCommitTagHeadOpen) {
-            state.quickCommitTagHeadError = "";
-          }
+          var willOpen = state.quickCommitOpenMenu !== "tag-head";
+          state.quickCommitOpenMenu = willOpen ? "tag-head" : null;
+          if (willOpen) state.quickCommitTagHeadError = "";
           rerenderQuickCommitModal();
-          if (state.quickCommitTagHeadOpen) {
+          if (willOpen) {
             var inp = document.getElementById("quick-commit-tag-head-input");
             if (inp) inp.focus();
           }
         });
         var tagHeadCancel = document.getElementById("quick-commit-tag-head-cancel");
         if (tagHeadCancel) tagHeadCancel.addEventListener("click", function() {
-          state.quickCommitTagHeadOpen = false;
+          if (state.quickCommitOpenMenu === "tag-head") state.quickCommitOpenMenu = null;
           state.quickCommitTagHeadError = "";
           rerenderQuickCommitModal();
         });
@@ -2006,7 +2012,6 @@
           submitTagHead(false);
         });
 
-        // ── Section 2: Push split-button ──
         var pushBtn = document.getElementById("quick-commit-push-btn");
         if (pushBtn) pushBtn.addEventListener("click", function() {
           submitPushOnly({ pushCommits: true, pushTags: false });
@@ -2014,8 +2019,7 @@
         var pushCaret = document.getElementById("quick-commit-push-caret");
         if (pushCaret) pushCaret.addEventListener("click", function(e) {
           e.stopPropagation();
-          state.quickCommitPushMenuOpen = !state.quickCommitPushMenuOpen;
-          state.quickCommitActionMenuOpen = false;
+          state.quickCommitOpenMenu = state.quickCommitOpenMenu === "push" ? null : "push";
           rerenderQuickCommitModal();
         });
         var pushMenu = document.getElementById("quick-commit-push-menu");
@@ -2025,7 +2029,7 @@
             (function(btn) {
               btn.addEventListener("click", function() {
                 var value = btn.getAttribute("data-qc-push");
-                state.quickCommitPushMenuOpen = false;
+                state.quickCommitOpenMenu = null;
                 if (value === "commits") submitPushOnly({ pushCommits: true, pushTags: false });
                 else if (value === "tags") submitPushOnly({ pushCommits: false, pushTags: true });
                 else if (value === "both") submitPushOnly({ pushCommits: true, pushTags: true });
@@ -2119,7 +2123,11 @@
             var data = result.data || {};
             var hash = data.commit && data.commit.hash ? data.commit.hash.substring(0, 7) : "";
             var tagName = data.tag && data.tag.name ? data.tag.name : "";
-            var base = "已提交" + (hash ? " " + hash : "") + (tagName ? "，已打 tag " + tagName : "");
+            var subCommits = Array.isArray(data.submoduleCommits) ? data.submoduleCommits : [];
+            var subPrefix = subCommits.length > 0
+              ? "已先提交 " + subCommits.length + " 个 submodule（" + subCommits.map(function(c) { return c.path; }).join("、") + "），"
+              : "";
+            var base = subPrefix + "已提交" + (hash ? " " + hash : "") + (tagName ? "，已打 tag " + tagName : "");
             if (willPush && data.pushError) {
               var msg = base + "；push 失败：" + data.pushError;
               if (typeof showToast === "function") showToast(msg, "error");
@@ -2208,7 +2216,7 @@
             } else {
               if (typeof showToast === "function") showToast(base + (pushed ? "，已 push" : ""), "success");
             }
-            state.quickCommitTagHeadOpen = false;
+            if (state.quickCommitOpenMenu === "tag-head") state.quickCommitOpenMenu = null;
             state.quickCommitTagHeadForm = { tag: "", push: false };
             if (state.selectedId) loadGitStatus(state.selectedId, { force: true }).then(function() {
               if (state.quickCommitOpen) rerenderQuickCommitModal();
@@ -2223,7 +2231,6 @@
           });
       }
 
-      // Push without committing.
       function submitPushOnly(opts) {
         if (!state.selectedId || state.quickCommitPushing) return;
         var pushCommits = !!(opts && opts.pushCommits);
@@ -2267,7 +2274,6 @@
           });
       }
 
-      // Build the file list portion of the modal.
       function renderQuickCommitFileRows(files) {
         var rows = files.map(function(item) {
           var status = (item.status || "  ").substring(0, 2);
@@ -2293,15 +2299,19 @@
         return rows || '<div class="qc-empty">没有可提交的改动。</div>';
       }
 
-      // Primary action button label / icon.
+      function isQuickCommitOpInFlight() {
+        return state.quickCommitSubmitting || state.quickCommitTagHeadSubmitting || state.quickCommitPushing;
+      }
+
       function renderQuickCommitPrimary(hasChanges) {
         var f = state.quickCommitForm;
         var label;
         if (state.quickCommitSubmitting) label = "提交中…";
         else if (f.primaryAction === "commit-push") label = "提交并 push";
         else label = "仅提交";
-        var disabled = !hasChanges || state.quickCommitSubmitting || state.quickCommitTagHeadSubmitting || state.quickCommitPushing;
-        var caretActive = state.quickCommitActionMenuOpen ? " is-active" : "";
+        var disabled = !hasChanges || isQuickCommitOpInFlight();
+        var menuOpen = state.quickCommitOpenMenu === "action";
+        var caretActive = menuOpen ? " is-active" : "";
         var menuItems = [
           { value: "commit", label: "仅提交", desc: "只 commit，不 push" },
           { value: "commit-push", label: "提交并 push", desc: "commit 后立即 push 到远端" }
@@ -2317,36 +2327,32 @@
           '<button id="quick-commit-submit-btn" class="btn btn-primary qc-split-main" type="button"' + (disabled ? ' disabled' : '') + '>' +
             escapeHtml(label) +
           '</button>' +
-          '<button id="quick-commit-action-caret" class="btn btn-primary qc-split-caret' + caretActive + '" type="button" data-qc-dropdown-toggle="action"' + (disabled ? ' disabled' : '') + ' aria-haspopup="menu" aria-expanded="' + (state.quickCommitActionMenuOpen ? 'true' : 'false') + '" aria-label="更多提交方式">' +
+          '<button id="quick-commit-action-caret" class="btn btn-primary qc-split-caret' + caretActive + '" type="button" data-qc-dropdown-toggle="action"' + (disabled ? ' disabled' : '') + ' aria-haspopup="menu" aria-expanded="' + (menuOpen ? 'true' : 'false') + '" aria-label="更多提交方式">' +
             '<svg viewBox="0 0 12 12" width="10" height="10" aria-hidden="true"><path d="M2 4l4 4 4-4" stroke="currentColor" stroke-width="1.6" fill="none" stroke-linecap="round" stroke-linejoin="round"/></svg>' +
           '</button>' +
-          (state.quickCommitActionMenuOpen ?
+          (menuOpen ?
             '<div id="quick-commit-action-menu" class="qc-dropdown-menu" data-qc-dropdown-menu="action" role="menu">' + menuHtml + '</div>' : '') +
           '</div>';
       }
 
-      // Status chips (ahead/behind/unpushed tags) under the HEAD card.
       function renderQuickCommitStatusChips(s) {
         var chips = [];
+        var hasUpstream = !!s.upstream;
         if (typeof s.ahead === "number" && s.ahead > 0) {
           chips.push('<span class="qc-chip qc-chip--ahead" title="本地领先 ' + s.ahead + ' 个 commit">↑ ' + s.ahead + ' 待推送</span>');
         }
         if (typeof s.behind === "number" && s.behind > 0) {
           chips.push('<span class="qc-chip qc-chip--behind" title="远端领先 ' + s.behind + ' 个 commit">↓ ' + s.behind + ' 待拉取</span>');
         }
-        if (typeof s.unpushedTagCount === "number" && s.unpushedTagCount > 0) {
-          chips.push('<span class="qc-chip qc-chip--tag" title="' + s.unpushedTagCount + ' 个本地 tag 未推送">🏷 ' + s.unpushedTagCount + ' 待推送</span>');
-        }
-        if (s.hasUpstream === false) {
+        if (!hasUpstream) {
           chips.push('<span class="qc-chip qc-chip--warn" title="当前分支没有 upstream，将首次推送时自动设置">无 upstream</span>');
-        }
-        if (!chips.length && s.hasUpstream !== false) {
+        } else if (!chips.length) {
           chips.push('<span class="qc-chip qc-chip--clean">与远端同步</span>');
         }
         return '<div class="qc-status-chips">' + chips.join("") + '</div>';
       }
 
-      // Inline "tag HEAD" drawer rendering.
+      // Inline drawer used by the "为 HEAD 打 tag" toggle.
       function renderQuickCommitTagHeadPanel() {
         var thf = state.quickCommitTagHeadForm || { tag: "", push: false };
         var submitting = state.quickCommitTagHeadSubmitting;
@@ -2368,22 +2374,23 @@
         '</div>';
       }
 
-      // Push split-button on the secondary row.
       function renderQuickCommitPushButton(s) {
         var ahead = typeof s.ahead === "number" ? s.ahead : 0;
-        var unpushedTags = typeof s.unpushedTagCount === "number" ? s.unpushedTagCount : 0;
-        var canPushCommits = ahead > 0 || s.hasUpstream === false; // first-push lets you set upstream
-        var canPushTags = unpushedTags > 0;
-        // Allow pushing commits even without ahead info (e.g. ls-remote unreachable) — backend will report.
-        if (typeof s.ahead !== "number" && s.hasUpstream !== false) canPushCommits = true;
-        if (typeof s.unpushedTagCount !== "number") canPushTags = true; // unknown — let user try
-        var disabled = state.quickCommitPushing || state.quickCommitSubmitting || state.quickCommitTagHeadSubmitting || (!canPushCommits && !canPushTags);
+        var hasUpstream = !!s.upstream;
+        // Allow pushing commits if we're ahead, if upstream is missing (first push will set it up),
+        // or if ahead is simply unknown — backend will surface real errors.
+        var canPushCommits = ahead > 0 || !hasUpstream || typeof s.ahead !== "number";
+        // Tag count isn't computed locally (would require a network probe). Let the user try.
+        var canPushTags = true;
+        var disabled = isQuickCommitOpInFlight() || (!canPushCommits && !canPushTags);
         var mainLabel = state.quickCommitPushing ? "推送中…" : "推送";
-        var caretActive = state.quickCommitPushMenuOpen ? " is-active" : "";
-        var items = [];
-        items.push({ value: "commits", label: "推送 commits", desc: ahead ? "推送 " + ahead + " 个 commit" : "推送当前分支", disabled: !canPushCommits });
-        items.push({ value: "tags", label: "推送 tags", desc: unpushedTags ? "推送 " + unpushedTags + " 个本地 tag" : "推送所有本地 tag", disabled: !canPushTags });
-        items.push({ value: "both", label: "推送 commits 和 tags", desc: "二合一", disabled: !(canPushCommits || canPushTags) });
+        var menuOpen = state.quickCommitOpenMenu === "push";
+        var caretActive = menuOpen ? " is-active" : "";
+        var items = [
+          { value: "commits", label: "推送 commits", desc: ahead ? "推送 " + ahead + " 个 commit" : "推送当前分支", disabled: !canPushCommits },
+          { value: "tags", label: "推送 tags", desc: "推送所有本地 tag", disabled: !canPushTags },
+          { value: "both", label: "推送 commits 和 tags", desc: "二合一", disabled: !(canPushCommits || canPushTags) }
+        ];
         var menuHtml = items.map(function(it) {
           var dis = it.disabled ? " is-disabled" : "";
           return '<button type="button" class="qc-dropdown-item' + dis + '" data-qc-push="' + it.value + '"' + (it.disabled ? ' disabled' : '') + '>' +
@@ -2395,10 +2402,10 @@
           '<button id="quick-commit-push-btn" class="btn btn-secondary qc-split-main" type="button"' + (disabled ? ' disabled' : '') + '>' +
             escapeHtml(mainLabel) +
           '</button>' +
-          '<button id="quick-commit-push-caret" class="btn btn-secondary qc-split-caret' + caretActive + '" type="button" data-qc-dropdown-toggle="push"' + (disabled ? ' disabled' : '') + ' aria-haspopup="menu" aria-expanded="' + (state.quickCommitPushMenuOpen ? 'true' : 'false') + '" aria-label="更多推送方式">' +
+          '<button id="quick-commit-push-caret" class="btn btn-secondary qc-split-caret' + caretActive + '" type="button" data-qc-dropdown-toggle="push"' + (disabled ? ' disabled' : '') + ' aria-haspopup="menu" aria-expanded="' + (menuOpen ? 'true' : 'false') + '" aria-label="更多推送方式">' +
             '<svg viewBox="0 0 12 12" width="10" height="10" aria-hidden="true"><path d="M2 4l4 4 4-4" stroke="currentColor" stroke-width="1.6" fill="none" stroke-linecap="round" stroke-linejoin="round"/></svg>' +
           '</button>' +
-          (state.quickCommitPushMenuOpen ?
+          (menuOpen ?
             '<div id="quick-commit-push-menu" class="qc-dropdown-menu qc-dropdown-menu--right" data-qc-dropdown-menu="push" role="menu">' + menuHtml + '</div>' : '') +
           '</div>';
       }
@@ -2467,11 +2474,11 @@
               '<code class="qc-head-text">' + escapeHtml(headLine) + '</code>' +
             '</div>' +
             renderQuickCommitStatusChips(s) +
-            (state.quickCommitTagHeadOpen ? renderQuickCommitTagHeadPanel() : '') +
+            (state.quickCommitOpenMenu === "tag-head" ? renderQuickCommitTagHeadPanel() : '') +
             '<div class="qc-section-actions qc-section-actions--secondary">' +
               '<button id="quick-commit-tag-head-toggle" class="btn btn-ghost btn-sm" type="button"' + (state.quickCommitPushing ? ' disabled' : '') + '>' +
                 '<svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true" style="vertical-align:-2px;margin-right:4px;"><path d="M2 2h6.5l5 5-5.5 5.5L2 7.5V2z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"/><circle cx="5" cy="5" r="1" fill="currentColor"/></svg>' +
-                (state.quickCommitTagHeadOpen ? '收起' : '为 HEAD 打 tag') +
+                (state.quickCommitOpenMenu === "tag-head" ? '收起' : '为 HEAD 打 tag') +
               '</button>' +
               renderQuickCommitPushButton(s) +
             '</div>' +
@@ -2640,6 +2647,40 @@
                   '</div>' +
                   '<p id="android-apk-message" class="hint hidden"></p>' +
                 '</div>' +
+                '<div class="settings-update-section hidden" id="macos-dmg-section">' +
+                  '<div class="settings-section-head">' +
+                    '<span class="settings-section-icon">🖥️</span>' +
+                    '<div class="settings-section-head-text">' +
+                      '<h4 class="settings-section-heading">macOS App</h4>' +
+                      '<p class="settings-section-sub">原生客户端版本与 DMG 下载</p>' +
+                    '</div>' +
+                  '</div>' +
+                  '<div id="macos-dmg-current-row" class="settings-about-row hidden">' +
+                    '<span class="settings-label">当前版本</span>' +
+                    '<span class="settings-value" id="settings-macos-dmg-current">-</span>' +
+                  '</div>' +
+                  '<div id="macos-dmg-github-row" class="settings-about-row settings-about-row-action hidden">' +
+                    '<span class="settings-label">线上版本</span>' +
+                    '<span class="settings-value settings-value-flex" id="settings-macos-dmg-github">-</span>' +
+                    '<button id="download-github-dmg-btn" class="btn btn-secondary btn-sm hidden" type="button">下载</button>' +
+                  '</div>' +
+                  '<div id="macos-dmg-local-row" class="settings-about-row settings-about-row-action hidden">' +
+                    '<span class="settings-label">本地版本</span>' +
+                    '<span class="settings-value settings-value-flex" id="settings-macos-dmg-local">-</span>' +
+                    '<button id="download-local-dmg-btn" class="btn btn-secondary btn-sm hidden" type="button">下载</button>' +
+                  '</div>' +
+                  '<div id="macos-auto-update-row" class="settings-toggle-row hidden">' +
+                    '<div class="settings-toggle-text">' +
+                      '<span class="settings-toggle-title">自动更新</span>' +
+                      '<span class="settings-toggle-desc" id="macos-auto-update-hint">检测到新版 DMG 将自动下载并挂载。</span>' +
+                    '</div>' +
+                    '<label class="settings-switch">' +
+                      '<input type="checkbox" id="auto-update-dmg-toggle" class="switch-toggle">' +
+                      '<span class="switch-slider"></span>' +
+                    '</label>' +
+                  '</div>' +
+                  '<p id="macos-dmg-message" class="hint hidden"></p>' +
+                '</div>' +
                 '<div class="settings-update-section" id="android-connect-section">' +
                   '<div class="settings-section-head">' +
                     '<span class="settings-section-icon">🔗</span>' +
@@ -5580,6 +5621,10 @@
         if (autoUpdateApkToggle) autoUpdateApkToggle.addEventListener("change", function() {
           toggleAutoUpdate("apk", autoUpdateApkToggle.checked);
         });
+        var autoUpdateDmgToggle = document.getElementById("auto-update-dmg-toggle");
+        if (autoUpdateDmgToggle) autoUpdateDmgToggle.addEventListener("change", function() {
+          toggleAutoUpdate("dmg", autoUpdateDmgToggle.checked);
+        });
         var copyConnectCodeBtn = document.getElementById("copy-connect-code-button");
         if (copyConnectCodeBtn) copyConnectCodeBtn.addEventListener("click", function() {
           var text = document.getElementById("android-connect-code");
@@ -7279,7 +7324,13 @@
           var delta = normalizedOutput.slice(currentOutput.length);
           if (delta) {
             wandTerminalWrite(state.terminal, delta);
-            maybeScheduleResyncForChunk(delta);
+            // 不在流式 chunk 路径触发 softResyncTerminal —— resync 会
+            // resetTerminal() + 完整重放整段 buffer，重放期间所有 cursor-home
+            // + 重画序列把"被覆盖的中间帧"反复塞进 main-screen scrollback，
+            // 表现为 PTY 视图里同一段回答被画 N 遍（PC 端列宽大、Claude TUI
+            // 重画序列密集时最严重）。响应结束的 thinking→idle 边界已经做了
+            // 一次 softResync 兜底，足以清掉流式残留的错位光标 DOM；流式
+            // 过程中持续重放只是纯粹的重复制造器。
             wrote = true;
           }
         } else if (currentOutput && currentOutput.startsWith(normalizedOutput)) {
@@ -9222,6 +9273,8 @@
             if (autoUpdateWebToggle) autoUpdateWebToggle.checked = !!autoUpdate.web;
             var autoUpdateApkToggle = document.getElementById("auto-update-apk-toggle");
             if (autoUpdateApkToggle) autoUpdateApkToggle.checked = !!autoUpdate.apk;
+            var autoUpdateDmgToggle = document.getElementById("auto-update-dmg-toggle");
+            if (autoUpdateDmgToggle) autoUpdateDmgToggle.checked = !!autoUpdate.dmg;
 
             // ── Android APK version display ──
             var apkSection = document.getElementById("android-apk-section");
@@ -9341,6 +9394,119 @@
               }
             }
 
+            // ── macOS DMG version display ──
+            var dmgSection = document.getElementById("macos-dmg-section");
+            var dmgCurrentRow = document.getElementById("macos-dmg-current-row");
+            var dmgCurrentEl = document.getElementById("settings-macos-dmg-current");
+            var dmgGithubRow = document.getElementById("macos-dmg-github-row");
+            var dmgGithubEl = document.getElementById("settings-macos-dmg-github");
+            var dmgGithubBtn = document.getElementById("download-github-dmg-btn");
+            var dmgLocalRow = document.getElementById("macos-dmg-local-row");
+            var dmgLocalEl = document.getElementById("settings-macos-dmg-local");
+            var dmgLocalBtn = document.getElementById("download-local-dmg-btn");
+            var dmgMessageEl = document.getElementById("macos-dmg-message");
+            var macosDmg = data.macosDmg || {};
+            var isInMacApp = !!_macAppVersion;
+            var hasDmgInfo = isInMacApp || !!macosDmg.github || !!macosDmg.local;
+            if (dmgSection) {
+              if (hasDmgInfo) dmgSection.classList.remove("hidden");
+              else dmgSection.classList.add("hidden");
+            }
+
+            if (isInMacApp) {
+              // ── macOS 壳内：显示当前版本 + 线上 + 本地 + 下载安装按钮 ──
+              if (dmgCurrentRow && dmgCurrentEl) {
+                dmgCurrentEl.textContent = "v" + _macAppVersion;
+                dmgCurrentRow.classList.remove("hidden");
+              }
+              if (macosDmg.github && dmgGithubRow && dmgGithubEl) {
+                var dghLabel = macosDmg.github.version ? ("v" + macosDmg.github.version) : macosDmg.github.fileName;
+                if (typeof macosDmg.github.size === "number") dghLabel += " · " + formatBytes(macosDmg.github.size);
+                dmgGithubEl.textContent = dghLabel;
+                dmgGithubRow.classList.remove("hidden");
+                if (dmgGithubBtn) {
+                  dmgGithubBtn.textContent = "下载安装";
+                  dmgGithubBtn.classList.remove("hidden");
+                  dmgGithubBtn.onclick = function() {
+                    try {
+                      WandNative.downloadUpdate(macosDmg.github.downloadUrl, macosDmg.github.fileName || "wand-update.dmg", "github");
+                    } catch (e) {
+                      if (typeof window.wandAlert === "function") {
+                        window.wandAlert("调用下载失败: " + e.message, { type: "danger", title: "下载失败" });
+                      } else if (typeof showToast === "function") {
+                        showToast("调用下载失败: " + e.message, "error");
+                      } else {
+                        alert("调用下载失败: " + e.message);
+                      }
+                    }
+                  };
+                }
+              }
+              if (macosDmg.local && dmgLocalRow && dmgLocalEl) {
+                var dlcLabel = macosDmg.local.version ? ("v" + macosDmg.local.version) : macosDmg.local.fileName;
+                if (typeof macosDmg.local.size === "number") dlcLabel += " · " + formatBytes(macosDmg.local.size);
+                dmgLocalEl.textContent = dlcLabel;
+                dmgLocalRow.classList.remove("hidden");
+                if (dmgLocalBtn) {
+                  dmgLocalBtn.textContent = "下载安装";
+                  dmgLocalBtn.classList.remove("hidden");
+                  dmgLocalBtn.onclick = function() {
+                    try {
+                      WandNative.downloadUpdate(macosDmg.local.downloadUrl, macosDmg.local.fileName || "wand-update.dmg", "local");
+                    } catch (e) {
+                      if (typeof window.wandAlert === "function") {
+                        window.wandAlert("调用下载失败: " + e.message, { type: "danger", title: "下载失败" });
+                      } else if (typeof showToast === "function") {
+                        showToast("调用下载失败: " + e.message, "error");
+                      } else {
+                        alert("调用下载失败: " + e.message);
+                      }
+                    }
+                  };
+                }
+              }
+              if (!macosDmg.github && !macosDmg.local && dmgMessageEl) {
+                dmgMessageEl.textContent = "暂无可用更新";
+                dmgMessageEl.classList.remove("hidden");
+              }
+              var dmgAutoRow = document.getElementById("macos-auto-update-row");
+              var dmgAutoHint = document.getElementById("macos-auto-update-hint");
+              if (dmgAutoRow) dmgAutoRow.classList.remove("hidden");
+              if (dmgAutoHint) dmgAutoHint.classList.remove("hidden");
+            } else {
+              // ── 浏览器模式：仅展示下载入口 ──
+              if (macosDmg.github && dmgGithubRow && dmgGithubEl) {
+                var dghLabel2 = macosDmg.github.version ? ("v" + macosDmg.github.version) : macosDmg.github.fileName;
+                if (typeof macosDmg.github.size === "number") dghLabel2 += " · " + formatBytes(macosDmg.github.size);
+                dmgGithubEl.textContent = dghLabel2;
+                dmgGithubRow.classList.remove("hidden");
+                if (dmgGithubBtn) {
+                  dmgGithubBtn.textContent = "下载";
+                  dmgGithubBtn.classList.remove("hidden");
+                  dmgGithubBtn.onclick = function() {
+                    window.open(macosDmg.github.downloadUrl, "_blank");
+                  };
+                }
+              }
+              if (macosDmg.local && dmgLocalRow && dmgLocalEl) {
+                var dlcLabel2 = macosDmg.local.version ? ("v" + macosDmg.local.version) : macosDmg.local.fileName;
+                if (typeof macosDmg.local.size === "number") dlcLabel2 += " · " + formatBytes(macosDmg.local.size);
+                dmgLocalEl.textContent = dlcLabel2;
+                dmgLocalRow.classList.remove("hidden");
+                if (dmgLocalBtn) {
+                  dmgLocalBtn.textContent = "下载";
+                  dmgLocalBtn.classList.remove("hidden");
+                  dmgLocalBtn.onclick = function() {
+                    window.open(macosDmg.local.downloadUrl, "_self");
+                  };
+                }
+              }
+              if (!macosDmg.github && !macosDmg.local && dmgMessageEl) {
+                dmgMessageEl.textContent = "暂未提供";
+                dmgMessageEl.classList.remove("hidden");
+              }
+            }
+
             // App connect code (encrypted)
             var connectCodeEl = document.getElementById("android-connect-code");
             var connectQrCanvas = document.getElementById("android-connect-qr");
@@ -9710,6 +9876,24 @@
           .catch(function() {});
       }
 
+      function checkDmgAutoUpdate() {
+        if (!_macAppVersion) return;
+        fetch("/api/auto-update", { credentials: "same-origin" })
+          .then(function(res) { return res.json(); })
+          .then(function(autoData) {
+            if (!autoData.dmg) return;
+            return fetch("/api/macos-dmg-update?currentVersion=" + encodeURIComponent(_macAppVersion), { credentials: "same-origin" })
+              .then(function(res) { return res.json(); })
+              .then(function(data) {
+                if (!data.updateAvailable || !data.downloadUrl) return;
+                try {
+                  WandNative.downloadUpdate(data.downloadUrl, data.fileName || "wand-update.dmg", data.source || "local");
+                } catch (_e) {}
+              });
+          })
+          .catch(function() {});
+      }
+
       function toggleAutoUpdate(type, enabled) {
         var body = {};
         body[type] = enabled;
@@ -9724,8 +9908,10 @@
           // Sync toggle state with server response
           var webToggle = document.getElementById("auto-update-web-toggle");
           var apkToggle = document.getElementById("auto-update-apk-toggle");
+          var dmgToggle = document.getElementById("auto-update-dmg-toggle");
           if (webToggle) webToggle.checked = !!data.web;
           if (apkToggle) apkToggle.checked = !!data.apk;
+          if (dmgToggle) dmgToggle.checked = !!data.dmg;
         })
         .catch(function() {
           // Revert toggle on failure
@@ -13870,6 +14056,35 @@
 
       // Drop any in-flight socket and start a new one *now* — used by the
       // Android resume bridge to recover from zombie connections (socket
+      // 客户端 WS 心跳检测：每 10s 跑一次，看 lastWsMessageAt 距今多久。
+      // 服务端每 20s 主动下推 {type:"ping"}，所以 40s 没消息就明确是半开。
+      // 浏览器在 background 时 setInterval 会被节流到 ~1Hz 或更慢，但
+      // 我们也在 visibilitychange→visible 里做了一次主动评估，所以
+      // 切回前台时不会拖很久才发现 stale。
+      var WS_HEARTBEAT_CHECK_MS = 10_000;
+      var WS_HEARTBEAT_STALE_MS = 40_000;
+      function startWsHeartbeatCheck() {
+        stopWsHeartbeatCheck();
+        state.wsHeartbeatCheckTimer = setInterval(evaluateWsHeartbeatStale, WS_HEARTBEAT_CHECK_MS);
+      }
+      function stopWsHeartbeatCheck() {
+        if (state.wsHeartbeatCheckTimer) {
+          clearInterval(state.wsHeartbeatCheckTimer);
+          state.wsHeartbeatCheckTimer = null;
+        }
+      }
+      function evaluateWsHeartbeatStale() {
+        if (!state.ws || state.ws.readyState !== WebSocket.OPEN) return;
+        // 第一帧（包括 onopen）会刷新 lastWsMessageAt；如果还是 0 说明刚连上
+        // 但服务端没下发任何东西（连 init 都没发出来）——交给下一轮检查。
+        if (!state.lastWsMessageAt) return;
+        var idle = Date.now() - state.lastWsMessageAt;
+        if (idle > WS_HEARTBEAT_STALE_MS) {
+          forceReconnectWebSocket("heartbeat-stale-" + Math.round(idle / 1000) + "s");
+        }
+      }
+
+      // Force a fresh WebSocket connection even if the existing one
       // still says OPEN, but the TCP path was torn down by Doze). Skips
       // the backoff timer; the caller has already decided this is urgent.
       function forceReconnectWebSocket(reason) {
@@ -13880,6 +14095,13 @@
           // reconnect path while we're already starting a fresh one.
           try { stale.onclose = null; } catch (e) { /* ignore */ }
           try { stale.onerror = null; } catch (e) { /* ignore */ }
+          // 也清掉 onmessage：close() 是异步的，TCP RST/Close 帧到达之前，浏览器
+          // socket 缓冲区里可能还有几条 in-flight 帧没派发。一旦它们在新 ws 已
+          // open + init 之后再触发，老 ws 的 output 会被 handleWebSocketMessage
+          // 当成"新增量"写进 wterm，造成"刚才那段又被画了一遍"。stale 心跳触发
+          // 的 force reconnect 比 onclose 触发更早，老 ws 仍处于 OPEN，这个窗口
+          // 更宽，必须显式 detach。
+          try { stale.onmessage = null; } catch (e) { /* ignore */ }
           try { stale.close(); } catch (e) { /* ignore */ }
           state.ws = null;
         }
@@ -13926,6 +14148,7 @@
           ws.onopen = function() {
             state.ws = ws;
             state.wsConnected = true;
+            state.lastWsMessageAt = Date.now();
             // Reset backoff on a successful connect so the next disconnect
             // starts the ladder from 500ms again.
             state.wsReconnectAttempts = 0;
@@ -13933,6 +14156,9 @@
             // Server's per-client output sequence counter restarts on every
             // new socket; clear ours so the first init isn't treated as a gap.
             state.lastSeqBySession = {};
+            // 启动客户端心跳检测：每 10s 检查一次 lastWsMessageAt，超过 40s
+            // 没收到任何消息（包括服务端 20s 一次的 ping）就视为半开连接。
+            startWsHeartbeatCheck();
             // Subscribe to current session if any
             subscribeToSession(state.selectedId);
             // Flush pending messages after reconnection
@@ -13947,8 +14173,20 @@
           };
 
           ws.onmessage = function(event) {
+            // 任意服务端消息都说明连接活着，先刷新心跳计时。
+            state.lastWsMessageAt = Date.now();
             try {
               var msg = JSON.parse(event.data);
+              // 应用层 ping：立刻回 pong。同时也让服务端能算 RTT。
+              // 这条消息处理完就 return，不进入下面的 sessionId 分发流程。
+              if (msg && msg.type === "ping") {
+                if (state.ws && state.ws.readyState === WebSocket.OPEN) {
+                  try {
+                    state.ws.send(JSON.stringify({ type: "pong", t: msg.t }));
+                  } catch (sendErr) { /* ignore */ }
+                }
+                return;
+              }
               if (msg && msg.type === "resync_required" && msg.sessionId) {
                 // Server dropped some output events under backpressure and
                 // is asking us for a fresh snapshot. Send a resync so the
@@ -13995,6 +14233,7 @@
           ws.onclose = function() {
             state.ws = null;
             state.wsConnected = false;
+            stopWsHeartbeatCheck();
             scheduleWsReconnect();
           };
 
@@ -14128,7 +14367,9 @@
                 // 变化的视觉错位无法被自愈，直到用户手动改窗口才修。现在让
                 // wterm 内部 ResizeObserver 独占 cols 跟踪职责。
                 wandTerminalWrite(state.terminal, msg.data.chunk);
-                maybeScheduleResyncForChunk(msg.data.chunk);
+                // 同 syncTerminalBuffer 的 delta 分支：流式 chunk 不再触发
+                // softResyncTerminal，避免完整重放把 cursor-home + 重画的
+                // "被覆盖中间帧"反复塞进 scrollback。thinking→idle 兜底就够了。
                 state.terminalSessionId = msg.sessionId;
                 if (msg.data.output) {
                   state.terminalOutput = clampClientTerminalOutput(normalizeTerminalOutput(msg.data.output));
@@ -14264,10 +14505,24 @@
               renderChat(true);
               updateTaskDisplay();
               updateApprovalStats();
-              // 订阅返回的是服务端 ring buffer 最新窗口，与客户端 terminalOutput
-              // 可能不连续。强制 replace（reset + 按当前 cols 重写）是订阅时唯一
-              // 可信的全量基线，避免 append 的 prefix 检查走错分支。
-              updateTerminalOutput(msg.data.output || "", msg.sessionId, "replace");
+              // 服务端 ring buffer 在多数场景下是当前已渲染输出的严格 superset
+              // （同一 PTY，buffer 只增不减）。这种情况下走 append delta 就够了，
+              // 不应该强制 replace。replace 会触发 resetTerminal + 全量重放整段
+              // output，wterm 把 ANSI cursor-home 重画的"中间帧"全部塞进
+              // scrollback，造成"同一段回答在 PTY 视图里被画 N 遍"——尤其是
+              // 锁屏 / 切回前台 / 心跳 stale 触发 reconnect 时，每次 init 都重放
+              // 一次，累积重复非常显著。
+              //
+              // 只有真的不连续（会话切换、ring buffer 截断了头部、output 不是
+              // currentOutput 的严格前缀延伸）才回退到 replace 的全量基线。
+              var initOutput = msg.data.output || "";
+              var sameTerminalSession = state.terminalSessionId === msg.sessionId;
+              var currTerminalOutput = state.terminalOutput || "";
+              var canAppendDelta = sameTerminalSession
+                && currTerminalOutput.length > 0
+                && initOutput.length >= currTerminalOutput.length
+                && initOutput.startsWith(currTerminalOutput);
+              updateTerminalOutput(initOutput, msg.sessionId, canAppendDelta ? "append" : "replace");
               // wterm 启动 cols=120，replace 写入可能落在错的列宽上；ResizeObserver
               // 回调异步，用 fit-with-retry 兜一次确保按真实宽度重排。
               ensureTerminalFitWithRetry("init");
@@ -17762,11 +18017,43 @@
 
       // ── Browser Notification API ──
 
+      // macOS WKWebView shim: Android shell injects a global WandNative via
+      // addJavascriptInterface, but WKWebView only exposes
+      // webkit.messageHandlers.<name>.postMessage(...). To keep call-sites
+      // identical across platforms, we synthesize a WandNative-shaped object
+      // when running inside the macOS shell.
+      try {
+        var _macUaMatch = navigator.userAgent.match(/WandPlatform\/macOS/);
+        var _macHandler = (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.wandNative) || null;
+        if (_macUaMatch && _macHandler && typeof window.WandNative === "undefined") {
+          window.WandNative = {
+            // Only downloadUpdate is wired for now; other Android-specific
+            // methods (notifications, haptics, screen wake) intentionally
+            // omitted so feature detection falls back to web APIs on macOS.
+            downloadUpdate: function(url, fileName, source) {
+              try {
+                _macHandler.postMessage({
+                  type: "downloadUpdate",
+                  url: String(url || ""),
+                  fileName: String(fileName || "wand-update.dmg"),
+                  source: String(source || "local"),
+                });
+              } catch (_e) {}
+            },
+          };
+        }
+      } catch (_e) {}
+
       // Detect Android APK native bridge
       var _hasNativeBridge = typeof WandNative !== "undefined" && typeof WandNative.sendNotification === "function";
-      // Detect if running inside APK and extract installed version from User-Agent
-      var _apkVersionMatch = navigator.userAgent.match(/WandApp\/([^\s]+)/);
-      var _apkVersion = _apkVersionMatch ? _apkVersionMatch[1] : null;
+      // Extract WandApp/<version> from User-Agent (set by both Android and macOS shells).
+      // We distinguish platforms by the additional WandPlatform/<name> token —
+      // macOS UA ends with "WandApp/X WandPlatform/macOS".
+      var _wandAppMatch = navigator.userAgent.match(/WandApp\/([^\s]+)/);
+      var _isMacApp = /WandPlatform\/macOS/.test(navigator.userAgent);
+      var _isAndroidApp = !!_wandAppMatch && !_isMacApp;
+      var _apkVersion = (_wandAppMatch && _isAndroidApp) ? _wandAppMatch[1] : null;
+      var _macAppVersion = (_wandAppMatch && _isMacApp) ? _wandAppMatch[1] : null;
 
       function _vibrate(pattern) {
         if (!_hasNativeBridge || typeof WandNative.vibrate !== "function") return;