handmux 0.20.3 → 0.22.0

package/src/browser/targetPolicy.js

@@ -0,0 +1,137 @@
+import dns from 'node:dns/promises';
+import net from 'node:net';
+
+function ipv4Parts(address) {
+  const parts = address.split('.').map(Number);
+  return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)
+    ? parts
+    : null;
+}
+
+function ipv6Words(address) {
+  const halves = address.split('::');
+  if (halves.length > 2) return null;
+  const parseHalf = (half) => {
+    if (!half) return [];
+    const words = [];
+    for (const token of half.split(':')) {
+      if (token.includes('.')) {
+        const parts = ipv4Parts(token);
+        if (!parts) return null;
+        words.push((parts[0] << 8) | parts[1], (parts[2] << 8) | parts[3]);
+      } else {
+        if (!/^[0-9a-f]{1,4}$/.test(token)) return null;
+        words.push(Number.parseInt(token, 16));
+      }
+    }
+    return words;
+  };
+  const left = parseHalf(halves[0]);
+  const right = parseHalf(halves[1] || '');
+  if (!left || !right) return null;
+  if (halves.length === 1) return left.length === 8 ? left : null;
+  const omitted = 8 - left.length - right.length;
+  if (omitted < 1) return null;
+  return [...left, ...Array(omitted).fill(0), ...right];
+}
+
+function mappedIpv4Parts(address) {
+  const words = ipv6Words(address);
+  if (!words
+    || words.slice(0, 5).some((word) => word !== 0)
+    || words[5] !== 0xffff) return null;
+  return [words[6] >> 8, words[6] & 0xff, words[7] >> 8, words[7] & 0xff];
+}
+
+function classifyIpv4(parts) {
+  if (parts[0] === 0) return 'unspecified';
+  if (parts[0] === 127) return 'loopback';
+  if (parts[0] === 169 && parts[1] === 254) return 'link-local';
+  if (parts[0] >= 224) return 'multicast';
+  return null;
+}
+
+export function classifyIp(raw) {
+  const address = String(raw || '').replace(/^\[|\]$/g, '').toLowerCase();
+  if (net.isIP(address) === 4) {
+    const parts = ipv4Parts(address);
+    return classifyIpv4(parts);
+  }
+  if (net.isIP(address) === 6) {
+    const mapped = mappedIpv4Parts(address);
+    if (mapped) return classifyIpv4(mapped);
+    if (address === '::') return 'unspecified';
+    if (address === '::1') return 'loopback';
+    if (/^fe[89ab]/.test(address)) return 'link-local';
+    if (address.startsWith('ff')) return 'multicast';
+    return null;
+  }
+  return null;
+}
+
+function effectivePort(url) {
+  if (url.port) return url.port;
+  return url.protocol === 'https:' ? '443' : '80';
+}
+
+export function createBrowserTargetPolicy({
+  topLevelUrl,
+  handmuxOrigin,
+  lookup = dns.lookup,
+} = {}) {
+  let topOrigin = new URL(topLevelUrl).origin;
+  let topAddressClass = null;
+  const appUrl = new URL(handmuxOrigin);
+  const appOrigin = appUrl.origin;
+  const appControlPort = effectivePort(appUrl);
+
+  return {
+    authorizeTopLevel(raw) {
+      const url = new URL(raw);
+      if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('browser URL must use http or https');
+      topOrigin = url.origin;
+      topAddressClass = null;
+    },
+
+    async check(raw) {
+      let url;
+      try { url = new URL(raw); } catch { return { allowed: false, reason: 'unsupported-protocol' }; }
+      if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return { allowed: false, reason: 'unsupported-protocol' };
+      }
+      if (url.origin === appOrigin) return { allowed: false, reason: 'handmux-origin' };
+
+      const hostname = url.hostname.replace(/^\[|\]$/g, '');
+      let addresses;
+      if (net.isIP(hostname)) addresses = [{ address: hostname }];
+      else {
+        try { addresses = await lookup(hostname, { all: true, verbatim: true }); }
+        catch { return { allowed: false, reason: 'dns-failed' }; }
+      }
+      if (!addresses?.length) return { allowed: false, reason: 'dns-failed' };
+
+      const classifications = addresses.map((item) => classifyIp(item.address));
+      if (effectivePort(url) === appControlPort && classifications.some((reason) => reason === 'loopback')) {
+        return { allowed: false, reason: 'handmux-origin' };
+      }
+      if (url.origin === topOrigin && topAddressClass == null) {
+        if (classifications.every((reason) => reason === 'loopback')) topAddressClass = 'loopback';
+        else if (classifications.every((reason) => reason == null)) topAddressClass = 'ordinary';
+      }
+      const loopbackNavigationAllowed = url.origin === topOrigin
+        && topAddressClass === 'loopback'
+        && classifications.every((reason) => reason === 'loopback');
+      for (const reason of classifications) {
+        if (reason === 'loopback' && loopbackNavigationAllowed) continue;
+        if (reason) return { allowed: false, reason: reason === 'loopback' ? 'loopback-not-authorized' : reason };
+      }
+      return {
+        allowed: true,
+        addresses: addresses.map((item) => ({
+          address: item.address,
+          family: item.family || net.isIP(item.address),
+        })),
+      };
+    },
+  };
+}

