handmux 0.21.0 → 0.22.1

package/README.md

@@ -68,20 +68,20 @@ handmux start --tunnel cloudflare   # instant public URL (cloudflared auto-insta
 ## Features
 
 - **Claude Code / Codex, deeply** — an inbox status ledger, thumb-approve permissions & plans, and stable host-wide usage bars shared by every connected device.
-- **Chat view (experimental)** — read and drive a Claude session as a chat instead of a terminal: bubbles with Markdown, tool cards with colored diffs, question cards you answer with a tap, warm colour tones. Experimental — may be unstable: enable it in Settings → 启用对话视图 / Enable chat view, then switch views from the window bar.
-- **Real-time terminal + desktop physical keyboard input** — terminal output streams as it happens on both phone and desktop. Scrolling up immediately browses recent tmux history without losing your place, pauses the stream when needed, and loads older history as you continue; returning to the bottom resynchronizes the live screen. When the source pane is shorter than the browser, spare rows show recent history above a faint dashed live boundary instead of empty space. Leaving the page pauses delivery; after 10 seconds away, returning starts from a fresh current screen instead of replaying stale output. **Live pushing** uses WebSocket, automatically falls back to **snapshot pulling** on a poor connection, and returns after 30 stable seconds. One top-right tag combines the actual mode and current latency; click it to see connection quality, the configured mode, fallback reason and retry countdown. Settings can keep this browser on snapshot pulling at an active interval from 0.8 to 2 seconds. On desktop, type into the current pane immediately without tapping “Show keyboard”; terminal-page keys keep working even after focus lands on the Window toolbar. `Shift+Enter` or the draft field opens draft mode with shortcuts, upload, history, voice and multiline editing intact. `Enter` sends and stays in draft mode, `Shift+Enter` inserts a newline, and IME Enter only confirms composition; press `Esc` or click the terminal to return to direct input. When a dialog, sheet, or menu is open, `Esc` closes only the top layer, one layer per press. Settings subpages stay stacked above Settings, so Back or `Esc` returns there before the main screen. Drag to select text, then copy/paste with `Cmd+C` / `Cmd+V` on macOS or `Ctrl+Shift+C` / `Ctrl+V` (or `Ctrl+Shift+V`) on Windows/Linux; `Ctrl+C` remains the terminal interrupt. Settings → Keyboard mode can auto-detect or force Mobile/Desktop for this browser only. Browser-reserved shortcuts such as `Cmd+W/T/L/R`, `F5`, and `F12` stay with the browser.
-- **Command & chat modes** — one bottom bar, two modes: type straight into the terminal, or talk to the agent in natural language. Both default quick bars include `Ctrl+C`. `handmux shortcuts` configures shared key/text items; each phone's ⚙ editor shows the effective quick-bar order, interleaves shared and local items, and can remove a shared item from that device only with immediate undo. Adding a phone-local item confirms success and returns directly to the list. Server changes apply live and phones reload them on foreground—no restart or polling required.
+- **Chat view (experimental)** — turn a Claude session into a mobile conversation with Markdown bubbles, colored tool diffs, and tap-to-answer cards; enable it in Settings and switch back to the terminal at any time.
+- **Real-time terminal + desktop keyboard** — stream the same tmux pane on phone and desktop with scrollback, weak-network fallback, direct physical-keyboard input, and native copy/paste.
+- **Command & chat modes** — switch between direct terminal input and natural-language agent chat, with a customizable quick bar that stays in sync across devices.
 - **Client reload after updates** — once the server update has finished, use Settings → Reload app to load the new client without quitting and reopening the home-screen app.
 - **Script push** — notify your phone from any script or CI step with `handmux push`; target all devices, a named session, or a specific device.
-- **Workspace recovery** — handmux silently keeps the metadata needed to rebuild your latest tmux workspace. After a computer or tmux-server restart, restore it beside any new sessions from the phone or with `handmux restore`; existing sessions are never replaced.
+- **Workspace recovery** — handmux keeps the metadata needed to restore your latest tmux workspace after a computer or tmux-server restart, without replacing existing sessions.
 - **Git viewer** — changes / commit history / any branch / full-screen colored diff, multi-repo tabs, read-only, never touches your tree.
