dsh-ssh-tui 0.8.2 → 0.8.3

package/CHANGELOG.md

@@ -10,6 +10,30 @@
 
 ---
 
+## 0.8.3 — 2026-10-13（`latest` + `next`）
+
+发版说明：[`docs/release-notes-0.8.3.md`](release-notes-0.8.3.md)。
+**紧急修复**：三个缺陷都是 0.8.2 把首启向导改成 Screen 时引入的，全部在"首次安装 / `/setup`"这条路上。
+
+### Fixed
+
+- **首启向导 / `/setup` 的粘贴**：终端粘贴（Ctrl+V / Cmd+V / 右键，即括号粘贴）此前落到 Screen
+  *背后*的工作区草稿里——向导字段一个字都收不到，读者只能手敲 API Key。现在粘贴归字段所有：字段步骤
+  直接落进字段（行尾换行折叠掉，多行按分隔拼接成一行），没有字段的步骤（模型多选、确认）不接收，
+  两种情况下草稿都不再被改写。
+- **走完向导没有退回工作区**：保存成功后 Screen 仍然占着屏，要随便按一个键才退得出去（那个键的兜底
+  才是真正的退场）。现在**保存本身就是退场**，与 Esc 对称；保存失败则**保留向导与错误**（此前错误写在
+  一个立刻被丢弃的状态上：Screen 留着、错误没了、填好的答案也没了）。完成语改为转写行，回到工作区
+  仍可读到。
+- **一次读取里的多个按键**：`text\r` 这样的读取会收下文字却丢掉回车，步骤停住不动。现在按 composer
+  一直以来的规则拆开（转义序列完整、CRLF 一个回车、控制字节各自成键、可打印文本连成一段）。
+- **Screen 打开时的 composer 编辑键**：`Enter` / `Backspace` / `Ctrl+H` / `Ctrl+U` / `Ctrl+K` /
+  `Ctrl+A` / `Ctrl+E` / `Ctrl+R` / `Ctrl+T` 不再作用于 `/diag`、`/status`、diff 全览等 Screen 背后
+  那个看不见的草稿（此前 `Enter` 会把草稿当消息发出去，`Ctrl+U` / `Ctrl+K` 会清空或截断它）。
+- **Screen 里的 `Ctrl+L`**：任意 Screen（不只是向导）都能整屏重画，用于清理花屏的终端；此前只有向导认这个键。
+
+---
+
 ## 0.8.2 — 2026-10-05（`latest` + `next`）
 
 发版说明：[`docs/release-notes-0.8.2.md`](release-notes-0.8.2.md)；候选版说明保留在

package/docs/release-notes-0.8.2.md

@@ -3,7 +3,9 @@
 > **发布方式：`latest` + `next`。** 上一次发版：**0.8.1**（2026-09-30，`latest` + `next`）。
 > 本版由 **0.8.2-rc.1**（2026-10-04 只上 `next`）沉淀一周后转正：候选版期间没有收到新的回归报告，
 > CI 五条腿与全部真 PTY 探针持续全绿，Windows / ConPTY 实机人工验收也已完成（见
-> [`checkpoints.md`](checkpoints.md)「Windows 实机轮」）。**内容与 0.8.2-rc.1 完全相同**，
+> [`checkpoints.md`](checkpoints.md)「Windows 实机轮」）。**运行时内容与候选版逐字节相同**（转正后从 registry 分别取回两个 tarball，`lib/` 整目录
+> `diff -r` 无差异）；自候选版以来新增的只有 README 与文档（DSH Relay 软品牌那一批）以及
+> `docs/screenshots/reconnect.gif`。
 > 逐项说明见 [`release-notes-0.8.2-rc.1.md`](release-notes-0.8.2-rc.1.md)。
 
 > `dsh-ssh-tui` is now presented as DSH Relay.

package/docs/release-notes-0.8.3.md

