[Init] Initial commit - NetMesh terminal manager

domain/terminalHibernate.ts

@@ -0,0 +1,172 @@
+import type { TerminalSession, TerminalSettings } from "./models/terminal";
+
+/** Compile-time kill switch for terminal hibernate (Settings > Terminal still controls user default). */
+export const TERMINAL_HIBERNATE_ENABLED = true;
+
+/** Default delay before hibernating a hidden tab (seconds). */
+export const TERMINAL_HIBERNATE_DELAY_SEC_DEFAULT = 5;
+
+export const TERMINAL_HIBERNATE_DELAY_SEC_MIN = 5;
+
+export const TERMINAL_HIBERNATE_DELAY_SEC_MAX = 600;
+
+/** Default delay in milliseconds (legacy constant for tests). */
+export const TERMINAL_HIBERNATE_DELAY_MS = TERMINAL_HIBERNATE_DELAY_SEC_DEFAULT * 1000;
+
+export function normalizeHibernateHiddenTabsDelaySec(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return TERMINAL_HIBERNATE_DELAY_SEC_DEFAULT;
+  }
+  return Math.min(
+    TERMINAL_HIBERNATE_DELAY_SEC_MAX,
+    Math.max(TERMINAL_HIBERNATE_DELAY_SEC_MIN, Math.round(value)),
+  );
+}
+
+export function resolveTerminalHibernateDelayMs(
+  settings?: Pick<TerminalSettings, "hibernateHiddenTabsDelaySec"> | null,
+): number {
+  return normalizeHibernateHiddenTabsDelaySec(settings?.hibernateHiddenTabsDelaySec) * 1000;
+}
+
+export function resolveTerminalHibernateEnabled(
+  settings?: Pick<TerminalSettings, "hibernateHiddenTabs"> | null,
+): boolean {
+  if (!TERMINAL_HIBERNATE_ENABLED) return false;
+  return settings?.hibernateHiddenTabs === true;
+}
+
+export function resolveTerminalHibernateEnabledForProtocol(
+  settings: Pick<TerminalSettings, "hibernateHiddenTabs"> | null | undefined,
+  protocol: string | null | undefined,
+): boolean {
+  return protocol !== "local" && resolveTerminalHibernateEnabled(settings);
+}
+
+/** Hidden connected and ended remote terminals can both release their xterm runtime. */
+export function canHibernateTerminalRuntimeStatus(
+  status: TerminalSession["status"],
+): boolean {
+  return status === "connected" || status === "disconnected";
+}
+
+export function canHibernateTerminalRuntimeSession(
+  status: TerminalSession["status"],
+  backendSessionId: string | null | undefined,
+): boolean {
+  if (!canHibernateTerminalRuntimeStatus(status)) return false;
+  return status === "disconnected" || Boolean(backendSessionId);
+}
+
+export function shouldKeepTerminalBackgroundWorkActive(
+  settings: Pick<TerminalSettings, "hibernateHiddenTabs"> | null | undefined,
+  protocol: string | null | undefined,
+  isVisible: boolean,
+): boolean {
+  return isVisible || !resolveTerminalHibernateEnabledForProtocol(settings, protocol);
+}
+
+/** Block hibernate while a file transfer or drag-drop session is in progress. */
+export function isTerminalFileTransferActive(options: {
+  zmodemActive: boolean;
+  ymodemInProgress: boolean;
+  isDraggingOver: boolean;
+}): boolean {
+  return options.zmodemActive || options.ymodemInProgress || options.isDraggingOver;
+}
+
+/** Lines kept when snapshotting xterm scrollback before hibernate. */
+export const TERMINAL_HIBERNATE_SNAPSHOT_MAX_LINES = 3_000;
+
+/** Default chunk size for replaying hibernate snapshots without blocking the main thread. */
+export const TERMINAL_HIBERNATE_REPLAY_CHUNK_BYTES_DEFAULT = 16 * 1024;
+
+export const TERMINAL_HIBERNATE_REPLAY_CHUNK_BYTES_MIN = 4 * 1024;
+
+export const TERMINAL_HIBERNATE_REPLAY_CHUNK_BYTES_MAX = 64 * 1024;
+
+/** Hidden tabs whose xterm runtime is kept alive (WebGL suspended) before full hibernate. */
+export const TERMINAL_HIBERNATE_KEEP_RENDERER_COUNT_DEFAULT = 2;
+
+export const TERMINAL_HIBERNATE_KEEP_RENDERER_COUNT_MIN = 0;
+
+export const TERMINAL_HIBERNATE_KEEP_RENDERER_COUNT_MAX = 12;
+
+/** Max chars buffered in renderer while xterm is hibernated (post-snapshot output). */
+export const TERMINAL_HIBERNATE_BUFFER_MAX_CHARS = 512 * 1024;
+
+export function capHibernateBuffer(buffer: string, maxChars = TERMINAL_HIBERNATE_BUFFER_MAX_CHARS): string {
+  if (buffer.length <= maxChars) return buffer;
+  return buffer.slice(buffer.length - maxChars);
+}
+
+export function capHibernateBufferByLines(text: string, maxLines: number): string {
+  if (maxLines <= 0 || text.length === 0) return text;
+  const lines = text.split("\n");
+  if (lines.length <= maxLines) return text;
+  return lines.slice(lines.length - maxLines).join("\n");
+}
+
+export function normalizeHibernateReplayChunkBytes(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return TERMINAL_HIBERNATE_REPLAY_CHUNK_BYTES_DEFAULT;
+  }
+  return Math.min(
+    TERMINAL_HIBERNATE_REPLAY_CHUNK_BYTES_MAX,
+    Math.max(TERMINAL_HIBERNATE_REPLAY_CHUNK_BYTES_MIN, Math.round(value)),
+  );
+}
+
+export function normalizeHibernateKeepRendererCount(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return TERMINAL_HIBERNATE_KEEP_RENDERER_COUNT_DEFAULT;
+  }
+  return Math.min(
+    TERMINAL_HIBERNATE_KEEP_RENDERER_COUNT_MAX,
+    Math.max(TERMINAL_HIBERNATE_KEEP_RENDERER_COUNT_MIN, Math.round(value)),
+  );
+}
+
+export function resolveTerminalHibernateReplayChunkBytes(
+  settings?: Pick<TerminalSettings, "hibernateReplayChunkBytes"> | null,
+): number {
+  return normalizeHibernateReplayChunkBytes(settings?.hibernateReplayChunkBytes);
+}
+
+export function resolveHibernateKeepRendererCount(
+  settings?: Pick<TerminalSettings, "hibernateKeepRendererCount"> | null,
+): number {
+  return normalizeHibernateKeepRendererCount(settings?.hibernateKeepRendererCount);
+}
+
+export function resolveHibernateSkipAltScreen(
+  settings?: Pick<TerminalSettings, "hibernateSkipAltScreen"> | null,
+): boolean {
+  return settings?.hibernateSkipAltScreen !== false;
+}
+
+export function resolveHibernatePreferWasmSerialize(
+  settings?: Pick<TerminalSettings, "hibernatePreferWasmSerialize"> | null,
+): boolean {
+  return settings?.hibernatePreferWasmSerialize === true;
+}
+
+export function shouldSkipHibernateForAltScreen(
+  alternateScreen: boolean,
+  settings?: Pick<TerminalSettings, "hibernateSkipAltScreen"> | null,
+): boolean {
+  return alternateScreen && resolveHibernateSkipAltScreen(settings);
+}
+
+/** Snapshot + buffered output to replay when recreating xterm after hibernate. */
+export type TerminalHibernateWakePayload = {
+  /** Full serialized terminal state -- preferred wake history (coherent ANSI). */
+  snapshot: string;
+  /** Visible viewport rows; used with scrollback only when snapshot is empty. */
+  viewportSnapshot?: string;
+  /** Older scrollback rows; used with viewport only when snapshot is empty. */
+  scrollbackSnapshot?: string;
+  pendingBuffer: string;
+  /** True when the pane was hibernated while a full-screen app owned the alt buffer. */
+  alternateScreen: boolean;
+};