-- **Web Preview for URLs and static folders** — Web Preview embeds pages inside Handmux; it is not a full browser. It is intended for development servers, localhost, intranet pages, and sites that allow embedding. New tabs default to the phone’s direct connection, while an optional computer proxy can reach the computer’s localhost and intranet without publishing them; run `handmux setup`, choose **Web preview**, and configure a proxy domain with wildcard routing and TLS to enable it. The **…** menu can open the original URL in the system browser, switch connection and phone/desktop view, set a per-tab background-close timer, and zoom through 75 / 80 / 90 / 100 / 110 / 125 / 150 / 175 / 200%. Zoom keeps the original page layout, exposes scrollbars for overflow, and leaves the page interactive while Handmux’s tab and address bars stay fixed. Direct pages remain subject to cross-origin iframe limits such as `X-Frame-Options`, CSP, third-party-cookie policy, unreadable titles/navigation, and failures that Handmux cannot always identify. Proxy mode forwards and rewrites pages, so despite WebSocket support it is usually slower and cannot guarantee compatibility with every site. Handmux never silently changes modes. Tabs, order, recent visits, and timers stay on the current device; only the selected tab shows Close, inactive tabs reserve no close-button space, and each new URL tab appends after every existing URL or static tab. Proxy tabs share only standards-matched Cookies on that device for SSO, not localStorage, IndexedDB, Service Workers, tabs, or direct-mode state. On Home, the address row’s folder button opens a static directory under the computer user’s home as a green tab with the same phone/desktop view and layout-preserving zoom. Successful static directories also appear in Recently Visited and reopen by directory with a fresh preview-only token; preview URLs and old tokens are not stored. Static content runs in an isolated iframe and cannot read the Handmux app token. Static tabs have no system-browser, connection, Cookie, timer, Stop, or Restart controls. Their server lease renews from actual page traffic, closing the tab releases it immediately, and an abandoned lease expires after two hours; reopening a saved tab recreates it automatically.
+- **Web Preview for URLs and static folders** — preview URLs by phone or computer proxy, or open an isolated static folder, with narrow/wide page widths and zoom; computer proxy can also request a mobile or desktop site version. It embeds pages rather than replacing a full browser.
 - **Docs** — tap a path in the terminal to open it; Markdown rendered, font zoom, sentence-by-sentence read-aloud.
 - **Mobile select & copy** — long-press to select in the terminal, drag iOS-style handles to fine-tune, copy the selection / a whole line / a whole paragraph.
 - **Files both ways** — multi-select upload from the chat box, download, share in, copy any absolute path.
 - **Ideas — catch every one** — a thought the moment it strikes: a per-window idea/to-do list, jot one by voice and drop it straight into the prompt.
 - **Built for flaky networks** — backoff reconnect, connection-lost banner, offline page, polling that pauses in the background; a reflow-safe cursor.
-- **Zero-install PWA** — runs in the browser; add to home screen for full-screen. Multilingual — English, 简体 / 繁體中文, 日本語, 한국어.
+- **Zero-install PWA** — runs full-screen from your home screen, with English, 简体 / 繁體中文, 日本語, and 한국어.
 
 ## Workspace recovery
 

package/README.zh-CN.md

@@ -68,20 +68,20 @@ handmux start --tunnel cloudflare   # 即时公网地址(自动装 cloudflared)
 ## 功能一览
 
 - **Claude Code / Codex 深度**——收件箱状态台账、拇指批授权批计划，以及所有设备共享的本机最新 agent 用量。