@@ -0,0 +1,72 @@
+# 0.8.3 发版说明
+
+> **发布方式：`latest` + `next`。** 上一次发版：**0.8.2**（2026-10-05，`latest` + `next`）。
+> 本版是**紧急修复**：0.8.2 把首启向导改成 Screen 之后，向导的输入与退场出了三个缺陷，
+> 都在"首次安装 / `/setup`"这条路上。没有协议变更、没有配置变更、没有数据损坏；
+> 升级即修复，不需要任何迁移动作。
+
+## 头等事：向导收得下粘贴，也走得掉
+
+三个缺陷都是 0.8.2 引入的（0.8.1 的向导借工作区的输入行，所以既收得到粘贴、也不需要自己退场）。
+
+### 1. 粘贴的 API Key 进不了字段，只能手敲
+
+终端粘贴（Ctrl+V / Cmd+V / 右键，即括号粘贴）此前落到了向导 **Screen 背后**那个看不见的工作区草稿里：
+向导字段一个字都收不到，而粘贴并没丢——它会留在草稿里，Esc 离开向导后在输入行现形，按回车就会被当成
+一条消息发出去。受影响的是**所有做括号粘贴的终端**（Windows Terminal、iTerm2、GNOME Terminal、WezTerm、
+kitty、VS Code 终端、tmux……），也就是几乎所有现代终端；受影响的是**每一个字段步骤**（提供商过滤、
+Provider ID、Base URL、**API Key**、模型列表、上下文窗口）。
+
+现在粘贴归字段所有：字段步骤直接落进字段（行尾换行折叠掉，多行按分隔拼成一行），没有字段的步骤
+（模型多选、确认）不接收，两种情况都不再改写工作区草稿。老控制台不发括号粘贴时，多行 burst 也按粘贴处理。
+
+### 2. 走完向导没有退回工作区
+
+保存成功后向导仍然占着屏，读者要随便按一个键才退得出去（那个键的"Screen 背后没有向导 → 关掉它"兜底
+才是真正的退场）。**保存本身就是退场**，现在与 Esc 一致：按 `y` 的同一帧，工作区回来。
+
+同一处的失败路径也修了：保存失败时错误写在了一个立刻被丢弃的状态上——Screen 留着、错误没了、填好的答案
+也没了，下一次按键还把这套流程当作没发生过。现在失败**保留向导与错误**，改完可以直接重试。
+
+向导自己的提示行会随 Screen 消失，所以"配置完成，已记住 X / Y"现在落在**转写行**里（凭据那一行是
+footer 回显，会过期），回到工作区后还读得到。
+
+### 3. 一次读取里的多个按键（顺带修掉的同类）
+
+一次终端读取里的多个按键此前被当成一个键：`text\r`（慢链路上的快速输入、终端合并写入）会收下文字却
+**丢掉那个回车**，步骤停住不动——读者只能再按一次回车。现在一次读取按 composer 一直以来的规则拆开：
+转义序列保持完整、CRLF 算一个回车、控制字节各自成键、可打印文本连成一段（所以没有括号粘贴的
+"yes" 仍然不会替读者按下确认）。
+
+## 兼容
+
+上游兼容窗口与 0.8.2 相同：`0.2.0-rc.1` / `0.2.0-rc.2` / `0.1.7-rc.1` / `0.1.7-rc.2`。
+**0.1.5 及更早的宿主不再支持。** 本版不改协议、不加命令、不动上游接口，也不改任何配置文件的形状。
+
+## 安装 / 升级
+
+```sh
+dsh plugin --profile tui add dsh-ssh-tui@latest
+```
+
+装完退出再启动。`/status` 可确认当前版本；装不上先看 `/doctor`。
+更新时请显式带 `@latest`，否则已有 lockfile 可能继续沿用旧版本。
+
+## 实测数字（本版，100×20）
+
+| 动作 | 毫秒（中位） | 字节 | 寻址行 | 全屏清屏 |
+|---|---|---|---|---|
+| 流式 delta | 1.67 | 501 | 3 | **0** |
+| 等待卡时钟 | 1.12 | 465 | 3 | **0** |
+| 报告屏翻页 | 1.21 | 2457 | 17 | **0** |
+| 菜单光标移动 | 0.90 | 588 | 4 | **0** |
+| 向导字段打字 | 0.19 | 140 | 1 | **0** |
+
+复现：`npm run bench`；README 里的同一张表由 `npm run bench:report` 从这次真跑生成。
+本版没有触碰绘制路径，数字与 0.8.2 同一量级。
+
+## 已知问题
+
+- 向导字段没有左右光标键，粘贴总是追加在末尾（掩码字段 + 中间光标这条组合目前不存在）。
+- `未测` 那一格在 Windows 本机看不到（ConPTY 代答光标位置），由管道父进程形状的探针覆盖。
+- 完整已知问题与人工验收清单见 [`checkpoints.md`](checkpoints.md) 的 0.8.2 一节。

package/lib/tui.js

@@ -451,6 +451,81 @@ const QUOTA_RETRY_MS = 15_000;
 const SETUP_STEPS = ['provider', 'id', 'base-url', 'key', 'models', 'models-pick', 'model-default', 'context', 'confirm'];
 /** The steps that show a text field (the others are pickers or the confirmation). */
 const SETUP_FIELD_STEPS = new Set(['provider', 'id', 'base-url', 'key', 'models', 'context']);