package/src/browser/worker.js

@@ -0,0 +1,32 @@
+import { createBrowserWorkerServer } from './workerServer.js';
+import { installHammerheadWebSocketUpgradeCompat } from './hammerheadCompat.js';
+
+const internalToken = process.env.HANDMUX_BROWSER_INTERNAL_TOKEN;
+const previewDomain = process.env.HANDMUX_PREVIEW_DOMAIN || null;
+const handmuxOrigin = process.env.HANDMUX_BROWSER_CONTROL_ORIGIN || 'http://127.0.0.1';
+
+let worker = null;
+let shutdownPromise = null;
+
+async function shutdown(code = 0) {
+  if (!shutdownPromise) {
+    shutdownPromise = (async () => {
+      await worker?.close();
+      process.exit(code);
+    })();
+  }
+  return shutdownPromise;
+}
+
+process.once('SIGINT', () => { shutdown().catch(() => process.exit(1)); });
+process.once('SIGTERM', () => { shutdown().catch(() => process.exit(1)); });
+process.once('disconnect', () => { shutdown().catch(() => process.exit(1)); });
+
+try {
+  installHammerheadWebSocketUpgradeCompat();
+  worker = await createBrowserWorkerServer({ internalToken, previewDomain, handmuxOrigin });
+  process.send?.({ type: 'handmux-browser-ready', port: worker.port });
+} catch (error) {
+  console.error(`[handmux] browser worker failed to start: ${error?.message || error}`);
+  process.exit(1);
+}

package/src/browser/workerClient.js

