termdock 1.4.356 → 1.4.357

package/dist/server/utils/localHttpsSetup.js

@@ -0,0 +1,257 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, createPrivateKey, X509Certificate, randomUUID } from 'node:crypto';
+import { execFile, spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { isIP } from 'node:net';
+const require = createRequire(import.meta.url);
+const { findExecutable } = require('../../../scripts/install-utils.cjs');
+export const MKCERT_VERSION = '1.4.4';
+// Pinned official release assets: https://github.com/FiloSottile/mkcert/releases/tag/v1.4.4
+export const MKCERT_SHA256 = {
+    'linux-amd64': '6d31c65b03972c6dc4a14ab429f2928300518b26503f58723e532d1b0a3bbb52',
+    'linux-arm64': 'b98f2cc69fd9147fe4d405d859c57504571adec0d3611c3eefd04107c7ac00d0',
+    'linux-arm': '2f22ff62dfc13357e147e027117724e7ce1ff810e30d2b061b05b668ecb4f1d7',
+    'darwin-amd64': 'a32dfab51f1845d51e810db8e47dcf0e6b51ae3422426514bf5a2b8302e97d4e',
+    'darwin-arm64': 'c8af0df44bce04359794dad8ea28d750437411d632748049d08644ffb66a60c6',
+};
+const runTool = async (file, args, options) => {
+    try {
+        return await new Promise((resolve, reject) => {
+            const child = execFile(file, args, { timeout: 120_000, maxBuffer: 4 * 1024 * 1024, ...options }, (error, stdout, stderr) => error ? reject(error) : resolve({ stdout, stderr }));
+            // A nested sudo must receive EOF, never wait on an unused stdin pipe.
+            child.stdin?.end();
+        });
+    }
+    catch (error) {
+        const failure = error;
+        throw new Error(`${path.basename(file)} ${args.join(' ')} failed (${failure.code ?? failure.signal ?? 'spawn error'}): ${failure.stderr?.trim() || failure.message}`, { cause: error });
+    }
+};
+export async function downloadVerifiedExecutable(url, sha256, target, fetcher = fetch) {
+    const response = await fetcher(url, { signal: AbortSignal.timeout(120_000) });
+    if (!response.ok)
+        throw new Error(`mkcert download returned HTTP ${response.status}. Install mkcert manually and retry td --setup-local-https.`);
+    if (Number(response.headers.get('content-length')) > 20 * 1024 * 1024)
+        throw new Error('mkcert download is unexpectedly large');
+    const chunks = [];
+    let size = 0;
+    if (!response.body)
+        throw new Error('Empty mkcert download');
+    const reader = response.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            if (size > 20 * 1024 * 1024) {
+                await reader.cancel();
+                throw new Error('mkcert download is unexpectedly large');
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = Buffer.concat(chunks);
+    if (createHash('sha256').update(bytes).digest('hex') !== sha256)
+        throw new Error('mkcert download SHA-256 mismatch; the executable was not installed');
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, bytes, { mode: 0o700, flag: 'wx' });
+        fs.renameSync(temporary, target);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+export async function ensureMkcert(options = {}) {
+    const find = options.find ?? findExecutable, run = options.run ?? runTool;
+    const home = options.home ?? os.homedir();
+    const target = path.join(home, '.termdock/bin/mkcert');
+    // Check our own location explicitly, including when HOME/PATH is restricted.
+    const existing = find('mkcert') || (fs.existsSync(target) ? target : null);
+    if (existing) {
+        try {
+            await run(existing, ['--version'], { timeout: 5000 });
+            return existing;
+        }
+        catch (error) {
+            throw new Error(`The installed mkcert is unusable: ${String(error)}. Repair or remove ${existing} and retry.`);
+        }
+    }
+    const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
+    const asset = `${platform}-${arch === 'x64' ? 'amd64' : arch}`;
+    const checksum = MKCERT_SHA256[asset];
+    if (!checksum)
+        throw new Error(`Automatic mkcert installation is unavailable for ${platform}/${arch}. Install mkcert manually (Windows: use WSL).`);
+    options.log?.(`Downloading verified mkcert ${MKCERT_VERSION} to ${target} (no administrator permission required)...`);
+    const url = `https://github.com/FiloSottile/mkcert/releases/download/v${MKCERT_VERSION}/mkcert-v${MKCERT_VERSION}-${asset}`;
+    try {
+        await (options.download ?? downloadVerifiedExecutable)(url, checksum, target);
+        await run(target, ['--version'], { timeout: 5000 });
+    }
+    catch (error) {
+        throw new Error(`Could not prepare mkcert: ${String(error)}. Install mkcert manually and retry td --setup-local-https.`, { cause: error });
+    }
+    return target;
+}
+export function localHttpsPaths(directory) {
+    return { cert: path.join(directory, 'termdock-local.pem'), key: path.join(directory, 'termdock-local-key.pem'), ca: path.join(directory, 'rootCA.pem') };
+}
+export function inspectLocalCertificate(files, names, now = Date.now()) {
+    const cert = new X509Certificate(fs.readFileSync(files.cert)), ca = new X509Certificate(fs.readFileSync(files.ca));
+    if (!ca.ca || cert.ca || !cert.checkIssued(ca) || !cert.verify(ca.publicKey)
+        || !cert.checkPrivateKey(createPrivateKey(fs.readFileSync(files.key))))
+        throw new Error('Certificate, private key and local CA do not match');
+    if (cert.keyUsage && !cert.keyUsage.includes('1.3.6.1.5.5.7.3.1'))
+        throw new Error('Local certificate does not allow TLS server authentication');
+    for (const item of [cert, ca]) {
+        if (Date.parse(item.validFrom) > now || Date.parse(item.validTo) <= now)
+            throw new Error('Local HTTPS certificate or CA is not currently valid');
+    }
+    const missing = names.filter(name => isIP(name) ? cert.checkIP(name) === undefined : cert.checkHost(name, { subject: 'never', wildcards: false }) === undefined);
+    if (missing.length)
+        throw new Error(`Certificate is missing names: ${missing.join(', ')}`);
+    return { cert, ca };
+}
+export function localCertificateNeedsRefresh(directory, names, now = Date.now()) {
+    try {
+        const { cert, ca } = inspectLocalCertificate(localHttpsPaths(directory), names, now);
+        return Math.min(Date.parse(cert.validTo), Date.parse(ca.validTo)) < now + 30 * 86400_000;
+    }
+    catch {
+        return true;
+    }
+}
+function runInteractive(file, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, { stdio: 'inherit', timeout: 120_000 });
+        child.once('error', reject);
+        child.once('exit', (code, signal) => code === 0 ? resolve() : reject(new Error(`mkcert -install failed (${signal ?? code})`)));
+    });
+}
+export async function setupLocalHttps(options) {
+    const run = options.run ?? runTool, find = options.find ?? findExecutable;
+    const mkcert = options.mkcert ?? await ensureMkcert({ log: options.log });
+    const names = [...new Set(options.names)];
+    if (!names.length)
+        throw new Error('At least one HTTPS certificate name is required');
+    fs.mkdirSync(options.directory, { recursive: true, mode: 0o700 });
+    const lock = path.join(options.directory, '.setup.lock');
+    try {
+        fs.writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const owner = Number(fs.readFileSync(lock, 'utf8'));
+        if (!Number.isSafeInteger(owner) || owner <= 0)
+            throw new Error('Invalid HTTPS setup lock; inspect ' + lock);
+        try {
+            process.kill(owner, 0);
+        }
+        catch (failure) {
+            if (failure.code === 'ESRCH') {
+                fs.rmSync(lock);
+                return setupLocalHttps({ ...options, mkcert });
+            }
+        }
+        throw new Error('Local HTTPS setup is already running; retry after it completes');
+    }
+    let stage;
+    try {
+        stage = fs.mkdtempSync(path.join(options.directory, '.setup-'));
+        const candidate = localHttpsPaths(stage), files = localHttpsPaths(options.directory);
+        await run(mkcert, ['-cert-file', candidate.cert, '-key-file', candidate.key, ...names], { cwd: stage });
+        const caroot = (await run(mkcert, ['-CAROOT'], { timeout: 5000 })).stdout.trim();
+        if (!path.isAbsolute(caroot))
+            throw new Error('mkcert returned an invalid CA directory');
+        fs.copyFileSync(path.join(caroot, 'rootCA.pem'), candidate.ca);
+        const verified = inspectLocalCertificate(candidate, names);
+        let oldFingerprint;
+        const hadCa = fs.existsSync(files.ca);
+        if (hadCa) {
+            try {
+                oldFingerprint = new X509Certificate(fs.readFileSync(files.ca)).fingerprint256;
+            }
+            catch { /* An explicit setup may repair a damaged CA; automatic renewal may not replace it. */ }
+        }
+        const caChanged = hadCa && oldFingerprint !== verified.ca.fingerprint256;
+        if (caChanged && options.allowCaChange === false)
+            throw new Error('Automatic renewal would replace the trusted CA. Restore its mkcert CAROOT/private key, or explicitly run td --setup-local-https to replace it and trust it again.');
+        const keys = ['cert', 'key', 'ca'];
+        const backups = new Map(keys.map(key => [key, fs.existsSync(files[key]) ? fs.readFileSync(files[key]) : undefined]));
+        for (const key of keys)
+            fs.chmodSync(candidate[key], 0o600);
+        try {
+            // No await between renames: filesystem watchers observe the complete set.
+            for (const key of keys)
+                fs.renameSync(candidate[key], files[key]);
+        }
+        catch (error) {
+            for (const key of keys) {
+                const backup = backups.get(key);
+                if (backup)
+                    fs.writeFileSync(files[key], backup, { mode: 0o600 });
+                else
+                    fs.rmSync(files[key], { force: true });
+            }
+            throw error;
+        }
+        const warnings = [];
+        if (caChanged)
+            warnings.push('The local CA changed. Install and trust the new rootCA.pem on every device again.');
+        let trust = 'skipped';
+        if (options.installCa !== false) {
+            const platform = options.platform ?? process.platform;
+            const interactive = options.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
+            let canInstallSystem = interactive || (options.uid ?? process.getuid?.()) === 0;
+            if (!canInstallSystem) {
+                const sudo = find('sudo');
+                if (sudo) {
+                    try {
+                        await run(sudo, ['-n', 'true'], { timeout: 5000 });
+                        canInstallSystem = true;
+                    }
+                    catch { /* No password prompts in a pipe/daemon. */ }
+                }
+            }
+            if (platform === 'linux' && !find('certutil'))
+                warnings.push('Browser CA trust needs certutil: Debian/Ubuntu: apt install libnss3-tools; Fedora/RHEL: dnf install nss-tools; Arch: pacman -S nss; openSUSE: zypper install mozilla-nss-tools.');
+            if (platform === 'linux' && !['update-ca-certificates', 'update-ca-trust', 'trust'].some(tool => find(tool)))
+                warnings.push('No Linux system CA trust updater was found. Install the ca-certificates package or configure this server\'s trust store manually.');
+            if (canInstallSystem) {
+                try {
+                    if (interactive && !options.run)
+                        await runInteractive(mkcert, ['-install']);
+                    else {
+                        const result = await run(mkcert, ['-install']);
+                        if (result.stderr.trim())
+                            warnings.push(result.stderr.trim());
+                    }
+                    trust = 'requested';
+                }
+                catch (error) {
+                    trust = 'failed';
+                    warnings.push(`Certificate generation succeeded, but local CA trust installation failed: ${String(error)}`);
+                }
+            }
+            else
+                warnings.push('Local CA trust was skipped because this non-interactive process cannot elevate privileges.');
+            const quotedMkcert = "'" + mkcert.replaceAll("'", "'\\''") + "'";
+            if (trust !== 'requested')
+                warnings.push(`To trust this CA on the server, run ${quotedMkcert} -install from an interactive terminal under the same user/CAROOT.`);
+        }
+        return { files, warnings, trust, caChanged };
+    }
+    finally {
+        if (stage)
+            fs.rmSync(stage, { recursive: true, force: true });
+        fs.rmSync(lock, { force: true });
+    }
+}