+/**
+ * Whether one data chunk is a paste rather than keystrokes.
+ *
+ * Bracketed paste says so outright, and that is the path every modern terminal
+ * takes. A console without it sends the content as one burst instead, and a burst
+ * carrying more than one line break is not a human pressing Enter twice — they
+ * cannot press it twice inside one read. This is the fallback's one rule, kept
+ * here so every surface that can take a paste applies the same one.
+ */
+function looksLikePasteBurst(text) {
+    let breaks = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === '\r' && text[index + 1] !== '\n')
+            breaks += 1;
+        else if (char === '\n' && text[index - 1] !== '\r')
+            breaks += 1;
+        if (breaks > 1)
+            return true;
+    }
+    return false;
+}
+/**
+ * Split one read into the keys it carries.
+ *
+ * A terminal hands over whatever arrived together, which is not always one key: a
+ * fast typist on a slow link sends `text\r`, a console without bracketed paste sends
+ * a whole line, and a paste is followed by Enter inside the same read. The composer
+ * has always taken a read apart (`handlePlainText` types it character by character),
+ * and a Screen has to see the same keys — a control byte is only itself when it
+ * stands alone, so a read handed to one step is a read whose Enter is dropped on the
+ * floor. That is what this returns: escape sequences whole (an arrow is one key),
+ * control bytes one each with CRLF read as the one Enter it is, and a run of
+ * printable text kept together, because a step that filters on what it is given
+ * wants the run and a paste without markers still must not answer a confirmation.
+ */
+function screenKeys(text) {
+    const keys = [];
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        if (char === '\x1b') {
+            // A CSI sequence (`\x1b[` params final), SS3 (`\x1bO` one char), or the lone
+            // Escape key itself when nothing follows it in this read.
+            const rest = text.slice(index);
+            const sequence = /^\x1b\[[0-9;?<]*[ -/]*[@-~]/u.exec(rest)?.[0] ?? /^\x1bO[@-~]/u.exec(rest)?.[0];
+            if (sequence !== undefined) {
+                keys.push(sequence);
+                index += sequence.length;
+                continue;
+            }
+            keys.push('\x1b');
+            index += 1;
+            continue;
+        }
+        if (char === '\r' || char === '\n') {
+            // Windows terminals send Enter as CRLF; both halves are one key.
+            const next = text[index + 1];
+            keys.push('\r');
+            index += (char === '\r' && next === '\n') || (char === '\n' && next === '\r') ? 2 : 1;
+            continue;
+        }
+        if (char < ' ' || char === '\x7f') {
+            keys.push(char);
+            index += 1;
+            continue;
+        }
+        let end = index;
+        while (end < text.length && text[end] >= ' ' && text[end] !== '\x7f')
+            end += 1;
+        keys.push(text.slice(index, end));
+        index = end;
+    }
+    return keys;
+}
 /**
  * The durable event types the plan projection reads (B2.5).
  *
@@ -11271,6 +11346,41 @@ export class SshTui {
         const screen = this.screen;
         if (screen === undefined)
             return;
+        // Ctrl+L repaints the frame and belongs to the terminal rather than to any
+        // surface that happens to be up: a Screen replaces the workspace entirely, so a
+        // reader with a garbled terminal would otherwise have to leave the Screen to
+        // clear it. The next paint is a full one, exactly as the composer's Ctrl+L is.
+        if (combined === '\x0c') {
+            this.screenNeedsFullPaint = true;
+            this.markDirty();
+            return;
+        }
+        // A burst of line breaks in one read is a paste from a console that cannot say so
+        // (`looksLikePasteBurst`): it belongs in the field as one edit, which is how a
+        // pasted key or model list survives a terminal without bracketed paste. It is
+        // asked *before* the split below, because splitting is what would turn one paste
+        // into a step's worth of Enters.
+        if (looksLikePasteBurst(combined)) {
+            this.pasteIntoScreen(combined);
+            return;
+        }
+        // A read is not a key (`screenKeys`). This is the only path a Screen's input
+        // arrives on, so a read carrying several keys — `text\r` from a fast typist on a
+        // slow link, an arrow batched with the key after it — has to be taken apart here
+        // or the keys after the first are spent on a step that cannot read them. Each key
+        // is handed on its own, and the rest of the read is dropped once the Screen it was
+        // addressed to is gone: the keys after a dismissal belong to whatever comes next,
+        // and guessing that here is how a paste ended up in the composer in the first
+        // place.
+        const keys = screenKeys(combined);
+        if (keys.length > 1) {
+            for (const key of keys) {
+                if (this.screen === undefined)
+                    return;
+                this.handleScreenInput(key, this.keymap.sequences.get(key));
+            }
+            return;
+        }
         // The setup Screen owns its own field, its own navigation and its own keys: it
         // consumes everything while it is up, and nothing reaches the workspace's
         // composer, history or transcript (B2.6 §4).
@@ -11683,14 +11793,23 @@ export class SshTui {
      * A paste is text input, so it goes through the same ownership question ordinary
      * typing does: into the composer's draft when the composer owns the keyboard, and
      * into a borrowed field when a surface that has one does. A surface without a
-     * text field (a confirmation, the inspect overlay) takes no paste at all — the
+     * text field (a confirmation, a menu, a report) takes no paste at all — the
      * alternative was writing the composer's hidden draft behind it, which is how a
      * paste into an approval dialog could silently rewrite the message being written.
+     *
+     * A **Screen** is that same question with a different answer, and it is asked
+     * first because `textIsEditable()` only ever answers for the composer's field: the
+     * setup Screen keeps a field of its own, which the composer's helpers cannot see
+     * and must never be handed (B2.6 §4).
      */
     handlePasteText(text) {
         const normalized = text.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
         if (normalized === '')
             return;
+        if (this.screen !== undefined) {
+            this.pasteIntoScreen(normalized);
+            return;
+        }
         if (!this.textIsEditable())
             return;
         this.leaveHistoryBrowse();
@@ -11705,29 +11824,52 @@ export class SshTui {
         }
         this.markDirty();
     }