@@ -0,0 +1,253 @@
+import http from 'node:http';
+import net from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { claimedBrowserRequest } from './publicProxy.js';
+import { BROWSER_INTERNAL_HEADER } from './protocol.js';
+import { createBrowserCoordinator } from './coordinator.js';
+
+const WORKER_FILE = fileURLToPath(new URL('./worker.js', import.meta.url));
+
+function forwardedHeaders(headers, internalToken, appToken, api) {
+  const out = { ...headers, [BROWSER_INTERNAL_HEADER]: internalToken };
+  if (api || out.authorization === `Bearer ${appToken}`) delete out.authorization;
+  delete out['proxy-authorization'];
+  return out;
+}
+
+export function createBrowserWorkerClient({
+  appToken,
+  previewDomain = null,
+  handmuxOrigin = 'http://127.0.0.1',
+  forkWorker = fork,
+  request = http.request,
+  connect = net.connect,
+  randomToken = () => randomBytes(32).toString('base64url'),
+  parentEnv = process.env,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  readyTimeoutMs = 10_000,
+  stableAfterMs = 30_000,
+  requestTimeoutMs = 15_000,
+  stopTimeoutMs = 3_000,
+} = {}) {
+  const internalToken = randomToken();
+  let child = null;
+  let port = null;
+  let generation = 0;
+  let stopping = false;
+  let restartDelay = 250;
+  let restartTimer = null;
+  let readyTimer = null;
+  let stableTimer = null;
+  const activeSockets = new Set();
+  const workerEnv = {};
+  for (const name of [
+    'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'TMP', 'TEMP',
+    'LANG', 'LC_ALL', 'TZ', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+    'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy',
+  ]) {
+    if (parentEnv[name] != null) workerEnv[name] = parentEnv[name];
+  }
+
+  const clearReadyTimer = () => {
+    if (readyTimer != null) clearTimer(readyTimer);
+    readyTimer = null;
+  };
+  const clearStableTimer = () => {
+    if (stableTimer != null) clearTimer(stableTimer);
+    stableTimer = null;
+  };
+  const scheduleRestart = () => {
+    if (stopping || restartTimer != null) return;
+    const delay = restartDelay;
+    restartDelay = Math.min(restartDelay * 2, 5_000);
+    restartTimer = setTimer(() => {
+      restartTimer = null;
+      if (!stopping) start();
+    }, delay);
+  };
+  const start = () => {
+    let spawned;
+    try {
+      spawned = forkWorker(WORKER_FILE, [], {
+        env: {
+          ...workerEnv,
+          HANDMUX_BROWSER_INTERNAL_TOKEN: internalToken,
+          HANDMUX_BROWSER_CONTROL_ORIGIN: handmuxOrigin,
+          ...(previewDomain ? { HANDMUX_PREVIEW_DOMAIN: previewDomain } : {}),
+        },
+        stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+      });
+    } catch {
+      child = null;
+      port = null;
+      scheduleRestart();
+      return;
+    }
+    child = spawned;
+    port = null;
+    readyTimer = setTimer(() => {
+      if (child === spawned && port == null) spawned.kill('SIGTERM');
+    }, readyTimeoutMs);
+    spawned.on('message', (message) => {
+      if (child !== spawned || message?.type !== 'handmux-browser-ready' || !Number.isInteger(message.port)) return;
+      port = message.port;
+      generation += 1;
+      clearReadyTimer();
+      clearStableTimer();
+      stableTimer = setTimer(() => {
+        stableTimer = null;
+        if (child === spawned && port != null) restartDelay = 250;
+      }, stableAfterMs);
+    });
+    const finalize = () => {
+      if (child !== spawned) return;
+      child = null;
+      port = null;
+      generation += 1;
+      clearReadyTimer();
+      clearStableTimer();
+      for (const socket of activeSockets) socket.destroy();
+      activeSockets.clear();
+      scheduleRestart();
+    };
+    spawned.once('error', () => {
+      if (child !== spawned) return;
+      try { spawned.kill('SIGTERM'); } catch { /* already gone */ }
+      finalize();
+    });
+    spawned.once('exit', finalize);
+    spawned.once('close', finalize);
+  };
+
+  const unavailable = (res, status) => res.status(status).json({ error: 'browser unavailable' });
+  const proxyHttp = (api) => (req, res, next) => {
+    if (!api && !claimedBrowserRequest(req)) return next();
+    const targetPort = port;
+    if (!targetPort) return unavailable(res, api ? 503 : 502);
+    const upstream = request({
+      hostname: '127.0.0.1',
+      port: targetPort,
+      method: req.method,
+      path: req.originalUrl || req.url,
+      headers: forwardedHeaders(req.headers, internalToken, appToken, api),
+    }, (incoming) => {
+      res.writeHead(incoming.statusCode || 502, incoming.headers);
+      incoming.pipe(res);
+      res.once('close', () => { if (!res.writableEnded) incoming.destroy(); });
+    });
+    if (api) upstream.setTimeout?.(requestTimeoutMs, () => upstream.destroy(new Error('browser worker request timeout')));
+    const abort = () => upstream.destroy();
+    req.once('aborted', abort);
+    res.once('close', () => { if (!res.writableEnded) abort(); });
+    upstream.once('error', () => {
+      if (!res.headersSent) unavailable(res, api ? 503 : 502);
+      else res.destroy();
+    });
+    req.pipe(upstream);
+  };
+
+  const onUpgrade = (req, socket, head) => {
+    if (!claimedBrowserRequest(req)) return false;
+    const targetPort = port;
+    if (!targetPort) { socket.destroy(); return true; }
+    const upstream = connect({ host: '127.0.0.1', port: targetPort });
+    activeSockets.add(socket);
+    activeSockets.add(upstream);
+    const cleanup = () => {
+      activeSockets.delete(socket);
+      activeSockets.delete(upstream);
+    };
+    upstream.once('connect', () => {
+      const headers = forwardedHeaders(req.headers, internalToken, appToken, false);
+      const lines = [`${req.method || 'GET'} ${req.url} HTTP/${req.httpVersion || '1.1'}`];
+      for (const [name, value] of Object.entries(headers)) {
+        if (Array.isArray(value)) for (const item of value) lines.push(`${name}: ${item}`);
+        else if (value != null) lines.push(`${name}: ${value}`);
+      }
+      upstream.write(`${lines.join('\r\n')}\r\n\r\n`);
+      if (head?.length) upstream.write(head);
+      socket.pipe(upstream).pipe(socket);
+    });
+    upstream.once('error', () => socket.destroy());
+    socket.once('error', () => upstream.destroy());
+    upstream.once('close', cleanup);
+    socket.once('close', cleanup);
+    return true;
+  };
+
+  const proxyRequest = ({ req, method, path, body }) => new Promise((resolve) => {
+    const targetPort = port;
+    if (!targetPort) return resolve(null);
+    const payload = body === undefined ? null : Buffer.from(JSON.stringify(body));
+    const headers = forwardedHeaders(req.headers, internalToken, appToken, true);
+    if (payload) {
+      headers['content-type'] = 'application/json';
+      headers['content-length'] = String(payload.length);
+    } else {
+      delete headers['content-length'];
+      delete headers['content-type'];
+    }
+    const upstream = request({ hostname: '127.0.0.1', port: targetPort, method, path, headers }, (incoming) => {
+      const chunks = [];
+      incoming.on('data', (chunk) => chunks.push(chunk));
+      incoming.on('end', () => resolve({
+        status: incoming.statusCode || 502,
+        headers: incoming.headers,
+        body: Buffer.concat(chunks),
+      }));
+    });
+    upstream.setTimeout?.(requestTimeoutMs, () => upstream.destroy(new Error('browser worker request timeout')));
+    upstream.once('error', () => resolve(null));
+    req.once('aborted', () => upstream.destroy());
+    upstream.end(payload || undefined);
+  });
+
+  const apiHandler = createBrowserCoordinator({
+    proxyRequest,
+    getStatus: () => ({ ready: port != null, generation }),
+  });
+
+  if (previewDomain) start();
+  let closePromise = null;
+  return {
+    apiHandler,
+    publicHandler: proxyHttp(false),
+    onUpgrade,
+    close() {
+      if (!closePromise) {
+        stopping = true;
+        apiHandler.close();
+        if (restartTimer != null) clearTimer(restartTimer);
+        restartTimer = null;
+        clearReadyTimer();
+        clearStableTimer();
+        for (const socket of activeSockets) socket.destroy();
+        activeSockets.clear();
+        const current = child;
+        if (!current) closePromise = Promise.resolve();
+        else closePromise = new Promise((resolve) => {
+          let finished = false;
+          let forceTimer = setTimer(() => {
+            forceTimer = null;
+            current.kill('SIGKILL');
+          }, stopTimeoutMs);
+          const finish = () => {
+            if (finished) return;
+            finished = true;
+            if (forceTimer != null) clearTimer(forceTimer);
+            resolve();
+          };
+          current.once('error', finish);
+          current.once('exit', finish);
+          current.once('close', finish);
+          try { current.kill('SIGTERM'); } catch { finish(); }
+        });
+      }
+      return closePromise;
+    },
+  };
+}