-- **对话视图（实验性）**——把 Claude 会话当成聊天来看、来驱动,而不是终端:气泡 + Markdown 正文、带彩色 diff 的工具卡、点按即答的问题卡、暖色配色。实验性功能,可能不稳定:在设置里开启「启用对话视图(实验性功能)」后,从窗口栏切换视图。
-- **实时终端 + 电脑物理键盘直输**——手机和电脑上的终端输出都会实时出现；首次向上滑动即可查看最近的 tmux 历史，继续向上会加载更早内容，回到底部再重新同步，不会丢位置。远端 pane 比浏览器矮时，多出的区域会展示最近历史，并用一条很浅的破折线标出实时画面的起点，不再留出大片空白。离开页面会立即暂停传输；超过 10 秒后回来会直接抓取最新画面，不再补画旧输出。「实时推送」使用 WebSocket，网络较差时自动临时回退到「快照拉取」，持续稳定 30 秒后自动切回；右上角用一个标签合并显示当前模式和延迟，点击后可查看连接状态、设置模式、降级原因和恢复倒计时。也可在设置里固定使用「快照拉取」，并选择 0.8–2 秒的活跃刷新频率。电脑浏览器打开同一个 Handmux URL，无需点「展开键盘」即可直接输入当前 tmux pane；即使焦点落在 Window 工具栏，终端页面上的按键仍会继续发送给当前 pane。按 `Shift+Enter` 或点击草稿框进入草稿模式，快捷用语、上传、历史、语音和多行自动增高全部保留。`Enter` 发送后仍停留在草稿模式，`Shift+Enter` 换行，输入法合成中的 Enter 只确认候选词，按 `Esc` 或点击终端回到直通模式；有弹窗、浮窗或菜单时，`Esc` 每次只关闭最上层，连续按键可逐层返回。设置中的二级页面会保留设置父层，返回或 `Esc` 会先回到设置，再回到主屏。终端文字可直接用鼠标拖选，macOS 按 `Cmd+C` / `Cmd+V`、Windows / Linux 按 `Ctrl+Shift+C` / `Ctrl+V`（或 `Ctrl+Shift+V`）复制粘贴，`Ctrl+C` 仍是终端中断。设置里的「键盘模式」可选自动识别、手机或电脑，选择只影响当前浏览器；`Cmd+W/T/L/R`、`F5`、`F12` 等浏览器保留按键不发送到终端。
-- **命令 / 聊天双模式**——底部一栏两种模式:直接敲进终端,或用自然语言发给 agent;两种默认快捷栏都有 `Ctrl+C`。`handmux shortcuts` 配置所有设备共享的按键 / 文字项;每台手机的 ⚙ 编辑器按快捷栏实际顺序统一显示共享与本机项,可自由混排,也可只从本机移除共享项并即时撤销。本机新增成功后会明确提示并直接返回列表。服务端修改立即生效,手机回到前台自动读取,无需重启或轮询。
+- **对话视图（实验性）**——用 Markdown 气泡、彩色工具 diff 和点按回答卡片把 Claude 会话变成移动端对话，可在设置中开启并随时切回终端。
+- **实时终端 + 电脑键盘**——在手机和电脑上实时操控同一个 tmux pane，支持历史滚动、弱网回退、物理键盘直输和原生复制粘贴。
+- **命令 / 聊天双模式**——在终端直输与自然语言对话间切换，并用跨设备同步的快捷栏快速操作。
 - **更新后重新加载客户端**——服务端更新完成后，在设置里点「重新加载应用」即可载入新版客户端，无需退出主屏应用再重新打开。
 - **脚本推送**——用 `handmux push` 从脚本或 CI 步骤推消息到手机,可指定全部设备、某个会话或某台设备。
-- **工作区恢复**——handmux 静默保存重建最新 tmux 工作区所需的元数据。电脑或 tmux server 重启后,可从手机或 `handmux restore` 把旧工作区恢复到新会话旁边,绝不替换现有会话。
+- **工作区恢复**——handmux 静默保存必要元数据，在电脑或 tmux server 重启后恢复最新工作区，绝不替换现有会话。
 - **Git 查看器**——改动 / 提交历史 / 任意分支 / 全屏彩色 diff,多仓库分页,只读不动工作区。
