my-ide-mobile-terminal 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beeweed2727
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# my-ide — mobile-friendly cloud terminal
+
+Fix for phone users who can't use the terminal inside cloud-hosted VS Code:
+a full [xterm.js](https://xtermjs.org) terminal in the browser with a touch
+key bar (CTRL, ALT, SHIFT, ESC, TAB, arrows, Home/End, PgUp/PgDn, backspace,
+delete, Ctrl+C/D/Z/…, F1–F12, programming symbols) next to it.
+
+## Install & run (npm package)
+
+```bash
+npm install -g my-ide-mobile-terminal
+myc
+```
+
+`myc` starts the app and prints only the frontend URL, e.g.
+`http://localhost:3000`. Options: `myc --port 4000`, `myc --help`.
+
+## Run from source
+
+```bash
+npm install
+npm start
+```
+
+Open `http://localhost:3000` on your phone (same Wi-Fi, or forward the port
+with the VS Code **Ports** panel). Tap the terminal, then type with your
+phone keyboard (⌨️ button) or the side keys.
+
+## How it works
+
+- `server.js` — Express static server + WebSocket (`/pty`) bridge to a real
+  shell spawned with `node-pty`. Every installed xterm.js bundle is served
+  locally from `node_modules`, no CDN.
+- `public/` — mobile UI: **left** PC-key bar, **middle** xterm.js terminal,
+  symbol quick-bar on top, thumb bar at the bottom. All xterm.js packages
+  are loaded: core, fit, attach, search, serialize, unicode11, web-links,
+  webgl (+ canvas fallback), image, progress.

package/bin/myc.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/* `myc` — start the mobile-friendly cloud terminal, print only its frontend URL. */
+import net from 'net';
+import path from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+const args = process.argv.slice(2);
+const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+
+if (args.includes('-h') || args.includes('--help')) {
+  console.log('Usage: myc [--port <n>]\n\nStart the mobile terminal server and print its frontend URL.');
+  process.exit(0);
+}
+
+if (args.includes('-V') || args.includes('--version')) {
+  try {
+    console.log(JSON.parse(readFileSync(pkgPath, 'utf8')).version);
+  } catch {
+    console.log('unknown');
+  }
+  process.exit(0);
+}
+
+function flagValue(names) {
+  for (let i = 0; i < args.length; i++) {
+    if (names.includes(args[i]) && args[i + 1] !== undefined) return args[i + 1];
+    if (names.includes('--port')) {
+      const m = /^--port=(\d+)$/.exec(args[i]);
+      if (m) return m[1];
+    }
+  }
+  return undefined;
+}
+
+function isFree(port) {
+  return new Promise((resolve) => {
+    const probe = net.createServer();
+    probe.once('error', () => resolve(false));
+    probe.once('listening', () => probe.close(() => resolve(true)));
+    probe.listen(port, '127.0.0.1');
+  });
+}
+
+const explicitPort = flagValue(['-p', '--port']) ?? process.env.PORT;
+const wanted = parseInt(explicitPort ?? '3000', 10) || 3000;
+
+let port = wanted;
+if (explicitPort !== undefined) {
+  if (!(await isFree(port))) {
+    console.error(`error: port ${port} is already in use`);
+    process.exit(1);
+  }
+} else {
+  while (!(await isFree(port))) {
+    port++;
+    if (port > wanted + 50) {
+      console.error(`error: no free port found near ${wanted}`);
+      process.exit(1);
+    }
+  }
+}
+
+process.env.PORT = String(port);
+process.env.MYC_QUIET = '1';
+await import('../server.js');
+
+// Wait until the server is actually reachable, then expose ONLY the frontend URL.
+const deadline = Date.now() + 15000;
+let up = false;
+while (Date.now() < deadline) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/health`);
+    if (res.ok) {
+      up = true;
+      break;
+    }
+  } catch {
+    /* not up yet */
+  }
+  await new Promise((r) => setTimeout(r, 150));
+}
+
+if (!up) {
+  console.error('error: server did not start in time');
+  process.exit(1);
+}
+
+console.log(`http://localhost:${port}`);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "my-ide-mobile-terminal",
+  "version": "1.0.0",
+  "description": "Mobile-friendly cloud terminal built with full xterm.js + touch key bar (Ctrl, Alt, arrows, etc.) for phones that can't use cloud VS Code's terminal",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "myc": "bin/myc.js"
+  },
+  "files": [
+    "bin/",
+    "public/",
+    "server.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "terminal",
+    "xterm",
+    "xterm.js",
+    "mobile",
+    "cloud",
+    "pty",
+    "cli"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node server.js"
+  },
+  "dependencies": {
+    "@xterm/addon-attach": "^0.11.0",
+    "@xterm/addon-canvas": "^0.7.0",
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/addon-image": "^0.9.0",
+    "@xterm/addon-progress": "^0.2.0",
+    "@xterm/addon-search": "^0.15.0",
+    "@xterm/addon-serialize": "^0.13.0",
+    "@xterm/addon-unicode11": "^0.8.0",
+    "@xterm/addon-web-links": "^0.11.0",
+    "@xterm/addon-webgl": "^0.18.0",
+    "@xterm/headless": "^5.5.0",
+    "@xterm/xterm": "^5.5.0",
+    "express": "^4.19.2",
+    "node-pty": "^1.0.0",
+    "ws": "^8.18.0"
+  }
+}

