handmux 0.18.0 → 0.20.0

package/public/index.html

@@ -22,8 +22,8 @@
     <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png?v=2" />
 
     <!-- Inline boot splash: paints instantly (before the JS bundle loads) so a cold launch shows the
-         brand, not a blank dark screen. main.jsx calls window.__hideBootSplash() once React has painted;
-         a safety timer hides it even if the bundle never boots. Self-contained here — no app code. -->
+         brand, not a blank dark screen. main.jsx calls window.__hideBootSplash() once React has painted.
+         Until then it must remain visible: a slow bundle should never expose the still-empty app root. -->
     <style>
       html, body { margin: 0; background: #1a1b1e; } /* opaque dark from frame one — no wallpaper showing through */
       #boot-splash { position: fixed; inset: 0; z-index: 9999; display: flex; flex-direction: column;
@@ -48,8 +48,8 @@
       @keyframes bootDot { 0%,100% { opacity: .22; transform: translateY(0); } 40% { opacity: 1; transform: translateY(-3px); } }
       @media (prefers-reduced-motion: reduce) { .boot-glow, .boot-dots i { animation: none; opacity: .8; } }
     </style>
-    <script type="module" crossorigin src="/assets/index-CvNuQ-bC.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DjJf1FX9.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-DjJf1FX9.css"></noscript>
+    <script type="module" crossorigin src="/assets/index-DkaDRYCU.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DCZuq0nO.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-DCZuq0nO.css"></noscript>
   </head>
   <body>
     <div id="boot-splash" aria-hidden="true">
@@ -63,7 +63,7 @@
     <div id="root"></div>
     <script>
       // Hide the splash once the app has painted (main.jsx), but keep it up at least ~650ms so the glow
-      // is actually seen, not a flicker. Safety: hide after 8s no matter what, so a failed boot never traps it.
+      // is actually seen, not a flicker. Slow or unavailable bundles leave this branded loading state visible.
       window.__bootStart = Date.now();
       window.__hideBootSplash = function () {
         var el = document.getElementById('boot-splash');
@@ -74,7 +74,6 @@
           setTimeout(function () { if (el.parentNode) el.parentNode.removeChild(el); }, 500);
         }, wait);
       };
-      setTimeout(function () { window.__hideBootSplash(); }, 8000);
     </script>
   </body>
 </html>

package/src/captureBackground.js