package/src/browser/workerServer.js

@@ -0,0 +1,98 @@
+import http from 'node:http';
+import express from 'express';
+import { tokenEquals } from '../auth.js';
+import { createBrowserPreviewManager } from './manager.js';
+import { createBrowserBootstrapStore } from './bootstrap.js';
+import { createBrowserPublicProxy } from './publicProxy.js';
+import { browserRoutes } from './routes.js';
+import { BROWSER_INTERNAL_HEADER } from './protocol.js';
+
+function isLoopback(address) {
+  return address === '127.0.0.1' || address === '::1' || String(address || '').startsWith('::ffff:127.');
+}
+
+function authenticated(req, token) {
+  const provided = req.headers[BROWSER_INTERNAL_HEADER];
+  return isLoopback(req.socket?.remoteAddress)
+    && typeof provided === 'string'
+    && tokenEquals(provided, token);
+}
+
+export async function createBrowserWorkerServer({
+  internalToken,
+  previewDomain = null,
+  handmuxOrigin = 'http://127.0.0.1',
+  browser: suppliedBrowser = null,
+  managerFactory = createBrowserPreviewManager,
+  browserPublicFactory = createBrowserPublicProxy,
+  host = '127.0.0.1',
+  port = 0,
+} = {}) {
+  if (!internalToken) throw new Error('browser worker internal token required');
+  const browserBootstrap = createBrowserBootstrapStore();
+  const browser = suppliedBrowser || await managerFactory({
+    handmuxOrigin,
+    previewDomain,
+    browserBootstrap,
+  });
+  const browserPublic = browserPublicFactory({ browser, browserBootstrap });
+  const app = express();
+
+  app.use((req, res, next) => {
+    if (!authenticated(req, internalToken)) return res.status(401).json({ error: 'browser worker unauthorized' });
+    delete req.headers[BROWSER_INTERNAL_HEADER];
+    next();
+  });
+  app.get('/_browser-worker/health', (_req, res) => res.json({ ok: true }));
+  app.use(
+    '/api/browser-proxy',
+    express.json(),
+    browserRoutes({ browser, previewDomain, browserBootstrap }),
+  );
+  app.use(browserPublic.handler);
+
+  const server = http.createServer(app);
+  const sockets = new Set();
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
+  });
+  server.on('upgrade', (req, socket, head) => {
+    if (!authenticated(req, internalToken)) {
+      socket.end('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+      return;
+    }
+    delete req.headers[BROWSER_INTERNAL_HEADER];
+    if (!browserPublic.onUpgrade(req, socket, head)) socket.destroy();
+  });
+
+  await new Promise((resolve, reject) => {
+    const onError = (error) => { server.off('listening', onListening); reject(error); };
+    const onListening = () => { server.off('error', onError); resolve(); };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, host);
+  });
+
+  let closePromise = null;
+  return {
+    host,
+    port: server.address().port,
+    server,
+    browser,
+    close() {
+      if (!closePromise) {
+        closePromise = (async () => {
+          const stopped = new Promise((resolve) => server.close(resolve));
+          server.closeIdleConnections?.();
+          for (const socket of sockets) socket.destroy();
+          try { await browser.close?.(); } finally {
+            server.closeAllConnections?.();
+            await stopped;
+          }
+        })();
+      }
+      return closePromise;
+    },
+  };
+}

