handmux 0.20.2 → 0.21.0

package/README.md

@@ -8,7 +8,7 @@
   <a href="https://www.npmjs.com/package/handmux"><img src="https://img.shields.io/npm/v/handmux?color=cb3837&logo=npm" alt="npm"></a>
   <a href="https://github.com/handmux/handmux/actions/workflows/test.yml"><img src="https://github.com/handmux/handmux/actions/workflows/test.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="license: AGPL-3.0"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white" alt="node"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white" alt="node"></a>
 </p>
 
 > **One phone, a whole mobile vibe-coding cockpit.** Built on tmux — one command on your computer, scan a QR, and your live session, Claude Code, Codex, git, previews and docs are all in your hand, creativity ready wherever you are.
@@ -27,7 +27,7 @@ handmux is more than a terminal on your phone. It puts the *same* live **tmux**
 
 ## Quick start · about a minute
 
-Your computer needs tmux and Node ≥ 18; the phone just needs a browser. Pick one:
+Your computer needs tmux and Node ≥ 20; the phone just needs a browser. Pick one:
 
 **Homebrew — macOS (recommended)** · installs Node + tmux for you:
 
@@ -75,7 +75,7 @@ handmux start --tunnel cloudflare   # instant public URL (cloudflared auto-insta
 - **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.
 - **Git viewer** — changes / commit history / any branch / full-screen colored diff, multi-repo tabs, read-only, never touches your tree.
-- **Site preview** — a static folder, or a running HTTP/HTTPS service by port (routing / APIs / live-reload intact), in a phone or desktop viewport. Set its bare preview domain once in `handmux setup`.
+- **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.
 - **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.
@@ -140,13 +140,13 @@ No tunnel by default — the phone connects **straight to your own computer**, n
 - **Yes** (cloud box / public IP / forwarded port) — no tunnel needed, connect directly; fastest and most private.
 - **No** — open a tunnel. Each runs on **your own free third-party account** — handmux just wires it up and operates no relay of its own: `cloudflare` (zero-config, up in seconds, but its public edge can be slow or unreliable in some regions) · `cloudflare-named` (your own domain, steadier) · `natapp` / `cpolar` (domestic providers that stay reachable inside mainland China) · `ssh` self-hosted (through your own server).
 