package/dist/server/utils/oscBuffer.js

@@ -0,0 +1,9 @@
+/** Retain the entire incomplete OSC, including a split ESC/ST terminator.
+ * Hook prompt payloads can be much longer than a normal terminal title. */
+export function incompleteOscSuffix(buffer, consumed, cap = 512 * 1024) {
+    const tail = buffer.slice(consumed);
+    const start = tail.lastIndexOf('\x1b]');
+    if (start >= 0 && tail.length - start <= cap)
+        return tail.slice(start);
+    return tail.endsWith('\x1b') ? '\x1b' : '';
+}

package/dist/server/utils/sessionDisplayName.js

@@ -18,7 +18,7 @@ export function getCwdLeafName(cwd) {
     return segments[segments.length - 1] || cwd;
 }
 export function getSessionDisplayLines(session, activeProgram, cwd, shellNames = DEFAULT_SESSION_DISPLAY_SHELL_NAMES, shellTitle = null, promptState = null) {
-    if (session.customName)
+    if (session.customName && session.name.trim())
         return { primary: session.name, secondary: getCwdLeafName(cwd) };
     // Shell integration (OSC 2) provides real-time title: command name when running,
     // cwd when idle. This is faster and more accurate than server-side process polling.
@@ -37,17 +37,19 @@ export function getSessionDisplayLines(session, activeProgram, cwd, shellNames =
     const dir = getCwdLeafName(cwd);
     if (dir)
         return { primary: dir, secondary: null };
-    return { primary: session.name, secondary: null };
+    const stored = session.name.trim();
+    const internal = /^(?:tmux:|remote:|wt-)/i.test(stored) || stored === session.sessionId || stored === session.id;
+    return { primary: stored && !internal ? stored : session.agent?.displayName || '终端会话', secondary: null };
 }
 export function getSessionDisplayName(session, activeProgram, cwd, shellNames = DEFAULT_SESSION_DISPLAY_SHELL_NAMES, shellTitle = null, promptState = null) {
     return getSessionDisplayLines(session, activeProgram, cwd, shellNames, shellTitle, promptState).primary;
 }
-/** Resolve the same title hints the session sidebar uses, without exposing route IDs. */
+/** Sidebar, tabs, inventories, selectors and server messages use this same projection. */
+export function getSessionPresentation(session, shellNames = DEFAULT_SESSION_DISPLAY_SHELL_NAMES) {
+    const { primary, secondary } = getSessionDisplayLines(session, session.activeProgram ?? null, session.cwd ?? null, shellNames, session.shellTitle ?? null, session.promptState ?? null);
+    return { displayName: primary, displaySubtitle: secondary };
+}
+/** Compatibility export for callers that still consume `name` in orchestration payloads. */
 export function collaborationSessionDisplayName(session) {
-    const cwdLeaf = getCwdLeafName(session.cwd ?? null);
-    const title = session.shellTitle === session.cwd || session.shellTitle === cwdLeaf ? null : session.shellTitle ?? null;
-    const name = getSessionDisplayName(session, session.activeProgram ?? null, null, DEFAULT_SESSION_DISPLAY_SHELL_NAMES, title);
-    return !name.trim() || /^(?:tmux:|remote:|wt-)/i.test(name) || name === session.sessionId
-        ? session.agent?.displayName || cwdLeaf || '终端会话'
-        : name;
+    return getSessionPresentation(session).displayName;
 }

package/dist/server/utils/settings.js

@@ -1,3 +1,4 @@
+import { isValidAndroidSerial } from '../shared/androidDevices.js';
 import crypto from 'crypto';
 import fs from 'fs';
 import os from 'os';
@@ -173,8 +174,9 @@ export function normalizeAndroidPanel(value) {
             docked = { sessionId: item.sessionId, side };
         }
     }