+    /**
+     * Give a paste to the field the Screen owns, or to nobody.
+     *
+     * The setup Screen is the only Screen with a field, and it is the one place a
+     * paste matters most: an API key, a base URL and a model list are all copied from
+     * somewhere else, and a first run that could only be typed by hand is the
+     * difference between a working session and an empty one. A step without a field —
+     * the model pickers, the confirmation — is not a text field, so the paste is
+     * dropped exactly as a menu drops it: a paste is text, never an answer.
+     */
+    pasteIntoScreen(text) {
+        const state = this.onboarding;
+        if (this.screen?.kind !== 'setup' || state === undefined || state.saving)
+            return;
+        if (!SETUP_FIELD_STEPS.has(state.step))
+            return;
+        // The field is drawn on one row, so it takes the value and not the line breaks
+        // around it: a key copied off a web page carries the newline that ended its
+        // line, and a pasted list or `.env` block means the breaks as separators. Both
+        // are folded here rather than inserted literally, which would leave the field
+        // holding text no step can parse and no row can draw.
+        const flat = text.split('\n').map(part => part.trim()).filter(part => part !== '').join(' ');
+        if (flat === '')
+            return;
+        this.setupInsert(state, flat);
+        this.markDirty();
+    }
     /**
      * Whether the keys that edit text belong to a field right now.
      *
      * The composer always has one; an open surface only has one when it borrowed it
-     * (a free-text answer, a setup field). Everything else — a confirmation, a menu,
-     * the inspect overlay — owns the keyboard without owning text, and those keys
-     * must do nothing rather than reach the draft behind the surface.
+     * (a free-text answer). Everything else — a confirmation, a menu, the inspect
+     * overlay, every Screen — owns the keyboard without owning the composer's text,
+     * and those keys must do nothing rather than reach the draft behind the surface.
+     * A Screen is included by name: the setup Screen has a field of its own, and it
+     * is reached through the Screen's own keys, never through the composer's.
      */
     textIsEditable() {
+        if (this.screen !== undefined)
+            return false;
         return this.dialog === undefined || this.borrowedText !== undefined;
     }
     handlePlainText(text) {
         // Fallback for terminals without bracketed paste: a burst of multiple line
         // breaks in one chunk is a paste, not repeated Enter presses.
-        let newlines = 0;
-        for (let index = 0; index < text.length; index += 1) {
-            const char = text[index];
-            if (char === '\r' && text[index + 1] !== '\n')
-                newlines += 1;
-            else if (char === '\n' && text[index - 1] !== '\r')
-                newlines += 1;
-        }
-        if (newlines > 1) {
+        if (looksLikePasteBurst(text)) {
             this.handlePasteText(text);
             return;
         }
@@ -11747,11 +11889,15 @@ export class SshTui {
         }
     }
     handleChar(char) {
-        // A setup Screen owns every key, Enter included: it is the key that submits a
-        // step, and the composer behind the screen must never receive one (B2.6 §4).
-        // Ctrl+C is the exception — it is the terminal's own interrupt and keeps its
-        // global meaning.
-        if (this.screen?.kind === 'setup' && char !== '\x03') {
+        // A Screen owns every key outright, and the gate comes first for the same reason
+        // `handleInputText` puts it first: the switch below spends its keys on the
+        // composer — Enter submits the draft, Backspace/Ctrl+U/Ctrl+K edit it, Ctrl+R
+        // folds the transcript behind the Screen. A Screen is not a dialog, so none of
+        // the `dialog === undefined` guards in that switch ever saw it, and every one of
+        // those keys used to reach a draft the reader could not see. The Screen decides
+        // what it uses (Enter and Ctrl+C close it, Esc leaves it, the wizard answers with
+        // them); anything it does not use is dropped, never forwarded (B2.6 §4).
+        if (this.screen !== undefined) {
             this.handleScreenInput(char, this.keymap.sequences.get(char));
             return;
         }
@@ -12249,13 +12395,6 @@ export class SshTui {
             this.markDirty();
             return;
         }
-        if (combined === '\x0c') {
-            // Ctrl+L still repaints the whole frame: the field is a row like any other,
-            // and a forced repaint is how a reader clears a garbled terminal.
-            this.screenNeedsFullPaint = true;
-            this.markDirty();
-            return;
-        }
         if (combined === '\x15') {
             // Ctrl+U clears the wizard's field, not the workspace's draft.
             this.setupSetField(state, '', 0);
@@ -12725,7 +12864,7 @@ export class SshTui {
                     this.setupMessage(state, 'system', t('onboard.baseSaved', { path: displayDshPath('settings.yaml') }));
                 }
                 if (saved) {
-                    this.setupMessage(state, 'system', t('onboard.officialDone', { model }));
+                    this.onboardDone(t('onboard.officialDone', { model }));
                 }
             }
             else {
@@ -12898,7 +13037,7 @@ export class SshTui {
                     this.onSelectionChanged?.(selection);
                     await this.rememberRoute(selection);
                     await this.syncSubagentToProvider(ownerId, state.models, previousParentProvider !== ownerId);
-                    this.setupMessage(state, 'system', t('onboard.customDone', { id: ownerId, model }));
+                    this.onboardDone(t('onboard.customDone', { id: ownerId, model }));
                 }
             }
         }
@@ -12907,12 +13046,45 @@ export class SshTui {
             this.setupMessage(state, 'error', t('onboard.saveFailed', { error: errorChain(error) }));
         }
         finally {
-            this.onboarding = undefined;
             state.resolve(saved);
+            // The Screen's exit is the answer, and the answer is one of two things.
+            //
+            // **Saved**: the wizard has nothing left to ask, so it hands the workspace back
+            // in the same frame. Cancelling always did this; saving did not, so a completed
+            // setup left the reader on the wizard's own frame until they pressed a key —
+            // and only that key's "no wizard behind this Screen" fallback closed it. Every
+            // confirmation the wizard would have painted on its own row went with the
+            // Screen, which is why the completion line is a transcript row (`onboardDone`).
+            //
+            // **Failed**: the wizard keeps the screen, because the row it just wrote is the
+            // reason and the answer (an API key, a Base URL) has to stay editable to retry.
+            // Dropping the state here is what used to leave a Screen with no wizard behind
+            // it: the error was written and then thrown away with it, and the next keypress
+            // dismissed the whole flow as if nothing had been asked.
+            if (saved) {
+                this.onboarding = undefined;
+                this.closeScreen();
+            }
+            else {
+                state.saving = false;
+            }
             this.showNextDialog();
             this.markDirty();
         }
     }
+    /**
+     * Say the wizard is done, where the reader will still be able to read it.
+     *
+     * A saved wizard closes its Screen in the same frame, so its own notice row would
+     * be painted for no frames at all — and the credential line that goes with it is a
+     * footer echo (`command-feedback`), which expires. This is the durable half of the
+     * answer: `command-status` routes to the transcript, exactly like the boot line
+     * that asked for the setup in the first place.
+     */
+    onboardDone(text) {
+        this.pushRow(represent('command-status', { kind: 'system', text }));
+        this.markDirty();
+    }
     /** Store one credential, falling back to a launch-environment override on shadow/absence. */
     async saveCredential(credentials, envRef, key) {
         const shadowing = process.env[envRef];