@@ -0,0 +1,93 @@
+const CSI = /\x1b\[([0-9;]*)m/g;
+const ANSI = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))/g;
+
+function backgroundAfter(line, initial) {
+  let background = initial;
+  const sgr = new RegExp(CSI.source, 'g');
+  let match = sgr.exec(line);
+  while (match) {
+    const params = match[1] === '' ? [0] : match[1].split(';').map(Number);
+    for (let i = 0; i < params.length; i += 1) {
+      const value = params[i];
+      if (value === 0 || value === 49) background = false;
+      else if ((value >= 40 && value <= 47) || (value >= 100 && value <= 107)) background = true;
+      else if (value === 38 || value === 48) {
+        const isBackground = value === 48;
+        if (params[i + 1] === 5) {
+          i += 2;
+          if (isBackground) background = true;
+        } else if (params[i + 1] === 2) {
+          i += 4;
+          if (isBackground) background = true;
+        }
+      }
+    }
+    match = sgr.exec(line);
+  }
+  return background;
+}
+
+function paintsBackground(line) {
+  let background = false;
+  let offset = 0;
+  const sgr = new RegExp(CSI.source, 'g');
+  let match = sgr.exec(line);
+  while (match) {
+    if (background && match.index > offset) return true;
+    background = backgroundAfter(match[0], background);
+    offset = sgr.lastIndex;
+    match = sgr.exec(line);
+  }
+  return background && offset < line.length;
+}
+
+const isBlank = (line) => line.replace(ANSI, '').trim() === '';
+
+// `capture-pane -e -N` compresses SGR state across newlines. A default blank row after a shaded
+// row (Claude) and a genuinely shaded padding row (Codex) therefore look identical in the combined
+// capture. Capturing just that row makes tmux emit the row's real starting attributes. Only those
+// ambiguous rows need the extra read; ordinary rows keep the single fast combined capture.
+export function ambiguousBackgroundRows(lines) {
+  const indexes = [];
+  let background = false;
+  let inBlankRun = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const ambiguous = background && isBlank(line);
+    // One row resolves the whole trailing run: default closes it before the first LF; shaded is the
+    // one real padding row the client preserves and seals before clearing any additional blanks.
+    if (ambiguous && !inBlankRun) indexes.push(index);
+    inBlankRun = ambiguous;
+    background = backgroundAfter(line, background);
+  }
+  return indexes;
+}
+
+export async function restoreBlankRowBackgrounds(lines, historyLines, readRow) {
+  const restored = [...lines];
+  const indexes = ambiguousBackgroundRows(lines);
+  await Promise.all(indexes.map(async (index) => {
+    const row = index - historyLines;
+    const exact = await readRow(row);
+    // A separately-captured default row has no background SGR. Explicitly close the combined
+    // stream's inherited background before replaying it. A real padding row starts with its own
+    // background SGR and is preserved verbatim.
+    restored[index] = paintsBackground(exact) ? exact : `\x1b[49m${exact}`;
+  }));
+  return restored;
+}
+
+export async function restoreCaptureBackgrounds(capture, paneHeight, readRow) {
+  const trailingNewline = capture.endsWith('\n');
+  const body = trailingNewline ? capture.slice(0, -1) : capture;
+  const lines = body.split('\n');
+  const historyLines = Math.max(0, lines.length - paneHeight);
+  const restored = await restoreBlankRowBackgrounds(lines, historyLines, async (row) => {
+    const exact = await readRow(row);
+    return exact.endsWith('\n') ? exact.slice(0, -1) : exact;
+  });
+  return {
+    ansi: restored.join('\n') + (trailingNewline ? '\n' : ''),
+    historyLines,
+  };
+}

package/src/cli/codexHooks.js

@@ -105,6 +105,16 @@ export function installCodexHooks(home = homedir(), { srcDir, stateFile } = {})
   return { status: 'installed' };
 }
 
