[Init] Initial commit - NetMesh terminal manager

components/terminal/terminalHibernateRuntime.ts

@@ -0,0 +1,364 @@
+import type { Terminal as XTerm } from "@xterm/xterm";
+import type { SerializeAddon } from "@xterm/addon-serialize";
+
+import {
+  capHibernateBuffer,
+  capHibernateBufferByLines,
+  TERMINAL_HIBERNATE_SNAPSHOT_MAX_LINES,
+  type TerminalHibernateWakePayload,
+} from "../../domain/terminalHibernate";
+import type { XTermRuntime } from "./runtime/createXTermRuntime";
+import { readActiveTerminalBufferTextRange } from "./terminalContextBuffer";
+import { serializeTerminalBuffer } from "./terminalSerialize";
+import {
+  writeTerminalPayloadChunked,
+  writeTerminalReplaySequence,
+  type TerminalReplayOptions,
+} from "./terminalReplay";
+
+export function isTerminalAlternateScreenActive(term: XTerm): boolean {
+  return (term.buffer.active as { type?: string }).type === "alternate";
+}
+
+export function resolveHibernateSerializeOptions(term: XTerm): {
+  excludeAltBuffer: boolean;
+  excludeModes: boolean;
+  alternateScreen: boolean;
+} {
+  const alternateScreen = isTerminalAlternateScreenActive(term);
+  return {
+    excludeAltBuffer: !alternateScreen,
+    excludeModes: !alternateScreen,
+    alternateScreen,
+  };
+}
+
+export type TerminalHibernateSnapshot = {
+  snapshot: string;
+  viewportSnapshot: string;
+  scrollbackSnapshot: string;
+  contextSnapshot?: string;
+  contextViewportSnapshot?: string;
+  contextScrollbackSnapshot?: string;
+  alternateScreen: boolean;
+};
+
+type MutableValue<T> = { current: T };
+
+export function applyAuthoritativeHibernateSnapshot(
+  refs: {
+    snapshot: MutableValue<string>;
+    viewportSnapshot: MutableValue<string>;
+    scrollbackSnapshot: MutableValue<string>;
+    contextSnapshot: MutableValue<string>;
+    contextViewportSnapshot: MutableValue<string>;
+    contextScrollbackSnapshot: MutableValue<string>;
+    pendingBuffer: MutableValue<string>;
+    alternateScreen: MutableValue<boolean>;
+  },
+  snapshot: string,
+  context: TerminalHibernateContextSnapshot,
+): void {
+  refs.snapshot.current = snapshot;
+  refs.viewportSnapshot.current = snapshot;
+  refs.scrollbackSnapshot.current = "";
+  refs.contextSnapshot.current = context.contextSnapshot;
+  refs.contextViewportSnapshot.current = context.contextViewportSnapshot;
+  refs.contextScrollbackSnapshot.current = context.contextScrollbackSnapshot;
+  refs.pendingBuffer.current = "";
+  refs.alternateScreen.current = context.alternateScreen;
+}
+
+export type TerminalHibernateContextSnapshot = Required<Pick<
+  TerminalHibernateSnapshot,
+  "contextSnapshot" | "contextViewportSnapshot" | "contextScrollbackSnapshot" | "alternateScreen"
+>>;
+
+export function resolveTerminalSnapshotCapture(
+  serialized: unknown,
+  context: TerminalHibernateContextSnapshot,
+): { snapshot: string; context: TerminalHibernateContextSnapshot } {
+  if (typeof serialized === "string") return { snapshot: serialized, context };
+  const plainText = context.alternateScreen
+    ? context.contextViewportSnapshot
+    : context.contextSnapshot;
+  const replayText = plainText.replace(/\r?\n/g, "\r\n");
+  return {
+    snapshot: context.alternateScreen
+      ? `\x1b[?1049h\x1b[H${replayText}`
+      : replayText,
+    context,
+  };
+}
+
+function isEmptyTerminalContext(text: string): boolean {
+  return text.split("\n").every((line) => line.length === 0);
+}
+
+export function readTerminalHibernateContext(
+  term: XTerm,
+): TerminalHibernateContextSnapshot {
+  const rows = Math.max(1, term.rows);
+  const bufferLength = resolveActiveBufferLength(term);
+
+  if (isTerminalAlternateScreenActive(term)) {
+    const contextViewportSnapshot = readActiveTerminalBufferTextRange(term, {
+      startLine: 0,
+      endLine: Math.max(0, rows - 1),
+    });
+    const empty = isEmptyTerminalContext(contextViewportSnapshot);
+    return {
+      contextSnapshot: empty ? "" : contextViewportSnapshot,
+      contextViewportSnapshot: empty ? "" : contextViewportSnapshot,
+      contextScrollbackSnapshot: "",
+      alternateScreen: true,
+    };
+  }
+
+  const activeBuffer = term.buffer.active as typeof term.buffer.active & { viewportY?: number };
+  const bottomViewportStart = Math.max(0, bufferLength - rows);
+  const viewportStart = Math.min(
+    bottomViewportStart,
+    Math.max(0, activeBuffer.viewportY ?? bottomViewportStart),
+  );
+  const viewportEnd = bufferLength > 0
+    ? Math.min(bufferLength - 1, viewportStart + rows - 1)
+    : -1;
+  const contextViewportSnapshot = readActiveTerminalBufferTextRange(term, {
+    startLine: viewportStart,
+    endLine: viewportEnd,
+  });
+  const contextStart = Math.min(
+    viewportStart,
+    Math.max(0, bufferLength - TERMINAL_HIBERNATE_SNAPSHOT_MAX_LINES),
+  );
+  const contextEnd = bufferLength > 0
+    ? Math.min(
+      bufferLength - 1,
+      Math.max(viewportEnd, contextStart + TERMINAL_HIBERNATE_SNAPSHOT_MAX_LINES - 1),
+    )
+    : -1;
+  const contextScrollbackSnapshot = viewportStart > 0
+    ? readActiveTerminalBufferTextRange(term, {
+      startLine: contextStart,
+      endLine: viewportStart - 1,
+    })
+    : "";
+  const contextSnapshot = readActiveTerminalBufferTextRange(term, {
+    startLine: contextStart,
+    endLine: contextEnd,
+  });
+  if (isEmptyTerminalContext(contextSnapshot)) {
+    return {
+      contextSnapshot: "",
+      contextViewportSnapshot: "",
+      contextScrollbackSnapshot: "",
+      alternateScreen: false,
+    };
+  }
+  return {
+    contextSnapshot,
+    contextViewportSnapshot,
+    contextScrollbackSnapshot,
+    alternateScreen: false,
+  };
+}
+
+function resolveActiveBufferLength(term: XTerm): number {
+  return term.buffer.active.length;
+}
+
+async function serializeWithOptions(
+  term: XTerm,
+  serializeAddon: SerializeAddon,
+  options: Record<string, unknown>,
+  preferWasm: boolean,
+): Promise<string> {
+  try {
+    return await serializeTerminalBuffer({
+      term,
+      serializeAddon,
+      options,
+      preferWasm,
+    });
+  } catch {
+    return "";
+  }
+}
+
+export async function serializeTerminalForHibernate(
+  term: XTerm,
+  serializeAddon: SerializeAddon,
+  options: { preferWasm?: boolean; prepare?: () => Promise<void> } = {},
+): Promise<TerminalHibernateSnapshot> {
+  await options.prepare?.();
+  const { excludeAltBuffer, excludeModes, alternateScreen } = resolveHibernateSerializeOptions(term);
+  const preferWasm = options.preferWasm === true;
+  const rows = Math.max(1, term.rows);
+  const bufferLength = resolveActiveBufferLength(term);
+  let context: TerminalHibernateContextSnapshot = {
+    contextSnapshot: "",
+    contextViewportSnapshot: "",
+    contextScrollbackSnapshot: "",
+    alternateScreen,
+  };
+  try {
+    context = readTerminalHibernateContext(term);
+  } catch {
+    // A transient buffer read failure must not prevent visual snapshot capture.
+  }
+
+  try {
+    if (alternateScreen) {
+      const endRow = Math.max(0, rows - 1);
+      const viewportSnapshot = capHibernateBufferByLines(
+        await serializeWithOptions(term, serializeAddon, {
+          excludeAltBuffer: false,
+          excludeModes: false,
+          range: { start: 0, end: endRow },
+        }, preferWasm),
+        rows,
+      );
+      return {
+        snapshot: viewportSnapshot,
+        viewportSnapshot,
+        scrollbackSnapshot: "",
+        ...context,
+        alternateScreen: true,
+      };
+    }
+
+    const viewportStart = Math.max(0, bufferLength - rows);
+    const viewportEnd = Math.max(0, bufferLength - 1);
+    const viewportSnapshot = await serializeWithOptions(term, serializeAddon, {
+      excludeAltBuffer,
+      excludeModes,
+      range: { start: viewportStart, end: viewportEnd },
+    }, preferWasm);
+    let scrollbackSnapshot = "";
+    if (viewportStart > 0) {
+      const scrollbackStart = Math.max(0, viewportStart - TERMINAL_HIBERNATE_SNAPSHOT_MAX_LINES);
+      scrollbackSnapshot = capHibernateBufferByLines(
+        await serializeWithOptions(term, serializeAddon, {
+          excludeAltBuffer,
+          excludeModes,
+          range: { start: scrollbackStart, end: viewportStart - 1 },
+        }, preferWasm),
+        TERMINAL_HIBERNATE_SNAPSHOT_MAX_LINES,
+      );
+    }
+
+    const snapshot = capHibernateBufferByLines(
+      await serializeWithOptions(term, serializeAddon, {
+        excludeAltBuffer,
+        excludeModes,
+      }, preferWasm),
+      TERMINAL_HIBERNATE_SNAPSHOT_MAX_LINES,
+    );
+
+    return {
+      snapshot,
+      viewportSnapshot,
+      scrollbackSnapshot,
+      ...context,
+      alternateScreen: false,
+    };
+  } catch {
+    return {
+      snapshot: "",
+      viewportSnapshot: "",
+      scrollbackSnapshot: "",
+      alternateScreen: isTerminalAlternateScreenActive(term),
+    };
+  }
+}
+
+export function appendHibernatePendingBuffer(current: string, chunk: string): string {
+  return capHibernateBuffer(current + chunk);
+}
+
+export function refreshTerminalViewport(term: XTerm): void {
+  const endRow = term.rows - 1;
+  if (endRow < 0) return;
+  term.refresh(0, endRow);
+}
+
+export async function appendTerminalReplayData(
+  term: XTerm,
+  data: string,
+  replayOptions?: TerminalReplayOptions,
+): Promise<void> {
+  return writeTerminalPayloadChunked(term, data, replayOptions);
+}
+
+export type ApplyHibernateWakeOptions = {
+  replayOptions?: TerminalReplayOptions;
+  deferWebgl?: boolean;
+};
+
+/**
+ * Resolve the pre-pending history bytes to replay on hibernate wake.
+ * Prefer the coherent full snapshot: SerializeAddon range slices omit a
+ * trailing newline at the boundary, so concatenating scrollback+viewport can
+ * merge the seam lines. Fall back to scrollback -> viewport when snapshot is
+ * empty (still never viewport-first -- that evicts newest rows under a finite
+ * scrollback cap; #2762).
+ */
+export function resolveHibernateWakeHistory(payload: TerminalHibernateWakePayload): string {
+  if (payload.snapshot) return payload.snapshot;
+  const viewport = payload.viewportSnapshot ?? "";
+  const scrollback = payload.scrollbackSnapshot ?? "";
+  if (!scrollback) return viewport;
+  if (!viewport) return scrollback;
+  if (/\r?\n$/.test(scrollback)) return `${scrollback}${viewport}`;
+  return `${scrollback}\r\n${viewport}`;
+}
+
+export async function applyHibernateWakeToTerminal(
+  term: XTerm,
+  runtime: XTermRuntime,
+  payload: TerminalHibernateWakePayload,
+  options: ApplyHibernateWakeOptions = {},
+): Promise<void> {
+  const replayOptions = options.replayOptions;
+  const history = resolveHibernateWakeHistory(payload);
+
+  // Chunked writes already yield to the event loop for large buffers. Do not
+  // idle-append older scrollback after the viewport: under a finite xterm
+  // scrollback cap that trims the just-restored newest rows (#2762).
+  await writeTerminalReplaySequence(
+    term,
+    [history, payload.pendingBuffer],
+    replayOptions,
+  );
+
+  if (!options.deferWebgl) {
+    runtime.ensureWebglRenderer();
+    runtime.clearTextureAtlas();
+  }
+
+  if (payload.alternateScreen) {
+    refreshTerminalViewport(term);
+  }
+}
+
+export function nudgeAlternateScreenRedraw(term: XTerm): void {
+  // A same-size resize does not notify the PTY, but xterm still synchronously
+  // drains its private parser buffer before returning. During a large TUI frame
+  // that can interrupt the normal write callback and strand renderer flow.
+  // Public refresh is sufficient to repaint the already-parsed viewport.
+  refreshTerminalViewport(term);
+}
+
+export function buildHibernateWakePayload(
+  snapshot: TerminalHibernateSnapshot,
+  pendingBuffer: string,
+): TerminalHibernateWakePayload {
+  return {
+    snapshot: snapshot.snapshot,
+    viewportSnapshot: snapshot.viewportSnapshot,
+    scrollbackSnapshot: snapshot.scrollbackSnapshot,
+    pendingBuffer,
+    alternateScreen: snapshot.alternateScreen,
+  };
+}