-> Tunnel config, server-side reverse proxy, autostart, voice/push credentials, and port previews → see the **[docs](https://handmux.com/docs)**.
+> Tunnel config, Web Preview, autostart, and voice/push credentials → see the **[docs](https://handmux.com/docs)**.
 
 Once autostart is installed, `handmux start` / `stop` / `restart` coordinate with that same launchd/systemd service (including after an upgrade). A lifecycle lock prevents concurrent launches; `status` shows the running version and warns with PIDs if stale/duplicate supervisors exist, while `stop` reaps every copy.
 
 ## Requirements
 
-Your computer needs **Node ≥ 18** and **tmux ≥ 3.0**; the phone just needs a browser. On **Windows**, run it inside **WSL2** (a real Linux kernel + real tmux) — see the [docs](https://handmux.com/docs#windows).
+Your computer needs **Node ≥ 20** and **tmux ≥ 3.0**; the phone just needs a browser. On **Windows**, run it inside **WSL2** (a real Linux kernel + real tmux) — see the [docs](https://handmux.com/docs#windows).
 
 ## Feedback & community
 

package/README.zh-CN.md

@@ -8,7 +8,7 @@
   <a href="https://www.npmjs.com/package/handmux"><img src="https://img.shields.io/npm/v/handmux?color=cb3837&logo=npm" alt="npm"></a>
   <a href="https://github.com/handmux/handmux/actions/workflows/test.yml"><img src="https://github.com/handmux/handmux/actions/workflows/test.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="license: AGPL-3.0"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white" alt="node"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white" alt="node"></a>
 </p>
 
 > **一部手机,一整套移动 Vibe Coding 驾驶舱。** 基于 tmux——电脑上一行命令、手机扫码,你正跑着的会话、Claude Code、Codex、git、预览、文档全到手里,创造力随时随地都在你手上。
@@ -27,7 +27,7 @@ handmux 不只是把终端搬上手机。它把你电脑上**正跑着的 tmux
 
 ## 快速上手 · 约一分钟
 
-**电脑上**需要 tmux 和 Node ≥ 18(手机只要个浏览器)。二选一:
+**电脑上**需要 tmux 和 Node ≥ 20(手机只要个浏览器)。二选一:
 
 **Homebrew —— macOS 首选** · 顺带帮你装好 Node + tmux:
 
@@ -75,7 +75,7 @@ handmux start --tunnel cloudflare   # 即时公网地址(自动装 cloudflared)
 - **脚本推送**——用 `handmux push` 从脚本或 CI 步骤推消息到手机,可指定全部设备、某个会话或某台设备。
 - **工作区恢复**——handmux 静默保存重建最新 tmux 工作区所需的元数据。电脑或 tmux server 重启后,可从手机或 `handmux restore` 把旧工作区恢复到新会话旁边,绝不替换现有会话。
 - **Git 查看器**——改动 / 提交历史 / 任意分支 / 全屏彩色 diff,多仓库分页,只读不动工作区。
-- **站点预览**——挑目录预览静态站,或按端口预览正跑的 HTTP/HTTPS 服务(路由 / 接口 / HMR 全保留)；动态预览域名在 `handmux setup` 里一次配好即可。
+- **网页预览器统一预览网址与静态目录**——网页预览器把页面嵌入 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 式手柄精调,一键拷贝选区 / 整行 / 整段。
 - **文件双向传**——聊天框多选上传、下载、系统分享进来、复制绝对路径。
@@ -140,13 +140,13 @@ handmux push <title> <body> [选项]
 - **有**(云主机 / 公网 IP / 已端口转发)—— 不用隧道,直接连,最快也最私密。
 - **没有** —— 开一条隧道。每条都跑在**你自己的免费第三方账号**上,handmux 只负责接通、自身不设中转:`cloudflare`(零配置秒通,但公共边缘在国内常不稳)· `cloudflare-named`(你的域名,更稳)· `natapp` / `cpolar`(国内厂商,大陆境内可达)· `ssh` 自建(接你自己的服务器)。
 
-> 隧道配置、服务端反向代理、开机自启、语音 / 推送凭证、端口预览等细节 → 见 **[文档](https://handmux.com/docs)**。
+> 隧道配置、网页预览器、开机自启、语音 / 推送凭证等细节 → 见 **[文档](https://handmux.com/docs)**。
 
 安装开机自启后，`handmux start` / `stop` / `restart` 会始终与同一个 launchd/systemd 服务协同（升级后也一样）。生命周期锁会阻止并发启动；`status` 显示实际运行版本，并列出未登记/重复 supervisor 的 PID；`stop` 会回收全部副本。
 
 ## 环境要求
 
-电脑需 **Node ≥ 18** 与 **tmux ≥ 3.0**;手机只要浏览器。**Windows** 请装进 **WSL2**(真 Linux 内核 + 真 tmux)——见 [文档](https://handmux.com/docs#windows)。
+电脑需 **Node ≥ 20** 与 **tmux ≥ 3.0**;手机只要浏览器。**Windows** 请装进 **WSL2**(真 Linux 内核 + 真 tmux)——见 [文档](https://handmux.com/docs#windows)。
 
 ## 反馈与交流
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "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",
@@ -22,7 +22,7 @@
     "pwa"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "bin": {
     "handmux": "bin/handmux.js"
@@ -48,6 +48,7 @@
     "busboy": "^1.6.0",
     "compression": "^1.8.1",
     "express": "^4.19.2",
+    "testcafe-hammerhead": "31.7.8",
     "tunlite": "^0.10.0",
     "web-push": "^3.6.7",
     "ws": "^8.21.0"
@@ -60,13 +61,13 @@
     "vitest": "^2.0.0"
   },
   "whatsNew": [
+    {"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.17.7","date":"2026-07-20","zh":"单实例启动兜底 · WSL 状态命令修复","en":"Single-instance startup guard · WSL status fix"},
-    {"version":"0.17.6","date":"2026-07-20","zh":"推送结果可追踪 · 对话与权限操作更可靠","en":"Traceable push results · safer chats and permissions"}
+    {"version":"0.17.8","date":"2026-07-20","zh":"分屏地图显示尺寸 · iPhone 交互修复","en":"Pane dimensions in the map · iPhone interaction fixes"}
   ]
 }