package/public/index.html

@@ -0,0 +1,169 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+  <meta name="mobile-web-app-capable" content="yes" />
+  <meta name="apple-mobile-web-app-capable" content="yes" />
+  <meta name="theme-color" content="#0b0e14" />
+  <title>Mobile Terminal — cloud VS Code companion</title>
+  <link rel="stylesheet" href="/xterm/xterm.css" />
+  <link rel="stylesheet" href="/style.css" />
+</head>
+<body>
+  <header id="topbar">
+    <span id="status-dot" class="disconnected" title="connection status"></span>
+    <strong id="title">📱 Mobile Terminal</strong>
+    <span id="status-text">connecting…</span>
+    <span class="spacer"></span>
+    <button id="btn-search" title="Search terminal output">🔍</button>
+    <button id="btn-clear" title="Clear screen">🧹</button>
+    <button id="btn-keyboard" title="Open phone keyboard">⌨️</button>
+    <button id="btn-reconnect" title="Reconnect">↻</button>
+  </header>
+
+  <!-- one-tap programming symbols (phone keyboards hide these) -->
+  <nav id="symbolbar" aria-label="Quick symbols">
+    <button data-insert="|">|</button>
+    <button data-insert="/">/</button>
+    <button data-insert="\">&#92;</button>
+    <button data-insert="-">-</button>
+    <button data-insert="_">_</button>
+    <button data-insert=":">:</button>
+    <button data-insert=";">;</button>
+    <button data-insert="~">~</button>
+    <button data-insert="`">`</button>
+    <button data-insert="&quot;">&quot;</button>
+    <button data-insert="'">'</button>
+    <button data-insert="(">(</button>
+    <button data-insert=")">)</button>
+    <button data-insert="{">{</button>
+    <button data-insert="}">}</button>
+    <button data-insert="[">[</button>
+    <button data-insert="]">]</button>
+    <button data-insert="*">*</button>
+    <button data-insert="&">&amp;</button>
+    <button data-insert="?">?</button>
+    <button data-insert="!">!</button>
+    <button data-insert="$">$</button>
+    <button data-insert="^">^</button>
+    <button data-insert="=">=</button>
+    <button data-insert="+">+</button>
+    <button data-insert="%">%</button>
+    <button data-insert="#">#</button>
+    <button data-insert="@">@</button>
+    <button data-insert=" ">␣</button>
+  </nav>
+
+  <div id="searchbar" hidden>
+    <input id="search-input" type="search" placeholder="Search output…" enterkeyhint="search" />
+    <button id="search-prev">▲</button>
+    <button id="search-next">▼</button>
+    <button id="search-close">✕</button>
+  </div>
+
+  <main id="layout">
+    <!-- LEFT: full PC key bar for touch users -->
+    <aside id="keybar" aria-label="PC keys">
+      <div class="key-group">
+        <div class="key-label">MOD</div>
+        <button class="key sticky" id="key-ctrl" title="Ctrl (tap, then tap a letter)">CTRL</button>
+        <button class="key sticky" id="key-alt" title="Alt/Option (tap, then tap a key)">ALT</button>
+        <button class="key sticky" id="key-shift" title="Shift (uppercases next letter)">⇧</button>
+        <button class="key" data-send="&#27;" title="Escape">ESC</button>
+        <button class="key" data-send="&#9;" title="Tab">TAB ⇥</button>
+      </div>
+
+      <div class="key-group">
+        <div class="key-label">ARROWS</div>
+        <div class="arrows">
+          <span></span><button class="key" data-send="&#27;[A" title="Up">▲</button><span></span>
+          <button class="key" data-send="&#27;[D" title="Left">◀</button><button class="key" data-send="&#27;[B" title="Down">▼</button><button class="key" data-send="&#27;[C" title="Right">▶</button>
+        </div>
+      </div>
+
+      <div class="key-group">
+        <div class="key-label">NAV</div>
+        <button class="key" data-send="&#27;[H" title="Home">HOME</button>
+        <button class="key" data-send="&#27;[F" title="End">END</button>
+        <button class="key" data-send="&#27;[5~" title="Page Up">PGUP</button>
+        <button class="key" data-send="&#27;[6~" title="Page Down">PGDN</button>
+      </div>
+
+      <div class="key-group">
+        <div class="key-label">EDIT</div>
+        <button class="key wide" data-send="" title="Backspace">⌫ BKSP</button>
+        <button class="key" data-send="&#27;[3~" title="Delete">DEL</button>
+        <button class="key" data-send="&#27;[2~" title="Insert">INS</button>
+        <button class="key wide" data-send="
+      </div>
+
+      <div class="key-group">
+        <div class="key-label">CTRL+</div>
+        <button class="key" data-send="" title="Ctrl+C — interrupt">C</button>
+        <button class="key" data-send="" title="Ctrl+D — EOF / logout">D</button>
+        <button class="key" data-send="" title="Ctrl+Z — suspend">Z</button>
+        <button class="key" data-send="" title="Ctrl+L — clear">L</button>
+        <button class="key" data-send="" title="Ctrl+R — history search">R</button>
+        <button class="key" data-send="" title="Ctrl+U — kill line">U</button>
+        <button class="key" data-send="" title="Ctrl+K — kill to end">K</button>
+        <button class="key" data-send="
" title="Ctrl+A — start of line">A</button>
+        <button class="key" data-send="" title="Ctrl+E — end of line">E</button>
+      </div>
+
+      <details class="key-group" id="fkeys">
+        <summary>F1–F12</summary>
+        <div class="fkey-grid">
+          <button class="key" data-send="&#27;OP">F1</button>
+          <button class="key" data-send="&#27;OQ">F2</button>
+          <button class="key" data-send="&#27;OR">F3</button>
+          <button class="key" data-send="&#27;OS">F4</button>
+          <button class="key" data-send="&#27;[15~">F5</button>
+          <button class="key" data-send="&#27;[17~">F6</button>
+          <button class="key" data-send="&#27;[18~">F7</button>
+          <button class="key" data-send="&#27;[19~">F8</button>
+          <button class="key" data-send="&#27;[20~">F9</button>
+          <button class="key" data-send="&#27;[21~">F10</button>
+          <button class="key" data-send="&#27;[23~">F11</button>
+          <button class="key" data-send="&#27;[24~">F12</button>
+        </div>
+      </details>
+    </aside>
+
+    <!-- MIDDLE: the terminal -->
+    <section id="terminal-wrap">
+      <div id="terminal" aria-label="Terminal. Tap to focus, then use phone keyboard or side keys."></div>
+      <div id="tap-hint">👆 tap here to type</div>
+      <!-- hidden input summons the OS keyboard on phones; its text is forwarded to the pty -->
+      <input id="kbd-proxy" type="text" autocomplete="off" autocapitalize="none" autocorrect="off" spellcheck="false"
+             aria-label="Phone keyboard input" />
+    </section>
+  </main>
+
+  <footer id="bottombar">
+    <button id="btn-kbd2" title="Toggle phone keyboard">⌨️ Keys</button>
+    <button data-send="&#9;" title="Tab">⇥</button>
+    <button data-send="&#27;" title="Esc">ESC</button>
+    <button data-send="|" title="Pipe">|</button>
+    <button data-send="~" title="Tilde">~</button>
+    <button data-send="/" title="Slash">/</button>
+    <button data-send="" title="Ctrl+C">^C</button>
+    <button data-send="
+    <button data-send="" title="Backspace">⌫</button>
+  </footer>
+
+  <!-- FULL xterm.js stack, every installed package is loaded (nothing left out) -->
+  <script src="/xterm/xterm.js"></script>
+  <script src="/xterm/addon-attach.js"></script>
+  <script src="/xterm/addon-fit.js"></script>
+  <script src="/xterm/addon-search.js"></script>
+  <script src="/xterm/addon-serialize.js"></script>
+  <script src="/xterm/addon-unicode11.js"></script>
+  <script src="/xterm/addon-web-links.js"></script>
+  <script src="/xterm/addon-webgl.js"></script>
+  <script src="/xterm/addon-canvas.js"></script>
+  <script src="/xterm/addon-image.js"></script>
+  <script src="/xterm/addon-progress.js"></script>
+  <script src="/terminal.js"></script>
+</body>
+</html>

package/public/style.css

@@ -0,0 +1,249 @@
+:root {
+  --bg: #0b0e14;
+  --panel: #131722;
+  --panel-2: #1a2030;
+  --border: #2a3348;
+  --text: #e6e9f0;
+  --dim: #8b93a7;
+  --accent: #4cc38a;
+  --accent-dim: #1f3d31;
+  --danger: #ff5f56;
+  --key-h: 44px;
+}
+
+* { box-sizing: border-box; -webkit-tap-highlight-color: transparent; }
+
+html, body {
+  height: 100%;
+  margin: 0;
+  overscroll-behavior: none;
+}
+
+body {
+  background: var(--bg);
+  color: var(--text);
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  display: flex;
+  flex-direction: column;
+  height: 100dvh;
+  overflow: hidden;
+}
+
+/* ---------- top bar ---------- */
+#topbar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  background: var(--panel);
+  border-bottom: 1px solid var(--border);
+  font-size: 14px;
+  min-height: 48px;
+}
+#topbar .spacer { flex: 1; }
+#status-dot {
+  width: 10px; height: 10px; border-radius: 50%;
+  background: var(--danger);
+  flex: none;
+}
+#status-dot.connected { background: var(--accent); box-shadow: 0 0 6px var(--accent); }
+#status-text { color: var(--dim); font-size: 12px; }
+#topbar button {
+  background: var(--panel-2);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  font-size: 16px;
+  min-width: 40px;
+  min-height: 36px;
+}
+
+/* ---------- symbol quick bar ---------- */
+#symbolbar {
+  display: flex;
+  gap: 6px;
+  overflow-x: auto;
+  padding: 6px 8px;
+  background: #0e1220;
+  border-bottom: 1px solid var(--border);
+  scrollbar-width: none;
+}
+#symbolbar::-webkit-scrollbar { display: none; }
+#symbolbar button {
+  flex: none;
+  min-width: 40px;
+  min-height: 36px;
+  font-size: 16px;
+  font-family: ui-monospace, monospace;
+  background: var(--panel-2);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+
+/* ---------- search ---------- */
+#searchbar {
+  display: flex;
+  gap: 6px;
+  padding: 6px 8px;
+  background: var(--panel);
+  border-bottom: 1px solid var(--border);
+}
+#searchbar[hidden] { display: none; }
+#search-input {
+  flex: 1;
+  background: #0e1220;
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 8px;
+  font-size: 16px; /* >=16px prevents iOS auto-zoom */
+}
+#searchbar button {
+  min-width: 44px;
+  background: var(--panel-2);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+
+/* ---------- main layout: LEFT keys + MIDDLE terminal ---------- */
+#layout {
+  flex: 1;
+  display: flex;
+  flex-direction: row;
+  min-height: 0;
+}
+
+#keybar {
+  width: 92px;
+  flex: none;
+  overflow-y: auto;
+  background: var(--panel);
+  border-right: 1px solid var(--border);
+  padding: 8px 6px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  touch-action: pan-y;
+  overscroll-behavior: contain;
+}
+
+.key-group { display: flex; flex-direction: column; gap: 6px; }
+.key-label {
+  font-size: 10px;
+  letter-spacing: 0.08em;
+  color: var(--dim);
+  text-align: center;
+}
+
+.key {
+  min-height: var(--key-h);
+  border-radius: 10px;
+  border: 1px solid var(--border);
+  background: var(--panel-2);
+  color: var(--text);
+  font-size: 13px;
+  font-weight: 600;
+  touch-action: manipulation;
+  user-select: none;
+}
+.key:active { background: #2a3552; }
+.key.wide { min-height: 52px; }
+.key.sticky.active {
+  background: var(--accent-dim);
+  border-color: var(--accent);
+  color: var(--accent);
+}
+
+.arrows {
+  display: grid;
+  grid-template-columns: 1fr 1fr 1fr;
+  gap: 4px;
+}
+.arrows .key { min-height: 40px; font-size: 14px; }
+
+#fkeys summary {
+  text-align: center;
+  font-size: 11px;
+  color: var(--dim);
+  padding: 6px;
+  cursor: pointer;
+}
+.fkey-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 4px;
+}
+.fkey-grid .key { min-height: 40px; font-size: 12px; }
+
+/* ---------- terminal (middle) ---------- */
+#terminal-wrap {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+  background: #000;
+  display: flex;
+}
+#terminal {
+  flex: 1;
+  padding: 6px 0 6px 8px;
+  overflow: hidden;
+}
+#terminal .xterm { height: 100%; }
+
+#tap-hint {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+  background: rgba(20, 26, 40, 0.9);
+  border: 1px solid var(--border);
+  color: var(--dim);
+  font-size: 12px;
+  padding: 6px 10px;
+  border-radius: 20px;
+  pointer-events: none;
+  transition: opacity 0.4s;
+}
+#tap-hint.gone { opacity: 0; }
+
+/* invisible but focusable: summons the phone keyboard */
+#kbd-proxy {
+  position: absolute;
+  bottom: 2px;
+  left: 2px;
+  width: 4px;
+  height: 4px;
+  opacity: 0.01;
+  border: none;
+  padding: 0;
+  font-size: 16px; /* stops iOS zoom */
+}
+
+/* ---------- bottom thumb bar ---------- */
+#bottombar {
+  display: flex;
+  gap: 6px;
+  padding: 8px 8px calc(8px + env(safe-area-inset-bottom));
+  background: var(--panel);
+  border-top: 1px solid var(--border);
+  overflow-x: auto;
+}
+#bottombar button {
+  flex: 1 0 auto;
+  min-width: 52px;
+  min-height: 44px;
+  font-size: 16px;
+  background: var(--panel-2);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  touch-action: manipulation;
+}
+#bottombar button:active { background: #2a3552; }
+
+/* larger phones / landscape: roomier keys */
+@media (min-width: 700px) {
+  #keybar { width: 120px; }
+  .key { font-size: 14px; }
+}

package/public/terminal.js

@@ -0,0 +1,332 @@
+/* Mobile terminal frontend — full xterm.js stack + touch key bar.
+ * Uses EVERY installed xterm package (nothing left out):
+ *   core + fit, attach, search, serialize, unicode11, web-links,
+ *   webgl (gpu), canvas (fallback), image (sixel/iTerm2), progress (OSC 9;4),
+ *   headless is server-side only (imported in node, not the browser).
+ */
+(function () {
+  'use strict';
+
+  const termEl = document.getElementById('terminal');
+  const statusDot = document.getElementById('status-dot');
+  const statusText = document.getElementById('status-text');
+  const kbdProxy = document.getElementById('kbd-proxy');
+  const tapHint = document.getElementById('tap-hint');
+  const searchbar = document.getElementById('searchbar');
+  const searchInput = document.getElementById('search-input');
+
+  // ---------- create terminal ----------
+  const term = new Terminal({
+    cursorBlink: true,
+    cursorStyle: 'bar',
+    fontSize: 14,
+    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+    lineHeight: 1.15,
+    scrollback: 5000,
+    allowProposedApi: true, // needed by image + progress addons
+    theme: {
+      background: '#000000',
+      foreground: '#e6e9f0',
+      cursor: '#4cc38a',
+      selectionBackground: 'rgba(76, 195, 138, 0.35)',
+    },
+  });
+
+  // ---------- load ALL addons ----------
+  const fitAddon = new FitAddon.FitAddon();
+  const searchAddon = new SearchAddon.SearchAddon();
+  const serializeAddon = new SerializeAddon.SerializeAddon();
+  const unicode11 = new Unicode11Addon.Unicode11Addon();
+  const webLinks = new WebLinksAddon.WebLinksAddon();
+  const attachAddon = null; // we speak JSON {type,input/resize} so we wire the socket manually
+  void attachAddon;
+
+  term.loadAddon(fitAddon);
+  term.loadAddon(searchAddon);
+  term.loadAddon(serializeAddon);
+  term.loadAddon(webLinks);
+  term.loadAddon(unicode11);
+  term.unicode.activeVersion = '11';
+
+  // image (sixel / iTerm2 inline images)
+  try {
+    const imageAddon = new ImageAddon.ImageAddon();
+    term.loadAddon(imageAddon);
+  } catch (e) { console.warn('image addon unavailable', e); }
+
+  // progress (OSC 9;4 progress bars, e.g. apt/pacman style tasks)
+  try {
+    const progressAddon = new ProgressAddon.ProgressAddon();
+    term.loadAddon(progressAddon);
+  } catch (e) { console.warn('progress addon unavailable', e); }
+
+  // gpu renderer with canvas fallback
+  let gpuAddon = null;
+  try {
+    gpuAddon = new WebglAddon.WebglAddon();
+    term.loadAddon(gpuAddon);
+  } catch (e) {
+    console.warn('webgl unavailable, trying canvas renderer', e);
+    try {
+      term.loadAddon(new CanvasAddon.CanvasAddon());
+    } catch (e2) { console.warn('canvas addon unavailable', e2); }
+  }
+  term.onRender && term.onRender(() => {});
+  if (gpuAddon && gpuAddon.onContextLoss) {
+    gpuAddon.onContextLoss(() => {
+      try { gpuAddon.dispose(); } catch {}
+      try { term.loadAddon(new CanvasAddon.CanvasAddon()); } catch {}
+    });
+  }
+
+  term.open(termEl);
+  safeFit();
+
+  function safeFit() {
+    try { fitAddon.fit(); } catch {}
+  }
+
+  // expose for debugging / tests
+  window.__term = term;
+  window.__serialize = () => serializeAddon.serialize();
+
+  // ---------- websocket <-> pty ----------
+  let ws = null;
+  let wantClose = false;
+  let retryMs = 1000;
+
+  function setStatus(connected, text) {
+    statusDot.classList.toggle('connected', connected);
+    statusDot.classList.toggle('disconnected', !connected);
+    statusText.textContent = text;
+  }
+
+  function connect() {
+    wantClose = false;
+    setStatus(false, 'connecting…');
+    const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+    ws = new WebSocket(proto + '://' + location.host + '/pty');
+
+    ws.onopen = () => {
+      retryMs = 1000;
+      setStatus(true, 'connected');
+      term.writeln('\x1b[32m● connected — tap ⌨️ if your phone keyboard is hidden.\x1b[0m');
+      pushResize();
+      term.focus();
+    };
+
+    ws.onmessage = (ev) => {
+      if (typeof ev.data === 'string' && ev.data.indexOf('{"type":"pong"}') !== -1) return;
+      term.write(ev.data);
+    };
+
+    ws.onclose = () => {
+      setStatus(false, 'disconnected');
+      if (!wantClose) {
+        term.writeln('\x1b[31m● disconnected — retrying…\x1b[0m');
+        setTimeout(connect, (retryMs = Math.min(retryMs * 1.5, 8000)));
+      }
+    };
+
+    ws.onerror = () => { try { ws.close(); } catch {} };
+  }
+
+  function sendInput(data) {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'input', data }));
+    }
+  }
+
+  function pushResize() {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'resize', cols: term.cols, rows: term.rows }));
+    }
+  }
+
+  term.onData((data) => sendInput(data));
+  term.onResize((size) => {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'resize', cols: size.cols, rows: size.rows }));
+    }
+  });
+
+  // keep-alive through proxies
+  setInterval(() => {
+    if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'ping' }));
+  }, 25000);
+
+  // ---------- sticky modifiers (CTRL / ALT / SHIFT) ----------
+  const sticky = { ctrl: false, alt: false, shift: false };
+  const keyCtrl = document.getElementById('key-ctrl');
+  const keyAlt = document.getElementById('key-alt');
+  const keyShift = document.getElementById('key-shift');
+
+  function paintSticky() {
+    keyCtrl.classList.toggle('active', sticky.ctrl);
+    keyAlt.classList.toggle('active', sticky.alt);
+    keyShift.classList.toggle('active', sticky.shift);
+  }
+
+  function bindSticky(btn, name) {
+    btn.addEventListener('click', () => {
+      sticky[name] = !sticky[name];
+      // ctrl and alt are exclusive-ish: enabling one releases the other
+      if (sticky[name] && name !== 'shift') {
+        if (name === 'ctrl') sticky.alt = false;
+        if (name === 'alt') sticky.ctrl = false;
+      }
+      paintSticky();
+      term.focus();
+    });
+  }
+  bindSticky(keyCtrl, 'ctrl');
+  bindSticky(keyAlt, 'alt');
+  bindSticky(keyShift, 'shift');
+
+  /** Apply sticky modifiers to a key about to be sent. Single-shot: consumed after one use. */
+  function applySticky(data) {
+    let out = data;
+    const wasCtrl = sticky.ctrl;
+    const wasAlt = sticky.alt;
+    const wasShift = sticky.shift;
+
+    if (wasShift && out.length === 1 && /[a-z]/.test(out)) out = out.toUpperCase();
+    // shift + arrows -> modified escape sequences terminals understand
+    if (wasShift && out.charCodeAt(0) === 0x1b && out[1] === '[' && /[ABCD]$/.test(out)) {
+      out = out.slice(0, -1) + ';2' + out.slice(-1);
+    }
+
+    if (wasCtrl && out.length === 1) {
+      const lower = out.toLowerCase();
+      if (lower >= 'a' && lower <= 'z') {
+        out = String.fromCharCode(lower.charCodeAt(0) - 96); // ctrl+a..ctrl+z
+      } else if (out === ' ') {
+        out = '\x00';
+      }
+    }
+    if (wasAlt) {
+      // Alt = ESC prefix (unless it already starts with ESC)
+      out = out.charCodeAt(0) === 0x1b ? out : '\x1b' + out;
+    }
+
+    sticky.ctrl = sticky.alt = sticky.shift = false;
+    paintSticky();
+    return out;
+  }
+
+  // every button with data-send / data-insert flows through here
+  document.addEventListener('click', (ev) => {
+    const sendBtn = ev.target.closest('[data-send]');
+    if (sendBtn) {
+      sendInput(applySticky(sendBtn.getAttribute('data-send')));
+      term.focus();
+      hideHint();
+      return;
+    }
+    const insBtn = ev.target.closest('[data-insert]');
+    if (insBtn) {
+      sendInput(applySticky(insBtn.getAttribute('data-insert')));
+      term.focus();
+      hideHint();
+    }
+  });
+
+  // ---------- phone keyboard proxy ----------
+  // Mobile browsers only open the virtual keyboard for a real <input>.
+  // We keep a nearly-invisible input focused and forward everything typed.
+  function openKeyboard() {
+    kbdProxy.focus({ preventScroll: true });
+    // iOS sometimes needs the caret trick:
+    try { kbdProxy.setSelectionRange(kbdProxy.value.length, kbdProxy.value.length); } catch {}
+  }
+
+  kbdProxy.addEventListener('input', () => {
+    const v = kbdProxy.value;
+    if (v) {
+      // on-screen keyboards may batch words + autocorrect; send raw then reset
+      sendInput(applySticky(v));
+      kbdProxy.value = '';
+    }
+  });
+
+  kbdProxy.addEventListener('keydown', (e) => {
+    // physical / bluetooth keyboards attached to the phone come through here too
+    if (e.key === 'Enter') { sendInput(applySticky('\r')); kbdProxy.value = ''; e.preventDefault(); }
+    else if (e.key === 'Backspace' && kbdProxy.value === '') { sendInput(applySticky('\x7f')); e.preventDefault(); }
+    else if (e.key === 'Tab') { sendInput(applySticky('\t')); e.preventDefault(); }
+    else if (e.key === 'Escape') { sendInput(applySticky('\x1b')); e.preventDefault(); }
+    else if (e.key && e.key.length === 1 && (e.ctrlKey || e.metaKey)) {
+      const lower = e.key.toLowerCase();
+      if (lower >= 'a' && lower <= 'z') {
+        sendInput(String.fromCharCode(lower.charCodeAt(0) - 96));
+        e.preventDefault();
+      }
+    }
+  });
+
+  termEl.addEventListener('click', () => { hideHint(); openKeyboard(); });
+  document.getElementById('btn-keyboard').addEventListener('click', openKeyboard);
+  document.getElementById('btn-kbd2').addEventListener('click', () => {
+    if (document.activeElement === kbdProxy) kbdProxy.blur();
+    else openKeyboard();
+  });
+
+  function hideHint() { tapHint.classList.add('gone'); }
+  setTimeout(hideHint, 9000);
+
+  // ---------- top bar actions ----------
+  document.getElementById('btn-clear').addEventListener('click', () => {
+    term.clear();
+    term.focus();
+  });
+  document.getElementById('btn-reconnect').addEventListener('click', () => {
+    try { wantClose = true; ws && ws.close(); } catch {}
+    term.writeln('\x1b[33m● reconnecting…\x1b[0m');
+    setTimeout(connect, 300);
+  });
+
+  // ---------- search (addon-search) ----------
+  document.getElementById('btn-search').addEventListener('click', () => {
+    searchbar.hidden = !searchbar.hidden;
+    if (!searchbar.hidden) searchInput.focus();
+    else searchAddon.clearDecorations();
+  });
+  document.getElementById('search-close').addEventListener('click', () => {
+    searchbar.hidden = true;
+    searchAddon.clearDecorations();
+    term.focus();
+  });
+  function runSearch() {
+    const q = searchInput.value;
+    if (!q) { searchAddon.clearDecorations(); return; }
+    searchAddon.findNext(q, { incremental: true });
+  }
+  searchInput.addEventListener('input', runSearch);
+  searchInput.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter') {
+      if (e.shiftKey) searchAddon.findPrevious(searchInput.value);
+      else searchAddon.findNext(searchInput.value);
+    }
+    if (e.key === 'Escape') document.getElementById('search-close').click();
+  });
+  document.getElementById('search-next').addEventListener('click', () => searchAddon.findNext(searchInput.value));
+  document.getElementById('search-prev').addEventListener('click', () => searchAddon.findPrevious(searchInput.value));
+
+  // ---------- resize ----------
+  function refit() {
+    safeFit();
+    pushResize();
+  }
+  new ResizeObserver(() => refit()).observe(termEl);
+  window.addEventListener('orientationchange', () => setTimeout(refit, 250));
+  window.addEventListener('resize', () => refit());
+  // mobile URL bar show/hide changes dvh; ResizeObserver covers it, this is belt & braces
+  if (window.visualViewport) {
+    window.visualViewport.addEventListener('resize', () => refit());
+  }
+  // fit once fonts/layout settle
+  setTimeout(refit, 100);
+  setTimeout(refit, 600);
+
+  connect();
+})();

package/server.js

@@ -0,0 +1,130 @@
+import express from 'express';
+import { createServer } from 'http';
+import { WebSocketServer } from 'ws';
+import * as pty from 'node-pty';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import os from 'os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const app = express();
+const server = createServer(app);
+const wss = new WebSocketServer({ server, path: '/pty' });
+
+const PORT = process.env.PORT || 3000;
+
+// ---- static frontend ----
+app.use(express.static(path.join(__dirname, 'public')));
+
+// Serve every installed xterm.js bundle locally (nothing loaded from CDN,
+// so "nothing gets remains" — all packages are installed AND used).
+//  core:      /xterm/xterm.js  +  /xterm/xterm.css
+//  addons:    /xterm/addon-*.js
+app.use(
+  '/xterm/xterm.css',
+  express.static(path.join(__dirname, 'node_modules/@xterm/xterm/css/xterm.css'))
+);
+for (const addon of [
+  'addon-attach',
+  'addon-canvas',
+  'addon-fit',
+  'addon-image',
+  'addon-progress',
+  'addon-search',
+  'addon-serialize',
+  'addon-unicode11',
+  'addon-web-links',
+  'addon-webgl',
+]) {
+  app.use(
+    `/xterm/${addon}.js`,
+    express.static(path.join(__dirname, `node_modules/@xterm/${addon}/lib/${addon}.js`))
+  );
+}
+app.use(
+  '/xterm/xterm.js',
+  express.static(path.join(__dirname, 'node_modules/@xterm/xterm/lib/xterm.js'))
+);
+
+app.get('/health', (_req, res) => res.json({ ok: true }));
+
+// ---- pty handling ----
+function spawnShell(cols = 80, rows = 30) {
+  const shell = process.env.SHELL || (os.platform() === 'win32' ? 'powershell.exe' : 'bash');
+  return pty.spawn(shell, [], {
+    name: 'xterm-256color',
+    cols,
+    rows,
+    cwd: process.env.HOME || process.cwd(),
+    env: {
+      ...process.env,
+      TERM: 'xterm-256color',
+      COLORTERM: 'truecolor',
+    },
+  });
+}
+
+wss.on('connection', (ws) => {
+  const ptyProc = spawnShell();
+  console.log(`[+] pty started pid=${ptyProc.pid}`);
+
+  // pty -> browser
+  const onData = (data) => {
+    if (ws.readyState === ws.OPEN) ws.send(data);
+  };
+  ptyProc.onData(onData);
+  ptyProc.onExit(({ exitCode, signal }) => {
+    if (ws.readyState === ws.OPEN) {
+      ws.send(`\r\n\x1b[31m[process exited code=${exitCode} signal=${signal}]\x1b[0m\r\n`);
+      ws.close();
+    }
+  });
+
+  // browser -> pty. Accepts raw strings (legacy) or JSON:
+  //   {"type":"input","data":"ls\r"} | {"type":"resize","cols":80,"rows":24}
+  ws.on('message', (msg) => {
+    const text = msg.toString();
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === 'object' && parsed.type) {
+        if (parsed.type === 'input' && typeof parsed.data === 'string') {
+          ptyProc.write(parsed.data);
+        } else if (parsed.type === 'resize') {
+          const cols = Math.max(20, Math.min(300, parseInt(parsed.cols, 10) || 80));
+          const rows = Math.max(5, Math.min(100, parseInt(parsed.rows, 10) || 30));
+          ptyProc.resize(cols, rows);
+        } else if (parsed.type === 'ping' && ws.readyState === ws.OPEN) {
+          ws.send(JSON.stringify({ type: 'pong' }));
+        }
+        return;
+      }
+    } catch {
+      // not JSON -> treat as raw input
+    }
+    ptyProc.write(text);
+  });
+
+  ws.on('close', () => {
+    console.log(`[-] ws closed, killing pty pid=${ptyProc.pid}`);
+    try {
+      ptyProc.kill();
+    } catch {
+      /* already dead */
+    }
+  });
+  ws.on('error', () => {
+    try {
+      ptyProc.kill();
+    } catch {
+      /* noop */
+    }
+  });
+});
+
+server.listen(PORT, () => {
+  if (process.env.MYC_QUIET) return; // `myc` CLI prints only the URL itself
+  console.log(`Mobile terminal listening on http://localhost:${PORT}`);
+  console.log('Open it on your phone (same network / forwarded port) and tap the terminal.');
+});