termbeam 1.1.0 → 1.2.0

package/README.md

@@ -65,6 +65,7 @@ termbeam --no-password          # disable password protection
 - **QR code on startup** for instant phone connection
 - **Light/dark theme** with persistent preference
 - **Adjustable font size** via status bar controls, saved across sessions
+- **Port preview** — reverse-proxy a single local web server port and preview it in the browser (HTTP only; no WebSocket/HMR; best with server-rendered apps)
 - **Remote access via [DevTunnel](#remote-access)** — ephemeral or persisted public URLs
 
 ## Remote Access

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {

package/public/terminal.html

@@ -939,7 +939,8 @@
         background: var(--overlay-bg);
         z-index: 200;
         justify-content: center;
-        align-items: center;
+        align-items: flex-start;
+        padding-top: 15vh;
       }
       .modal-overlay.visible {
         display: flex;
@@ -1405,6 +1406,14 @@
           <button class="bar-btn" id="zoom-out" title="Decrease font size">−</button>
           <button class="bar-btn" id="zoom-in" title="Increase font size">+</button>
         </div>
+        <button
+          class="bar-btn"
+          id="preview-btn"
+          title="Preview local port"
+          onclick="openPreviewModal()"
+        >
+          🌐
+        </button>
         <button class="bar-btn" id="share-btn" title="Share link">
           <svg
             width="16"
@@ -1659,6 +1668,61 @@
       </div>
     </div>
 
+    <!-- Preview Port Modal -->
+    <div class="modal-overlay" id="preview-modal">
+      <div class="modal">
+        <h2>🌐 Preview Local Port</h2>
+        <p
+          style="
+            color: var(--text-secondary);
+            font-size: 13px;
+            margin: -8px 0 16px;
+            line-height: 1.4;
+          "
+        >
+          Open a local server running on your machine in a new tab — works through the tunnel.
+        </p>
+        <label for="preview-port-input">Port</label>
+        <div style="position: relative">
+          <input
+            type="number"
+            id="preview-port-input"
+            placeholder="e.g. 3000"
+            min="1"
+            max="65535"
+          />
+          <span
+            id="preview-detect-status"
+            style="
+              position: absolute;
+              right: 12px;
+              top: 50%;
+              transform: translateY(-50%);
+              font-size: 12px;
+              color: var(--text-secondary);
+            "
+          ></span>
+        </div>
+        <div
+          id="preview-hint"
+          style="
+            font-size: 12px;
+            color: var(--success);
+            margin-top: 6px;
+            display: none;
+            align-items: center;
+            gap: 4px;
+          "
+        >
+          <span>✓</span> <span id="preview-hint-text"></span>
+        </div>
+        <div class="modal-actions">
+          <button class="btn-cancel" id="preview-cancel">Cancel</button>
+          <button class="btn-create" id="preview-open">Open Preview ↗</button>
+        </div>
+      </div>
+    </div>
+
     <!-- Folder Browser -->
     <div class="browser-overlay" id="ns-browser-overlay">
       <div class="browser-sheet">
@@ -1929,6 +1993,7 @@
         setupImagePaste();
         setupSelectMode();
         setupNewSessionModal();
+        setupPreviewModal();
         loadShellsForModal();
         startPolling();
 
@@ -3357,6 +3422,64 @@
         input.select();
       }
 
+      function openPreviewModal() {
+        const modal = document.getElementById('preview-modal');
+        const input = document.getElementById('preview-port-input');
+        const status = document.getElementById('preview-detect-status');
+        const hint = document.getElementById('preview-hint');
+        const hintText = document.getElementById('preview-hint-text');
+        input.value = '';
+        hint.style.display = 'none';
+        status.textContent = '';
+        modal.classList.add('visible');
+        input.focus();
+
+        if (activeId) {
+          status.textContent = 'detecting…';
+          fetch('/api/sessions/' + activeId + '/detect-port')
+            .then((r) => (r.ok ? r.json() : null))
+            .then((data) => {
+              status.textContent = '';
+              if (data && data.detected) {
+                input.value = data.port;
+                input.select();
+                hintText.textContent = 'Detected port ' + data.port + ' from terminal output';
+                hint.style.display = 'flex';
+              }
+            })
+            .catch(() => {
+              status.textContent = '';
+            });
+        }
+      }
+
+      function submitPreview() {
+        const input = document.getElementById('preview-port-input');
+        const port = parseInt(input.value, 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+          input.style.borderColor = '#f87171';
+          input.focus();
+          setTimeout(() => (input.style.borderColor = ''), 1500);
+          return;
+        }
+        window.open('/preview/' + port + '/', '_blank');
+        document.getElementById('preview-modal').classList.remove('visible');
+      }
+
+      function setupPreviewModal() {
+        document.getElementById('preview-cancel').addEventListener('click', () => {
+          document.getElementById('preview-modal').classList.remove('visible');
+        });
+        document.getElementById('preview-open').addEventListener('click', submitPreview);
+        document.getElementById('preview-port-input').addEventListener('keydown', (e) => {
+          if (e.key === 'Enter') submitPreview();
+        });
+        document.getElementById('preview-modal').addEventListener('click', (e) => {
+          if (e.target.id === 'preview-modal')
+            document.getElementById('preview-modal').classList.remove('visible');
+        });
+      }
+
       document.getElementById('share-btn').addEventListener('click', async () => {
         const urlPromise = fetch('/api/share-token')
           .then((r) => (r.ok ? r.json() : null))

package/src/preview.js

@@ -0,0 +1,112 @@
+const http = require('http');
+const express = require('express');
+const log = require('./logger');
+
+const PROXY_TIMEOUT = 10_000;
+
+// Rewrite absolute paths in HTML/CSS so they route through the proxy
+function rewriteAbsolutePaths(body, prefix, isHtml) {
+  if (isHtml) {
+    // Rewrite HTML attributes: href="/...", src="/...", action="/...", etc.
+    body = body.replace(
+      /((?:href|src|action|srcset|poster|data|formaction)\s*=\s*["'])\/(?!\/|preview\/)/gi,
+      `$1${prefix}/`,
+    );
+    // Rewrite meta content URLs: content="/..."
+    body = body.replace(/(content\s*=\s*["'])\/(?!\/|preview\/)/gi, `$1${prefix}/`);
+  }
+  // Rewrite CSS url() references: url("/...") or url('/...') or url(/...)
+  body = body.replace(/(url\(\s*["']?)\/(?!\/|preview\/)/gi, `$1${prefix}/`);
+  return body;
+}
+
+function createPreviewProxy() {
+  const router = express.Router();
+
+  function proxyRequest(req, res) {
+    const port = Number(req.params.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      return res
+        .status(400)
+        .json({ error: 'Invalid port: must be an integer between 1 and 65535' });
+    }
+
+    // Strip /preview/:port prefix, keep the rest (or default to /)
+    // Express 5 *path returns an array of segments — join them back
+    const segments = req.params.path;
+    const forwardPath = segments ? `/${[].concat(segments).join('/')}` : '/';
+    const search = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
+
+    const fwdHeaders = { ...req.headers, host: `127.0.0.1:${port}` };
+    // Request uncompressed so we can rewrite HTML content
+    delete fwdHeaders['accept-encoding'];
+
+    const options = {
+      hostname: '127.0.0.1',
+      port,
+      path: forwardPath + search,
+      method: req.method,
+      headers: fwdHeaders,
+    };
+
+    log.debug(`Preview proxy: ${req.method} ${forwardPath}${search} → 127.0.0.1:${port}`);
+
+    const prefix = `/preview/${port}`;
+
+    const proxyReq = http.request(options, (proxyRes) => {
+      const headers = { ...proxyRes.headers };
+
+      // Rewrite Location headers so redirects stay inside the proxy
+      if (headers.location) {
+        const loc = headers.location;
+        if (loc.startsWith('/') && !loc.startsWith(prefix)) {
+          headers.location = prefix + loc;
+        }
+      }
+
+      const contentType = (headers['content-type'] || '').toLowerCase();
+      const isHtml = contentType.includes('text/html');
+      const isCss = contentType.includes('text/css');
+
+      if (isHtml || isCss) {
+        // Buffer response to rewrite absolute paths
+        const chunks = [];
+        proxyRes.on('data', (chunk) => chunks.push(chunk));
+        proxyRes.on('end', () => {
+          let body = Buffer.concat(chunks).toString();
+          body = rewriteAbsolutePaths(body, prefix, isHtml);
+          delete headers['content-length'];
+          headers['transfer-encoding'] = 'chunked';
+          res.writeHead(proxyRes.statusCode, headers);
+          res.end(body);
+        });
+      } else {
+        res.writeHead(proxyRes.statusCode, headers);
+        proxyRes.pipe(res);
+      }
+    });
+
+    proxyReq.setTimeout(PROXY_TIMEOUT, () => {
+      proxyReq.destroy();
+      if (!res.headersSent) {
+        res.status(504).json({ error: 'Gateway timeout: upstream server did not respond in time' });
+      }
+    });
+
+    proxyReq.on('error', (err) => {
+      log.warn(`Preview proxy error (port ${port}): ${err.message}`);
+      if (!res.headersSent) {
+        res.status(502).json({ error: `Bad gateway: ${err.message}` });
+      }
+    });
+
+    req.pipe(proxyReq);
+  }
+
+  router.all('/:port', proxyRequest);
+  router.all('/:port/*path', proxyRequest);
+
+  return router;
+}
+
+module.exports = { createPreviewProxy };

package/src/routes.js

@@ -132,6 +132,26 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     res.json({ shells, default: config.defaultShell, cwd: config.cwd });
   });
 
+  app.get('/api/sessions/:id/detect-port', auth.middleware, (req, res) => {
+    const session = sessions.get(req.params.id);
+    if (!session) return res.status(404).json({ error: 'not found' });
+
+    const buf = session.scrollbackBuf || '';
+    const regex = /https?:\/\/(?:localhost|127\.0\.0\.1):(\d+)/g;
+    let lastPort = null;
+    let match;
+    while ((match = regex.exec(buf)) !== null) {
+      const port = parseInt(match[1], 10);
+      if (port >= 1 && port <= 65535) lastPort = port;
+    }
+
+    if (lastPort !== null) {
+      res.json({ detected: true, port: lastPort });
+    } else {
+      res.json({ detected: false });
+    }
+  });
+
   app.delete('/api/sessions/:id', auth.middleware, (req, res) => {
     if (sessions.delete(req.params.id)) {
       res.json({ ok: true });

package/src/server.js

@@ -12,7 +12,8 @@ const { createAuth } = require('./auth');
 const { SessionManager } = require('./sessions');
 const { setupRoutes, cleanupUploadedFiles } = require('./routes');
 const { setupWebSocket } = require('./websocket');
-const { startTunnel, cleanupTunnel } = require('./tunnel');
+const { startTunnel, cleanupTunnel, findDevtunnel } = require('./tunnel');
+const { createPreviewProxy } = require('./preview');
 
 // --- Helpers ---
 function getLocalIP() {
@@ -43,7 +44,9 @@ function createTermBeamServer(overrides = {}) {
   app.set('trust proxy', 'loopback');
   app.use(express.json());
   app.use(cookieParser());
-  app.use((_req, res, next) => {
+  app.use((req, res, next) => {
+    // Don't apply TermBeam's security headers to proxied preview content
+    if (req.path.startsWith('/preview/')) return next();
     res.setHeader('X-Content-Type-Options', 'nosniff');
     res.setHeader('X-Frame-Options', 'DENY');
     res.setHeader('Referrer-Policy', 'no-referrer');
@@ -59,6 +62,7 @@ function createTermBeamServer(overrides = {}) {
   const wss = new WebSocketServer({ server, path: '/ws', maxPayload: 1 * 1024 * 1024 });
 
   const state = { shareBaseUrl: null };
+  app.use('/preview', auth.middleware, createPreviewProxy());
   setupRoutes(app, { auth, sessions, config, state });
   setupWebSocket(wss, { auth, sessions });
 
@@ -75,6 +79,29 @@ function createTermBeamServer(overrides = {}) {
   }
 
   function start() {
+    // Fail early if tunnel mode is on but devtunnel CLI is not installed
+    if (config.useTunnel && !findDevtunnel()) {
+      log.error('❌ devtunnel CLI is not installed.');
+      log.error('');
+      log.error('  TermBeam uses tunnels by default for remote access.');
+      log.error('  Install the Azure Dev Tunnels CLI, or use --no-tunnel for LAN-only mode.');
+      log.error('');
+      log.error('  Install it:');
+      log.error('    Windows:  winget install Microsoft.devtunnel');
+      log.error(
+        '             or: Invoke-WebRequest -Uri https://aka.ms/TunnelsCliDownload/win-x64 -OutFile devtunnel.exe',
+      );
+      log.error('    macOS:    brew install --cask devtunnel');
+      log.error('    Linux:    curl -sL https://aka.ms/DevTunnelCliInstall | bash');
+      log.error('');
+      log.error('  Then restart your terminal and try again.');
+      log.error(
+        '  Docs: https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started',
+      );
+      log.error('');
+      process.exit(1);
+    }
+
     return new Promise((resolve) => {
       server.listen(config.port, config.host, async () => {
         const ip = getLocalIP();

package/src/tunnel.js

@@ -89,7 +89,8 @@ async function startTunnel(port, options = {}) {
   if (!found) {
     log.error('❌ devtunnel CLI is not installed.');
     log.error('');
-    log.error('  The --tunnel flag requires the Azure Dev Tunnels CLI.');
+    log.error('  TermBeam uses tunnels by default for remote access.');
+    log.error('  Install the Azure Dev Tunnels CLI, or use --no-tunnel for LAN-only mode.');
     log.error('');
     log.error('  Install it:');
     log.error('    Windows:  winget install Microsoft.devtunnel');
@@ -120,19 +121,24 @@ async function startTunnel(port, options = {}) {
     } catch {}
 
     if (!loggedIn) {
-      log.info('devtunnel not logged in, launching login...');
-      log.info('A browser window will open for authentication.');
+      log.info('devtunnel not logged in, launching browser login (30s timeout)...');
       try {
-        execFileSync(devtunnelCmd, ['user', 'login'], { stdio: 'inherit' });
-      } catch (loginErr) {
-        log.error('');
-        log.error('  DevTunnel login failed. To use tunnels, run:');
-        log.error('    devtunnel user login');
-        log.error('');
-        log.error('  Or start without a tunnel:');
-        log.error('    termbeam --no-tunnel');
-        log.error('');
-        return null;
+        execFileSync(devtunnelCmd, ['user', 'login'], { stdio: 'inherit', timeout: 30000 });
+      } catch {
+        log.info('Browser login failed or unavailable, falling back to device code flow...');
+        log.info('A code will be displayed — open the URL on any device to authenticate.');
+        try {
+          execFileSync(devtunnelCmd, ['user', 'login', '-d'], { stdio: 'inherit' });
+        } catch (loginErr) {
+          log.error('');
+          log.error('  DevTunnel login failed. To use tunnels, run:');
+          log.error('    devtunnel user login');
+          log.error('');
+          log.error('  Or start without a tunnel:');
+          log.error('    termbeam --no-tunnel');
+          log.error('');
+          return null;
+        }
       }
     }
 
@@ -257,4 +263,4 @@ function cleanupTunnel() {
   }
 }
 
-module.exports = { startTunnel, cleanupTunnel };
+module.exports = { startTunnel, cleanupTunnel, findDevtunnel };