package/src/cli/i18n/en.js

@@ -171,7 +171,6 @@ export default {
   'setup.choose': 'choose 1-6',
   'setup.invalid': 'invalid choice',
   'setup.askPort': 'server port',
-  'setup.askPreviewDomain': 'preview domain (no http://, https://, or *.)',
   'setup.askHostname': 'public hostname (e.g. handmux.example.com)',
   'setup.askTunnelName': 'tunnel name',
   'setup.askSshHost': 'ssh host (user@host[:port])',
@@ -193,7 +192,10 @@ export default {
   'setup.secName': 'Name',
   'setup.secPort': 'Port',
   'setup.secToken': 'Token',
-  'setup.secPreview': 'Dynamic preview',
+  'setup.secBrowser': 'Web preview',
+  'setup.browserOff': 'not configured · Direct mode only',
+  'setup.askBrowserDomain': 'Web preview proxy domain (blank = Direct mode only)',
+  'setup.browserAbout': 'Enter a proxy domain (for example, preview.example.com) and route its wildcard subdomains to Handmux over HTTPS; leave it blank for Direct mode only.',
   'setup.tokenAuto': 'auto · new each start',
   'setup.tokenCustom': 'Set a custom token…',
   'setup.tokenRandom': 'Generate a random one',
@@ -206,7 +208,6 @@ export default {
   'setup.secPush': 'Push',
   'setup.secVoice': 'Voice',
   'setup.default': '(default)',
-  'setup.previewOff': 'Not configured',
   'setup.on': 'on',
   'setup.off': 'off',
   'setup.yes': 'Yes',
@@ -287,11 +288,6 @@ export default {
   '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};  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.',
-  'setup.previewHttps': 'The preview domain itself must support HTTPS. The local development service may use HTTP or HTTPS.',
-  'setup.previewTlsCf': "  TLS: Cloudflare's free cert covers ONE level (*.example.com); deeper (*.preview.example.com) needs Advanced Certificate Manager.",
-  'setup.previewTlsEdge': "  TLS: your edge serves the wildcard cert (e.g. a Let's Encrypt *.preview.your.domain).",
 
   // workspace restore
   'restore.usage': 'Usage: handmux restore [--dry-run] [--checkpoint <id>] [--session <name>] | handmux restore --list',
@@ -381,12 +377,11 @@ start flags (matching env var in parens):
   --cf-tunnel-name N            tunnel name for cloudflare-named (HANDMUX_CF_TUNNEL_NAME, default: handmux)
   --authtoken T                 authtoken for natapp / cpolar (HANDMUX_AUTHTOKEN)
   --cpolar-region R             cpolar edge region, e.g. cn (HANDMUX_CPOLAR_REGION)
-  --preview-domain D            enable dynamic previews, needs wildcard subdomain (HANDMUX_PREVIEW_DOMAIN)
   --foreground, -f              run in the foreground (don't daemonize)
   --no-qr                       don't render the QR code
 
-rarely needed (env or flag): --static-dir / --upload-exts / --preview-ttl
-  (HANDMUX_STATIC_DIR / HANDMUX_UPLOAD_EXTS / HANDMUX_PREVIEW_TTL)
+rarely needed (env or flag): --static-dir / --upload-exts
+  (HANDMUX_STATIC_DIR / HANDMUX_UPLOAD_EXTS)
 
 'handmux service install' accepts these same start flags — they're baked into the autostart entry.
 `,

package/src/cli/i18n/zh.js

@@ -170,7 +170,6 @@ export default {
   'setup.choose': '选择 1-6',
   'setup.invalid': '无效选择',
   'setup.askPort': '服务端口',
-  'setup.askPreviewDomain': '预览域名（不要填 http://、https:// 或 *.）',
   'setup.askHostname': '公网域名(例如 handmux.example.com)',
   'setup.askTunnelName': '隧道名称',
   'setup.askSshHost': 'ssh 主机(user@host[:port])',
@@ -192,7 +191,10 @@ export default {
   'setup.secName': '名称',
   'setup.secPort': '端口',
   'setup.secToken': '令牌',
-  'setup.secPreview': '动态预览',
+  'setup.secBrowser': '网页预览器',
+  'setup.browserOff': '未配置 · 仅手机直连',
+  'setup.askBrowserDomain': '网页预览器代理域名（留空 = 仅手机直连）',
+  'setup.browserAbout': '填写代理域名（如 preview.example.com），并将其通配子域以 HTTPS 路由到 Handmux；留空则仅使用手机直连。',
   'setup.tokenAuto': '自动 · 每次启动新生成',
   'setup.tokenCustom': '自定义令牌…',
   'setup.tokenRandom': '随机生成一个',
@@ -205,7 +207,6 @@ export default {
   'setup.secPush': '推送',
   'setup.secVoice': '语音',
   'setup.default': '(默认)',
-  'setup.previewOff': '未配置',
   'setup.on': '开',
   'setup.off': '关',
   'setup.yes': '是',
@@ -286,11 +287,6 @@ export default {
   'setup.sshHelp1': '服务端(一次性):把反向代理指向被转发的 loopback 端口。',
   '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 网关。',
-  'setup.previewHttps': '预览域名本身必须支持 HTTPS；本机开发服务可使用 HTTP 或 HTTPS。',
-  'setup.previewTlsCf': '  TLS:Cloudflare 的免费证书只覆盖一级(*.example.com);更深一层(*.preview.example.com)需要 Advanced Certificate Manager。',
-  'setup.previewTlsEdge': '  TLS:由你自己的边缘提供通配证书(例如 Let\'s Encrypt 的 *.preview.your.domain)。',
 
   // 工作区恢复
   'restore.usage': '用法: handmux restore [--dry-run] [--checkpoint <id>] [--session <name>] | handmux restore --list',
@@ -380,12 +376,11 @@ start flag(括号内为对应环境变量):
   --cf-tunnel-name N            cloudflare-named 的隧道名(HANDMUX_CF_TUNNEL_NAME,默认:handmux)
   --authtoken T                 natapp / cpolar 的 authtoken(HANDMUX_AUTHTOKEN)
   --cpolar-region R             cpolar 边缘区域,如 cn(HANDMUX_CPOLAR_REGION)
-  --preview-domain D            启用动态预览,需要通配子域名(HANDMUX_PREVIEW_DOMAIN)
   --foreground, -f              前台运行(不后台化)
   --no-qr                       不渲染二维码
 
-很少用到(环境变量或 flag):--static-dir / --upload-exts / --preview-ttl
-  (HANDMUX_STATIC_DIR / HANDMUX_UPLOAD_EXTS / HANDMUX_PREVIEW_TTL)
+很少用到(环境变量或 flag):--static-dir / --upload-exts
+  (HANDMUX_STATIC_DIR / HANDMUX_UPLOAD_EXTS)
 
 'handmux service install' 也接受上面这些 start flag —— 它们会被烘进自启项。
 `,

package/src/cli/options.js

@@ -65,14 +65,13 @@ export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen =
     name: pick('name', env.HANDMUX_APP_NAME) || null,
     host: pick('host', env.HANDMUX_HOST, '0.0.0.0'),
     token: pick('token', env.HANDMUX_TOKEN) || gen(),
-    previewDomain: pick('previewDomain', env.HANDMUX_PREVIEW_DOMAIN) || null,
     foreground: !!pick('foreground', false),
     qr: pick('qr', true) !== false,
     // Unified config — what used to live in .env. The supervisor injects these into the server child's
     // environment (HANDMUX_STATIC_DIR / VAPID_* / XFYUN_* …), which is exactly where the server reads them.
     staticDir: pick('staticDir', env.HANDMUX_STATIC_DIR) || null,
     uploadExts: pick('uploadExts', env.HANDMUX_UPLOAD_EXTS) || null,
-    previewTtl: pick('previewTtl', env.HANDMUX_PREVIEW_TTL) || null,
+    previewDomain: pick('previewDomain', env.HANDMUX_PREVIEW_DOMAIN) || null,
     vapid: fileCfg.vapid || null,   // { public, private, subject } — push notifications
     xfyun: fileCfg.xfyun || null,   // { appId, apiKey, apiSecret } — voice input
     shortcuts: normalizeShortcuts(fileCfg.shortcuts),
@@ -183,8 +182,8 @@ export function explainConfig(flags = {}, fileCfg = {}, cfgPath = null, env = pr
   }
   add('publicUrl', pub, pub.value == null ? '(none — derived from tunnel if any)' : String(pub.value));
 
-  const preview = trace(flags, fileCfg, env, cfgPath, 'previewDomain', 'HANDMUX_PREVIEW_DOMAIN', null);
-  add('previewDomain', preview, preview.value == null ? '(off)' : String(preview.value));
+  const previewDomain = trace(flags, fileCfg, env, cfgPath, 'previewDomain', 'HANDMUX_PREVIEW_DOMAIN', null);
+  add('previewDomain', previewDomain, previewDomain.value == null ? '(none)' : String(previewDomain.value));
 
   if (t === 'ssh') {
     add('sshHost', trace(flags, fileCfg, env, cfgPath, 'sshHost', 'HANDMUX_SSH_HOST', null));