@co0ontty/wand 4.72.0 → 4.72.1

package/dist/web-ui/sidebar-layout.d.ts

@@ -16,10 +16,6 @@
  * 在 `max-width: 639.98px` 归零，成对出现，不能各自为政——否则会出现
  * 「JS 认为停靠、CSS 不补 padding」的覆盖态。
  */
-/** 停靠所需的最小宽度，与 CSS `min-width: 640px` 断点一致。 */
-export declare const SIDEBAR_PUSH_MIN_WIDTH = 640;
-/** 触摸设备停靠所需的最小高度，与原生端 `usesWideListDetail` 一致。 */
-export declare const SIDEBAR_PUSH_MIN_HEIGHT = 480;
 export interface SidebarLayoutViewport {
     readonly width: number;
     readonly height: number;

package/dist/web-ui/sidebar-layout.js

@@ -17,9 +17,9 @@
  * 「JS 认为停靠、CSS 不补 padding」的覆盖态。
  */
 /** 停靠所需的最小宽度，与 CSS `min-width: 640px` 断点一致。 */
-export const SIDEBAR_PUSH_MIN_WIDTH = 640;
+const SIDEBAR_PUSH_MIN_WIDTH = 640;
 /** 触摸设备停靠所需的最小高度，与原生端 `usesWideListDetail` 一致。 */
-export const SIDEBAR_PUSH_MIN_HEIGHT = 480;
+const SIDEBAR_PUSH_MIN_HEIGHT = 480;
 /** true = 抽屉（覆盖主内容）；false = 停靠（推开主内容）。 */
 export function usesSidebarDrawer(viewport) {
     if (!(viewport.width >= SIDEBAR_PUSH_MIN_WIDTH))

package/dist/ws-broadcast.d.ts

@@ -13,8 +13,6 @@ export interface WsSessionPort {
     getTerminalState?(id: string): PtyTerminalSnapshot | null;
     sendPtyInput?(id: string, input: string, shortcutKey?: string, userInput?: boolean): void;
     resizePty?(id: string, cols: number, rows: number): void;
-    pausePtyOutput?(id: string): void;
-    resumePtyOutput?(id: string): void;
 }
 export declare class WsBroadcastManager {
     private wss;
@@ -23,7 +21,6 @@ export declare class WsBroadcastManager {
     private heartbeatTimer?;
     private disposed;
     private port?;
-    private readonly ptyPauseRefs;
     private getCardDefaults;
     private useHttps;
     private authService?;
@@ -68,9 +65,20 @@ export declare class WsBroadcastManager {
      */
     private resumeAndQueueResyncNotices;
     private discardClient;
-    private acquirePtyPause;
-    private releasePtyPause;
-    private releaseAllPtyPauses;
+    /**
+     * 客户端 ack 掉一段已渲染字节。积压回落到低水位就从「降级」恢复，并请该客户端
+     * 用终端快照重建屏幕（降级期间它的屏幕停在最后一帧，中间帧已经丢掉了）。
+     */
+    private handlePtyAck;
+    /**
+     * 客户端积压追赶完成 → 请它用终端快照重建屏幕。
+     *
+     * 走客户端已支持的 `resync_required` 通道（客户端会回 `resync`，服务端用
+     * init 下发 terminalState 快照），不引入新协议。限流见 PTY_RESYNC_MIN_INTERVAL_MS。
+     */
+    private requestPtyResync;
+    /** 把一条 resync 通知塞进该客户端的发送队列（不绕过队列，也不绕过背压）。 */
+    private queueResyncNotice;
     private sendPtyError;
     private processWsQueue;
 }

package/dist/ws-broadcast.js

@@ -26,6 +26,12 @@ const HEARTBEAT_INTERVAL_MS = 20_000;
 const HEARTBEAT_STALE_MS = 45_000;
 const PTY_UNACKED_HIGH_WATER = 512 * 1024;
 const PTY_UNACKED_LOW_WATER = 128 * 1024;
+/**
+ * 同一个（客户端, 会话）两次「请重建屏幕」的最小间隔。慢性慢客户端追上来后会
+ * 立刻再积压，没有这个下限就会变成「重建 → 立刻积压 → 再重建」的循环，每次重建
+ * 都要下发一份终端快照。
+ */
+const PTY_RESYNC_MIN_INTERVAL_MS = 5_000;
 const MAX_PTY_INPUT_CHARS = 128 * 1024;
 function asEventData(data) {
     return data && typeof data === "object" && !Array.isArray(data)
@@ -60,7 +66,6 @@ export class WsBroadcastManager {
     heartbeatTimer;
     disposed = false;
     port;
-    ptyPauseRefs = new Map();
     getCardDefaults;
     useHttps;
     authService;
@@ -116,7 +121,6 @@ export class WsBroadcastManager {
                 sendQueue: [],
                 sendInProgress: false,
                 backpressurePaused: false,
-                lastOutputBySession: new Map(),
                 outputSeqBySession: new Map(),
                 pendingResyncSessions: new Set(),
                 lastSeenAt: Date.now(),
@@ -147,16 +151,13 @@ export class WsBroadcastManager {
                         }
                         // 默认仍是历史的“切换当前会话”；分屏池显式用 mode:add 叠加订阅。
                         if (msg.mode !== "add") {
-                            this.releaseAllPtyPauses(client);
                             client.ptySubscriptions.clear();
                         }
-                        else {
-                            this.releasePtyPause(client, msg.sessionId);
-                        }
                         client.ptySubscriptions.set(msg.sessionId, {
                             supportsAck: msg.capabilities?.ptyAck === true,
                             unackedBytes: 0,
-                            paused: false,
+                            degraded: false,
+                            lastResyncNoticeAt: 0,
                         });
                         this.flushOutput(msg.sessionId);
                         const snapshot = this.port?.getSession(msg.sessionId) ?? null;
@@ -172,7 +173,6 @@ export class WsBroadcastManager {
                         }
                     }
                     else if (msg.type === "unsubscribe" && msg.sessionId) {
-                        this.releasePtyPause(client, msg.sessionId);
                         client.ptySubscriptions.delete(msg.sessionId);
                     }
                     else if (msg.type === "resync" && msg.sessionId) {
@@ -204,13 +204,7 @@ export class WsBroadcastManager {
                         }
                     }
                     else if (msg.type === "pty_ack" && msg.sessionId && Number.isFinite(msg.bytes)) {
-                        const subscription = client.ptySubscriptions.get(msg.sessionId);
-                        if (!subscription?.supportsAck)
-                            return;
-                        subscription.unackedBytes = Math.max(0, subscription.unackedBytes - Math.max(0, Math.floor(msg.bytes)));
-                        if (subscription.paused && subscription.unackedBytes <= PTY_UNACKED_LOW_WATER) {
-                            this.releasePtyPause(client, msg.sessionId);
-                        }
+                        this.handlePtyAck(client, msg.sessionId, msg.bytes);
                     }
                     else if (msg.type === "pong") {
                         // 应用层 pong（对我们下发的 {type:"ping"} 的响应）。lastSeenAt
@@ -436,12 +430,22 @@ export class WsBroadcastManager {
             }
             const subscription = client.ptySubscriptions.get(event.sessionId);
             const usesPtyAckFlowControl = isRawPtyOutput && subscription?.supportsAck === true;
+            if (usesPtyAckFlowControl && subscription.degraded) {
+                // 已经积压到高水位的客户端：后面这些原始字节对它是**过期的 TUI 帧**（终端
+                // 每帧整屏重绘，中间帧没有任何保留价值），停发这些分片；等它 ack 追上来
+                // 再由 requestPtyResync 让它按终端快照重建屏幕。
+                //
+                // 历史实现在这里是「暂停整个会话的 PTY 读取」，结果是：一个客户端
+                // （手机切后台 / WebView 被节流 / 标签页休眠）停止 ack，整个会话对所有
+                // 客户端冻结，连会话日志和落库也一起停，而且只能靠那个客户端 ack 回落
+                // 才恢复；手机不回来就永久冻住。降级只影响积压的这一个客户端。
+                continue;
+            }
             if (usesPtyAckFlowControl) {
                 outgoing = { ...outgoing, ptyBytes };
                 subscription.unackedBytes += ptyBytes;
-                if (subscription.unackedBytes >= PTY_UNACKED_HIGH_WATER) {
-                    this.acquirePtyPause(client, event.sessionId);
-                }
+                if (subscription.unackedBytes >= PTY_UNACKED_HIGH_WATER)
+                    subscription.degraded = true;
             }
             // Backpressure only gates new business messages. The send pump must
             // keep draining messages that were already accepted; otherwise a queue
@@ -490,7 +494,6 @@ export class WsBroadcastManager {
         }
     }
     discardClient(client, terminate) {
-        this.releaseAllPtyPauses(client);
         client.sendQueue.length = 0;
         client.pendingResyncSessions.clear();
         client.sendInProgress = false;
@@ -503,34 +506,45 @@ export class WsBroadcastManager {
             catch { /* ignore */ }
         }
     }
-    acquirePtyPause(client, sessionId) {
+    /**
+     * 客户端 ack 掉一段已渲染字节。积压回落到低水位就从「降级」恢复，并请该客户端
+     * 用终端快照重建屏幕（降级期间它的屏幕停在最后一帧，中间帧已经丢掉了）。
+     */
+    handlePtyAck(client, sessionId, bytes) {
         const subscription = client.ptySubscriptions.get(sessionId);
-        if (!subscription || subscription.paused)
+        if (!subscription?.supportsAck)
             return;
-        subscription.paused = true;
-        const next = (this.ptyPauseRefs.get(sessionId) ?? 0) + 1;
-        this.ptyPauseRefs.set(sessionId, next);
-        if (next === 1)
-            this.port?.pausePtyOutput?.(sessionId);
+        subscription.unackedBytes = Math.max(0, subscription.unackedBytes - Math.max(0, Math.floor(bytes)));
+        if (subscription.degraded && subscription.unackedBytes <= PTY_UNACKED_LOW_WATER) {
+            subscription.degraded = false;
+            this.requestPtyResync(client, sessionId);
+        }
     }
-    releasePtyPause(client, sessionId) {
+    /**
+     * 客户端积压追赶完成 → 请它用终端快照重建屏幕。
+     *
+     * 走客户端已支持的 `resync_required` 通道（客户端会回 `resync`，服务端用
+     * init 下发 terminalState 快照），不引入新协议。限流见 PTY_RESYNC_MIN_INTERVAL_MS。
+     */
+    requestPtyResync(client, sessionId) {
         const subscription = client.ptySubscriptions.get(sessionId);
-        if (!subscription?.paused)
+        if (!subscription)
             return;
-        subscription.paused = false;
-        const next = Math.max(0, (this.ptyPauseRefs.get(sessionId) ?? 1) - 1);
-        if (next === 0) {
-            this.ptyPauseRefs.delete(sessionId);
-            this.port?.resumePtyOutput?.(sessionId);
-        }
-        else {
-            this.ptyPauseRefs.set(sessionId, next);
-        }
+        const now = Date.now();
+        if (now - subscription.lastResyncNoticeAt < PTY_RESYNC_MIN_INTERVAL_MS)
+            return;
+        subscription.lastResyncNoticeAt = now;
+        this.queueResyncNotice(client, sessionId, "pty_backlog_drop");
     }
-    releaseAllPtyPauses(client) {
-        for (const sessionId of client.ptySubscriptions.keys()) {
-            this.releasePtyPause(client, sessionId);
+    /** 把一条 resync 通知塞进该客户端的发送队列（不绕过队列，也不绕过背压）。 */
+    queueResyncNotice(client, sessionId, reason) {
+        if (client.ws.readyState !== WebSocket.OPEN)
+            return;
+        client.sendQueue.push(JSON.stringify({ type: "resync_required", sessionId, reason }));
+        if (client.sendQueue.length >= MAX_QUEUE_SIZE) {
+            client.backpressurePaused = true;
         }
+        this.processWsQueue(client);
     }
     sendPtyError(client, sessionId, error) {
         if (client.ws.readyState !== WebSocket.OPEN)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@co0ontty/wand",
-  "version": "4.72.0",
+  "version": "4.72.1",
   "description": "A web console for Claude Code, Codex, OpenCode, and other local CLI tools.",
   "type": "module",
   "bin": {