-- **网页预览器统一预览网址与静态目录**——网页预览器把页面嵌入 Handmux，它不是真正的浏览器，适合预览开发服务、localhost、内网和允许嵌入的网站。新页签默认手机直连；可在电脑运行 `handmux setup`、选择“网页预览器”，配置代理域名及通配路由 / TLS 后，经电脑访问其 localhost 和内网，无需对外发布。“…”菜单可用系统浏览器打开原网址、切换连接方式与手机 / 电脑视图、设置页签后台关闭时间，并按 75 / 80 / 90 / 100 / 110 / 125 / 150 / 175 / 200% 缩放。缩放保持网页原有布局，通过滚动条查看溢出内容；网页始终可交互，Handmux 的标签栏和地址栏保持固定。手机直连仍受跨域 iframe 限制，例如 `X-Frame-Options`、CSP、第三方 Cookie、标题与页面内跳转不可读，Handmux 也不一定能判断失败原因。电脑代理会转发并改写网页，即使支持 WebSocket，通常也更慢，且不保证兼容所有网站；系统不会静默切换模式。标签页、顺序、最近访问和计时只存在当前设备；只有当前标签显示关闭按钮，未选中标签不预留关闭按钮空间，新打开的网页标签始终追加到现有网址与静态标签之后。同一设备的代理页签仅按真实目标 Cookie 规则共享 Cookie 以复用 SSO，不共享 localStorage、IndexedDB、Service Worker、标签或直连状态。Home 地址栏右侧的目录按钮可选择电脑用户目录下的静态目录，在同一个预览器里打开为绿色静态标签，并复用手机 / 电脑视图及保持布局的缩放。成功打开的静态目录也会进入“最近访问”，再次点击会按目录获取新的预览专用 token，不保存预览地址或旧 token；静态内容运行在隔离 iframe 中，无法读取 Handmux 主应用 token。静态标签不提供系统浏览器、连接方式、Cookie、后台计时、停止或重启入口；真实页面访问会自动续租，关闭标签立即释放，异常遗留的租约会在两小时后过期，重新打开已保存标签时会自动恢复。
+- **网页预览器**——用手机直连或电脑代理预览网址，也可隔离打开静态目录，支持窄屏 / 宽屏和缩放；电脑代理还可向网站请求手机版或电脑版。它只嵌入网页，不替代完整浏览器。
 - **文档**——终端里点路径即开;Markdown 排版、字号缩放、逐句高亮朗读。
 - **选中 · 拷贝**——终端里长按选中,拖 iOS 式手柄精调,一键拷贝选区 / 整行 / 整段。
 - **文件双向传**——聊天框多选上传、下载、系统分享进来、复制绝对路径。
 - **想法 · 随想随记**——不错过任何点子:每窗口一份想法清单,灵感一冒就记(能语音速记),一点填进输入框。
 - **专治弱网**——退避重连、掉线横幅、离线兜底页、后台暂停轮询;光标不乱跳。
-- **零安装 PWA**——浏览器直接跑,可加主屏全屏运行;多语言(English、简体 / 繁體中文、日本語、한국어)。
+- **零安装 PWA**——添加到主屏即可全屏运行，支持 English、简体 / 繁體中文、日本語和 한국어。
 
 ## 工作区恢复
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -41,6 +41,7 @@
     "bundle": "node scripts/bundle-web.mjs",
     "prepack": "node scripts/bundle-web.mjs",
     "test": "vitest run",
+    "test:workspace-host": "HANDMUX_WORKSPACE_HOST=1 vitest run test/workspaceHost.test.js",
     "test:workspace-docker": "HANDMUX_WORKSPACE_DOCKER=1 vitest run test/workspaceDocker.test.js"
   },
   "dependencies": {
@@ -61,13 +62,13 @@
     "vitest": "^2.0.0"
   },
   "whatsNew": [
+    {"version":"0.22.1","date":"2026-08-04","zh":"网页宽度与网站版本分开控制","en":"Separate page width and site-version controls"},
+    {"version":"0.22.0","date":"2026-08-03","zh":"全屏设置 · 窗口与分屏管理更清晰","en":"Full-screen Settings · clearer window and pane management"},
     {"version":"0.21.0","date":"2026-08-03","zh":"网页预览：手机直连、电脑代理与静态目录","en":"Web preview: direct, computer proxy, and static folders"},
     {"version":"0.20.3","date":"2026-08-01","zh":"实时终端显示更稳定流畅","en":"More stable, smoother live terminals"},
     {"version":"0.20.2","date":"2026-07-27","zh":"实时终端长时间运行更流畅","en":"Smoother long-running live terminals"},
     {"version":"0.20.1","date":"2026-07-26","zh":"聊天发送修复 · 电脑键盘不中断","en":"Reliable chat sending · uninterrupted desktop input"},
     {"version":"0.20.0","date":"2026-07-26","zh":"终端实时推送 · 弱网自动回退","en":"Live terminal pushing · automatic network fallback"},
-    {"version":"0.19.0","date":"2026-07-25","zh":"电脑物理键盘直输 · Window 切换更流畅","en":"Desktop keyboard input · faster window switching"},
-    {"version":"0.18.0","date":"2026-07-22","zh":"Tmux 工作区恢复 · 快捷栏自由定制","en":"Tmux workspace recovery · customizable shortcuts"},
-    {"version":"0.17.8","date":"2026-07-20","zh":"分屏地图显示尺寸 · iPhone 交互修复","en":"Pane dimensions in the map · iPhone interaction fixes"}
+    {"version":"0.19.0","date":"2026-07-25","zh":"电脑物理键盘直输 · Window 切换更流畅","en":"Desktop keyboard input · faster window switching"}
   ]
 }