+// Refresh scripts for an already opted-in install on server restart. Never enables hooks or rewrites
+// config.toml; it only replaces our deployed script bytes with this handmux version.
+export function syncCodexHooks(home = homedir(), { srcDir, stateFile } = {}) {
+  // The marked config is the durable opt-in signal. Refresh it even when a service manager's PATH cannot
+  // resolve the user's Codex binary; never turn a hook off merely because Node installations switched.
+  if (!readConf(home).includes(BEGIN)) return { status: codexHooksStatus(home), changed: false };
+  deployHookScripts(hooksDir(home), srcDir, stateFile);
+  return { status: 'installed', changed: false };
+}
+
 // Uninstall: strip our config.toml region and remove the copied scripts/env. Best-effort.
 export function uninstallCodexHooks(home = homedir()) {
   if (fs.existsSync(configPath(home))) writeFileAtomic(configPath(home), stripCodexHooks(readConf(home)));

package/src/cli/hookScaffold.js

@@ -5,9 +5,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-// The two scripts every agent hook installer deploys. Shared because the stdin payloads are identical across
-// agents (Codex mirrors Claude's hook contract), so the same notify/write pair drives both.
-export const HOOK_SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs'];
+// Scripts every agent hook installer deploys. The notify/write pair is shared because Codex mirrors
+// Claude's hook contract; the small Codex usage reader is inert unless handmux-write receives agent=codex.
+export const HOOK_SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs', 'handmux-codex-usage.cjs'];
 
 // Atomic write (tmp + rename) so a crash can't leave a half-written config file. Text in, text out — callers
 // pass raw TOML for config.toml, or use writeJsonAtomic for pretty-printed settings.json.

package/src/cli/i18n/en.js

@@ -285,7 +285,7 @@ export default {
   'setup.sshReady': '✓ passwordless SSH already set up',
   'setup.sshSetup': "→ setting up passwordless SSH to {host} (you'll enter the password once) …",
   'setup.sshHelp1': 'Server side (one-time): point a reverse proxy at the forwarded loopback port.',
-  'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  (add client_max_body_size 60m; proxy_read_timeout 90s;)',
+  'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  also set proxy_http_version 1.1, the Upgrade/Connection WebSocket headers, client_max_body_size 60m, and proxy_read_timeout 90s;',
   'setup.sshHelpCaddy': '  caddy:  {url} {  reverse_proxy 127.0.0.1:{port}  }',
   'setup.previewAbout': 'Open a development service running on this machine by port from your phone. Static directory preview still works without this setting.',
   'setup.previewRoute': 'Enter only the preview domain (for example, preview.example.com). handmux uses <project-name>.preview.example.com; route *.preview.example.com to the handmux gateway.',

package/src/cli/i18n/zh.js

@@ -284,7 +284,7 @@ export default {
   'setup.sshReady': '✓ 免密 SSH 已配置好',
   'setup.sshSetup': '→ 正在配置到 {host} 的免密 SSH(你需要输入一次密码)…',
   'setup.sshHelp1': '服务端(一次性):把反向代理指向被转发的 loopback 端口。',
-  'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  (加上 client_max_body_size 60m; proxy_read_timeout 90s;)',
+  'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  并设置 proxy_http_version 1.1、Upgrade/Connection WebSocket 头、client_max_body_size 60m、proxy_read_timeout 90s;',
   'setup.sshHelpCaddy': '  caddy:  {url} {  reverse_proxy 127.0.0.1:{port}  }',
   'setup.previewAbout': '用于在手机上按端口打开本机正在运行的开发服务；不配置时，静态目录预览仍可使用。',
   'setup.previewRoute': '只填预览域名（如 preview.example.com）。handmux 会使用 <项目名>.preview.example.com；请将 *.preview.example.com 路由到 handmux 网关。',

package/src/routes/system.js

@@ -106,11 +106,10 @@ export function systemRoutes({ commands, claudeEvents, asrEnv, shortcuts, home,
     try { res.json(await claudeEvents.getStates(allowed)); } catch (e) { next(e); }
   });
 
-  // Agent usage/quota for the Usage page. Disk-only, no credentials: Claude's 5h/weekly % from the
-  // statusLine snapshot (if the capturer is opted in), Codex's rate_limits + tokens from its newest
-  // rollout. Either side is null when unavailable. Cached briefly (see usage.js); never throws.
-  r.get('/usage', (req, res, next) => {
-    try { res.json(getUsageCached(home)); } catch (e) { next(e); }
+  // Agent usage/quota for the Usage page. Claude reads its statusLine snapshot; Codex asks its own local
+  // app-server for account limits and merges rollout token/context data. Cached briefly; never handles auth.
+  r.get('/usage', async (req, res, next) => {
+    try { res.json(await getUsageCached(home)); } catch (e) { next(e); }
   });
 
   // Orphan Claude sessions: `claude` processes running on this host but NOT inside a tmux pane, so

package/src/routes/terminal.js

@@ -6,6 +6,7 @@ import { gzipSync } from 'node:zlib';
 import { isPaneId, isWindowId } from '../tmux/commands.js';
 import { capTrailingBlankRows } from '../trimCapture.js';
 import { isAllowedKey } from '../keyNames.js';
+import { restoreCaptureBackgrounds } from '../captureBackground.js';
 
 export { isAllowedKey } from '../keyNames.js';
 
@@ -19,7 +20,16 @@ export { isAllowedKey } from '../keyNames.js';
 // beat to ingest the pasted line; without it, the Enter can fold into the input as a newline
 // instead of submitting. 120ms is imperceptible but enough to settle.
 const SUBMIT_GAP_MS = 120;
+const RAW_INPUT_MAX_BYTES = 16 * 1024;
 const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+const validHexInput = (hex) => typeof hex === 'string'
+  && hex.length >= 2
+  && hex.length <= RAW_INPUT_MAX_BYTES * 2
+  && hex.length % 2 === 0
+  && /^[0-9a-f]+$/i.test(hex);
+const isMissingPane = (error) =>
+  /(?:can't find|cannot find|no such|unknown|not found).*\bpane\b|\bpane\b.*(?:can't find|cannot find|no such|unknown|not found)/i
+    .test(error instanceof Error ? error.message : String(error));
 
 export function terminalRoutes({ commands }) {
   const r = express.Router();
@@ -37,13 +47,28 @@ export function terminalRoutes({ commands }) {
       // pane as exactly its visible screen (lines=0) and skip the blank-trim. A normal pane still pulls
       // `lines` of scrollback and caps the empty grid below the cursor (fresh shell = "prompt + a wall of
       // blank rows") so the phone's bottom-anchored render shows content, not blank. See trimCapture.js.
-      const raw = await commands.capturePane(req.query.pane, altScreen ? 0 : lines);
+      const captured = await commands.capturePane(req.query.pane, altScreen ? 0 : lines);
+      const restored = typeof commands.capturePaneRow === 'function'
+        ? await restoreCaptureBackgrounds(
+          captured,
+          height,
+          (row) => commands.capturePaneRow(req.query.pane, row),
+        )
+        : {
+          ansi: captured,
+          historyLines: Math.max(
+            0,
+            (captured.endsWith('\n') ? captured.slice(0, -1) : captured).split('\n').length - height,
+          ),
+        };
+      const raw = restored.ansi;
       const ansi = altScreen ? raw : capTrailingBlankRows(raw);
       // The cursor's row counted from the BOTTOM of the (trimmed) capture. The live screen is the
       // capture's last `height` rows, so the cursor sits `height-1-cursorY` rows above the bottom —
       // less however many trailing blank rows capTrailingBlankRows dropped (all of them below the
       // cursor). The client re-places xterm's cursor this many rows up from the seed's last row.
       const rowsOf = (s) => (s.endsWith('\n') ? s.slice(0, -1) : s).split('\n').length;
+      const historyLines = altScreen ? 0 : restored.historyLines;
       const cur = {
         row: Math.max(0, (height - 1 - cursorY) - (rowsOf(raw) - rowsOf(ansi))),
         col: cursorX, vis: cursorVisible,
@@ -58,7 +83,9 @@ export function terminalRoutes({ commands }) {
         .update(`${width}x${height}\n${cur.col},${cursorY},${cur.vis ? 1 : 0}\n${altScreen ? 1 : 0}${mouseAware ? 'm' : ''}\n${ansi}`)
         .digest('hex').slice(0, 16);
       if (req.query.since === hash) return res.status(204).end();
-      const json = JSON.stringify({ ansi, width, height, hash, cur, alt: altScreen, mouseAware });
+      const json = JSON.stringify({
+        ansi, width, height, historyLines, hash, cur, alt: altScreen, mouseAware,
+      });
       res.set('Content-Type', 'application/json');
       res.set('Vary', 'Accept-Encoding'); // both 200 branches vary on encoding (correct for any caching proxy)
       // Capture text is mostly SGR codes + spaces — gzip crushes it ~10x. (204s are empty, never gzipped.)
@@ -87,6 +114,20 @@ export function terminalRoutes({ commands }) {
     } catch (e) { next(e); }
   });
 
+  r.post('/input', async (req, res, next) => {
+    const { pane, hex } = req.body || {};
+    if (!isPaneId(pane)) return res.status(400).json({ error: 'bad pane id' });
+    if (!validHexInput(hex)) return res.status(400).json({ error: 'bad input bytes' });
+    try {
+      await commands.exitCopyModeIfActive(pane);
+      await commands.sendHexInput(pane, hex);
+      res.json({ ok: true });
+    } catch (error) {
+      if (isMissingPane(error)) return res.status(404).json({ error: 'pane not found' });
+      next(error);
+    }
+  });
+
   // Resize the tmux window so it reflows to the phone (auto:false), or hand sizing back to
   // attached clients (auto:true). NOTE: this mutates the shared window — the PC's view of it
   // changes too.

package/src/server.js

@@ -8,10 +8,12 @@ import { createApiRouter } from './httpApi.js';
 import { loadUploadExts } from './uploadTypes.js';
 import { createClaudeEvents } from './claudeEvents.js';
 import { syncHooks } from './cli/claudeHooks.js';
+import { syncCodexHooks } from './cli/codexHooks.js';
 import { claudeStatePath } from './cli/state.js';
 import * as commands from './tmux/commands.js';
 import * as push from './push.js';
 import { cacheControlFor } from './staticCache.js';
+import { compressStaticAssets } from './staticCompression.js';
 import { applyAppName, applyManifestName } from './appName.js';
 import { homedir } from 'node:os';
 import { createPreviews } from './previews.js';
@@ -22,6 +24,7 @@ import { createEnvironmentProvider } from './workspace/environment.js';
 import { createWorkspaceLock } from './workspace/lock.js';
 import { createGracefulShutdown, createWorkspaceBackground } from './workspace/checkpointer.js';
 import { createWorkspaceRuntime } from './workspace/runtime.js';
+import { createTerminalStream } from './terminalStream.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
@@ -80,6 +83,12 @@ try {
     stateFile,
   });
 } catch { /* best effort — hook sync never fails startup */ }
+try {
+  syncCodexHooks(home, {
+    srcDir: path.resolve(here, '../hooks'),
+    stateFile,
+  });
+} catch { /* best effort — hook sync never fails startup */ }
 
 // Static-site + dynamic preview. The dynamic side is enabled by HANDMUX_PREVIEW_DOMAIN (the wildcard
 // base domain, e.g. preview.example.com); unset → static only. One registry instance is shared by the
@@ -119,6 +128,7 @@ if (appName) {
 }
 
 // index:false so the renamed shell below owns "/" too (otherwise static would serve the generic one).
+app.use(compressStaticAssets);
 app.use(express.static(staticDir, {
   index: false,
   // Cache-Control policy lives in staticCache.js (unit-tested): index.html + sw.js are never cached
@@ -142,10 +152,17 @@ app.get('*', (req, res, next) => {
 const server = app.listen(cfg.port, cfg.host, () => {
   console.log(`[handmux] listening on http://${cfg.host}:${cfg.port} (serving ${staticDir})`);
 });
-// WebSocket/HMR for dynamic previews: route raw Upgrade by Host to the right loopback port.
-server.on('upgrade', preview.onUpgrade);
+const terminalStream = createTerminalStream({ token, commands });
+// The terminal stream owns one exact path. Every other Upgrade keeps using the existing
+// dynamic-preview router unchanged.
+server.on('upgrade', (req, socket, head) => {
+  if (!terminalStream.onUpgrade(req, socket, head)) preview.onUpgrade(req, socket, head);
+});
 
 const shutdown = createGracefulShutdown({ events, workspace, server });
-const handleSignal = () => { shutdown().catch(() => {}); };
+const handleSignal = () => {
+  terminalStream.close();
+  shutdown().catch(() => {});
+};
 process.on('SIGINT', handleSignal);
 process.on('SIGTERM', handleSignal);

package/src/staticCompression.js

@@ -0,0 +1,10 @@
+import compression from 'compression';
+
+const compress = compression({ threshold: 1024 });
+
+// Only compress Vite's content-hashed frontend assets. API responses keep their existing
+// latency/streaming behavior, while the large JS/CSS needed for first paint becomes much smaller.
+export function compressStaticAssets(req, res, next) {
+  if (!req.path.startsWith('/assets/')) return next();
+  return compress(req, res, next);
+}