-    const deviceSerial = typeof raw.deviceSerial === 'string' && /^[0-9a-zA-Z_.:\-]{1,128}$/.test(raw.deviceSerial) ? raw.deviceSerial : null;
-    return { enabled, quality, activePresetId, presets, docked, deviceSerial };
+    const deviceSerial = typeof raw.deviceSerial === 'string' && isValidAndroidSerial(raw.deviceSerial) ? raw.deviceSerial : null;
+    const devicePhysicalId = typeof raw.devicePhysicalId === 'string' && /^[a-f0-9]{64}$/.test(raw.devicePhysicalId) ? raw.devicePhysicalId : null;
+    return { enabled, quality, activePresetId, presets, docked, deviceSerial, devicePhysicalId };
 }
 export function normalizePinnedExplorerRoots(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -786,7 +788,8 @@ export function setRightSidebarTabsSetting(patch) {
 export function getAndroidPanelSetting() { return loadSettings().androidPanel; }
 export function setAndroidPanelSetting(patch) {
     return updateSettings((settings) => {
-        settings.androidPanel = normalizeAndroidPanel({ ...settings.androidPanel, ...patch });
+        const resetIdentity = patch.deviceSerial !== undefined && patch.deviceSerial !== settings.androidPanel.deviceSerial && patch.devicePhysicalId === undefined;
+        settings.androidPanel = normalizeAndroidPanel({ ...settings.androidPanel, ...(resetIdentity ? { devicePhysicalId: null } : {}), ...patch });
     });
 }
 export function getCollaborationPanelsSetting() { return loadSettings().collaborationPanels; }

package/dist/server/utils/tmuxDisplayGeometry.js

@@ -0,0 +1,54 @@
+import { claimTmuxSize } from './tmuxSizeOwnership.js';
+import { retainTmuxObserverSize } from './tmuxObserverSize.js';
+/** All tmux display entries use this owner/observer transaction. Resizing a
+ * display without its observer makes refreshing the page shrink the window.
+ * The session's existing I/O queue serializes these operations across clients.
+ */
+export class TmuxDisplayGeometry {
+    observer;
+    run;
+    sessionName;
+    displayPids;
+    initialSize;
+    current;
+    firstResize = true;
+    constructor(observer, run, sessionName, displayPids, initialSize) {
+        this.observer = observer;
+        this.run = run;
+        this.sessionName = sessionName;
+        this.displayPids = displayPids;
+        this.initialSize = initialSize;
+        this.current = { cols: initialSize?.cols ?? observer.cols, rows: initialSize?.rows ?? observer.rows };
+    }
+    get size() { return { cols: this.current.cols, rows: this.current.rows }; }
+    reset() { this.firstResize = true; }
+    async prepareAttach(size, supportsOwnership) {
+        const clients = (await this.run(['list-clients', '-t', this.sessionName, '-F', '#{client_pid} #{client_tty} #{client_flags}']))
+            .split('\n').map(line => line.trim().split(/\s+/));
+        const metadata = clients.find(([pid]) => pid === String(this.observer.ptyProcess.pid));
+        if (metadata?.[1] && supportsOwnership) {
+            await this.run(['refresh-client', '-t', metadata[1], '-f', 'ignore-size']);
+        }
+        const hasSizeOwner = clients.some(([pid, tty, flags]) => tty && pid !== String(this.observer.ptyProcess.pid)
+            && !flags?.split(',').includes('ignore-size'));
+        if (this.initialSize && supportsOwnership && !hasSizeOwner)
+            retainTmuxObserverSize(this.observer, size.cols, size.rows);
+    }
+    async resize(display, requested, supportsOwnership) {
+        if (!display.attached || !Number.isFinite(requested.cols) || !Number.isFinite(requested.rows) || requested.cols < 1 || requested.rows < 1) {
+            return { ok: false, ...this.size, redraw: false };
+        }
+        const size = { cols: Math.floor(requested.cols), rows: Math.floor(requested.rows) };
+        if (supportsOwnership)
+            await claimTmuxSize(this.run, this.sessionName, display.pid, this.displayPids());
+        const same = this.current.cols === size.cols && this.current.rows === size.rows;
+        const ok = same ? display.attached : display.resize(size.cols, size.rows);
+        if (!ok)
+            return { ok: false, ...this.size, redraw: false };
+        retainTmuxObserverSize(this.observer, size.cols, size.rows);
+        const redraw = same && !this.firstResize;
+        this.firstResize = false;
+        this.current = size;
+        return { ok: true, ...this.size, redraw };
+    }
+}

package/dist/server/utils/tmuxObserverSize.js

@@ -0,0 +1,26 @@
+/** An ignored observer still becomes tmux's size fallback when every browser
+ * disconnects. Keep it at the selected display's grid, never the 80x24 default.
+ */
+export function retainTmuxObserverSize(session, cols, rows) {
+    if (session.cols === cols && session.rows === rows)
+        return;
+    session.ptyProcess.resize(cols, rows);
+    session.cols = cols;
+    session.rows = rows;
+}
+/** Preserve an existing window when creating its backend observer, including
+ * after a service restart. A guessed default would resize the running TUI.
+ */
+export async function readTmuxObserverSize(run, target) {
+    // display-message resolves a pane; an exact session target needs its colon.
+    const paneTarget = target.startsWith('=') && !target.includes(':') ? `${target}:` : target;
+    const raw = await run(['display-message', '-p', '-t', paneTarget, '#{window_width} #{window_height} #{status}']);
+    const [width, height, status] = raw.trim().split(/\s+/);
+    const cols = Number(width), paneRows = Number(height);
+    const statusRows = status === 'on' ? 1 : status === 'off' ? 0 : Number(status);
+    if (![cols, paneRows, statusRows].every(Number.isSafeInteger)
+        || cols < 1 || paneRows < 1 || statusRows < 0 || statusRows > 5) {
+        throw new Error('TMUX_WINDOW_GEOMETRY_UNAVAILABLE');
+    }
+    return { cols, rows: paneRows + statusRows };
+}

package/docs/integrations.md

@@ -107,7 +107,8 @@ after-id 不在本组保留记录中返回 MESSAGE_NOT_FOUND；前缀不唯一
 
 ## 管理员配置身份
 
-接口只监听本机 Unix socket `~/.termdock/integration-<port>.sock`（0600），
+接口只监听本机 Unix socket `~/.termdock/integration-<port>.sock`（0600）。
+用户目录过长时自动使用 `/tmp` 下按用户与目录摘要隔离的私有短路径（目录 0700）；CLI 会自动解析同一路径。
 不暴露 HTTP 业务接口，不使用网页转发。首版身份绑定**一个本机协作组**，
 不支持跨服务组。先在 TD 建立本机组，再查询其 ID：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.356",
+  "version": "1.4.357",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",
@@ -43,7 +43,11 @@
     "trace:fsio": "node scripts/inspect-fs-io.mjs",
     "release:classify": "node scripts/classify-release.mjs",
     "test": "vitest --passWithNoTests",
+    "test:initialization": "node --test tests/nodePtyInstall.test.mjs tests/installUtils.test.mjs && node --import tsx --test tests/initialization.process.test.mjs && vitest run --maxWorkers=2 src/server/utils/bootCheck.test.ts src/server/utils/localHttpsSetup.test.ts src/server/utils/nodePtyCleanup.test.ts",
+    "test:initialization:real": "node --import tsx --test tests/initialization.real.test.mjs",
     "test:webgl": "vitest run --config vitest.webgl.config.ts",
+    "test:terminal-geometry": "vitest run src/lib/terminal/geometry.test.ts src/lib/terminal/geometryBoundary.test.ts src/lib/terminal/fitHysteresis.test.ts src/lib/terminal/api.continuousReconnect.test.ts src/lib/components/terminal/TerminalViewportPasteOwnership.test.tsx src/lib/federation/SessionAccessView.test.tsx src/server/utils/tmuxDisplayGeometry.test.ts src/server/utils/tmuxObserverSize.test.ts src/server/utils/tmuxSizeOwnership.test.ts src/server/utils/terminalHandshakeDimensions.test.ts src/server/routes/terminalInitialSize.test.ts src/server/routes/terminalSampling.test.ts",
+    "test:terminal-geometry:browser": "vitest run --config vitest.webgl.config.ts src/lib/terminal/geometry.browser.ts",
     "test:ui": "vitest --ui",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/postinstall.mjs",

package/runtime-manifest.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.356",
+  "version": "1.4.357",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-uodaeckvlR6JDQ73ORIEefAICJ13wyApaFoGn2b0/GA=",
-  "serverBundleHash": "sha256-EleaQUnsAD9SVsw4yzpj1baMo/wPvtGD+nxHeqQJMFw=",
-  "clientBundleHash": "sha256-JdYvt3n9O/BJP9I3C9SqhKgOGybj4C++jnfeyaQhd5I=",
+  "serverBundleHash": "sha256-LrgxHOq6BzR9VFmkNZxOiK7Lgp7ni4xHbMySIQZlfjA=",
+  "clientBundleHash": "sha256-SV6wLRzsYqg3fI+zXukBIdsqpzRzaJk01KT3kP1TnyY=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }

package/scripts/install-utils.cjs

@@ -0,0 +1,81 @@
+// Shared by npm postinstall and the first-start checks. Never invoke a shell or
+// open a sudo password prompt from an npm lifecycle/background process.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+function findExecutable(command, { env = process.env, home = os.homedir(), platform = process.platform } = {}) {
+  const extra = [path.join(home, '.termdock/bin'), path.join(home, '.local/bin'), '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+  if (platform === 'darwin') extra.push('/opt/homebrew/bin', '/opt/local/bin');
+  const candidates = command.includes(path.sep) ? [path.resolve(command)] : [...new Set([...(env.PATH || '').split(path.delimiter).filter(Boolean), ...extra])].map(dir => path.resolve(dir, command));
+  for (const candidate of candidates) {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch { /* Continue through the actual executable paths. */ }
+  }
+  return null;
+}
+
+function runFile(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 120_000, ...options });
+  return { ok: !result.error && result.status === 0, stdout: result.stdout || '', stderr: result.stderr || '',
+    error: result.error?.message || (result.status !== 0 ? `exit status=${result.status ?? 'none'}${result.signal ? `; signal=${result.signal}` : ''}` : '') };
+}
+
+function tmuxInstallPlan(platform = process.platform, find = findExecutable) {
+  const candidates = platform === 'darwin' ? [
+    ['brew', ['install', 'tmux'], false], ['port', ['install', 'tmux'], true], ['nix-env', ['-iA', 'nixpkgs.tmux'], false],
+  ] : platform === 'linux' ? [
+    ['apt-get', ['install', '-y', 'tmux'], true], ['dnf', ['install', '-y', 'tmux'], true],
+    ['yum', ['install', '-y', 'tmux'], true], ['apk', ['add', 'tmux'], true],
+    ['pacman', ['-S', '--noconfirm', 'tmux'], true], ['zypper', ['--non-interactive', 'install', 'tmux'], true],
+    ['nix-env', ['-iA', 'nixpkgs.tmux'], false],
+  ] : [];
+  for (const [name, args, needsRoot] of candidates) {
+    const command = find(name);
+    if (command) return { command, args, needsRoot, hint: `${needsRoot ? 'sudo ' : ''}${name} ${args.join(' ')}` };
+  }
+  return null;
+}
+
+function checkTmux({ platform = process.platform, uid = process.getuid?.(), find = findExecutable, run = runFile } = {}) {
+  const probe = () => {
+    const command = find('tmux');
+    if (!command) return null;
+    const result = run(command, ['-V'], { timeout: 5000 });
+    return result.ok && /^tmux\s+\d/.test(result.stdout.trim()) ? result.stdout.trim() : null;
+  };
+  const version = probe();
+  if (version) return { ok: true, installed: false, version };
+  const plan = tmuxInstallPlan(platform, find);
+  if (!plan) return { ok: false, installed: false, error: 'tmux is unavailable. Install it with your system package manager (Windows: use WSL).' };
+  let command = plan.command, args = plan.args;
+  if (plan.needsRoot && uid !== 0) {
+    const sudo = find('sudo');
+    if (!sudo || !run(sudo, ['-n', 'true'], { timeout: 5000 }).ok) {
+      return { ok: false, installed: false, error: `tmux is unavailable; automatic installation needs root or passwordless sudo. Run: ${plan.hint}` };
+    }
+    command = sudo; args = ['-n', plan.command, ...args];
+  }
+  const installed = run(command, args);
+  const checked = probe();
+  return checked ? { ok: true, installed: true, version: checked }
+    : { ok: false, installed: false, error: `tmux installation did not produce a usable executable. Run: ${plan.hint}. ${(installed.stderr || installed.error || 'Installer returned without a working tmux').trim().slice(-1500)}` };
+}
+
+function probeNodePty(ptyRoot) {
+  const pty = require(ptyRoot);
+  // A stale/nonexistent $SHELL (or a minimal distro without bash) does not mean
+  // the native addon needs recompiling. Probe the portable system shell.
+  const child = pty.spawn(process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : '/bin/sh',
+    process.platform === 'win32' ? ['/c', 'exit', '0'] : ['-c', 'exit 0'], { name: 'xterm', cols: 80, rows: 24 });
+  child.kill();
+}
+
+function clearPtyModuleCache(ptyRoot) {
+  for (const file of Object.keys(require.cache)) if (file.startsWith(ptyRoot + path.sep)) delete require.cache[file];
+}
+
+module.exports = { findExecutable, runFile, tmuxInstallPlan, checkTmux, probeNodePty, clearPtyModuleCache };