Files
Netcatty/components/terminal/useTerminalEffects.ts
T
3490b0673d fix: StrictMode 双发清理 + 笔记页卡顿优化 (#2810)
* Cursor: Apply local changes for cloud agent

* fix(terminal): stop first SSH fail under StrictMode remount

Defer backend boot past the double-invoke, cancel superseded vault init,
gate start on vault hydration, and harden hotkey/attach cleanup so the
first connect no longer races a stale close or empty keychain.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* perf: finish StrictMode mega-subscriber plan (accent isolation + docs)

Stabilize published terminal themes across custom-accent drag, apply accent
at chrome/log leaves and CSS injection only, land Phase 0 design/plan docs,
and lock Host-bag / Bugbot-clean contracts for the isolation checklist.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* docs: add StrictMode mega-subscriber design and plan artifacts

Force-add Phase 0 spec/plan under docs/superpowers (gitignored locally)
so the delivery branch carries the approved design and plan copy.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: clear remaining StrictMode doubles and notes editor jank

Gate every AI send and reject concurrent runTurn, latch tray connect flush
and settings persistMounted remounts, and stop notes content drafts from
rebuilding MDXEditor/shell on each keystroke.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* perf: gate hidden notes panel subscribe and skip host-link annotate on keystrokes

Hidden terminal notes mounts keep a live snapshot read but stop listening to
publishes. Host-link DOM annotation follows hosts/mode (preview MutationObserver)
instead of every markdown value change.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: latch SSH transport idle TTL notify under StrictMode

Avoid duplicate main-process notifySettingsChanged on effect double-invoke
when the idle TTL value has not changed.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* perf: freeze inactive vault notes against hosts churn and prefetch MDXEditor

Gate the retained VaultNotesSection notesStore subscription while hidden,
ignore hosts identity in its memo compare when inactive, and warm the lazy
InlineMarkdownEditor chunk when notes become active.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: clear remaining AI StrictMode double-fire hazards

Latch Ask-AI terminal selection on requestId before draft mutation, hoist
Codex App Server IPC bridge to App (ref-counted), and make Catty
requestApproval join an existing waiter for the same toolCallId.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: remount-safe AI send latch and skip stale MCP approval IPC

Replace the component sendInFlightRef with a module key latch so StrictMode
panel remount cannot reopen a mid-flight send, and no-op resolveApproval when
the pending entry is already drained.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* test: allow gated useNotesStore in VaultNotesSection memo contract

The retained notes section now passes enabled:isActive so hidden mounts do
not subscribe; update the VaultView memo source assertion accordingly.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: keep note drafts across mode toggle and external note publishes

Flush ref-only content before edit/preview remount, and skip prop→editor
setMarkdown while a local draft diverges from the last synced value.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* chore: strip StrictMode sermon comments after Bugbot/Comment Sicko pass

Keep effect-order and public-export contracts; drop remount/perf narration
that the latches and tests already encode.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix: remount-safe Ask-AI terminal selection latch

Move consumed requestIds to a module Set so StrictMode remount cannot
append the same selection chip twice before parent state clears.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* chore: drop remount latch comment

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>
2026-08-07 14:38:24 +00:00

1881 lines
71 KiB
TypeScript

/* eslint-disable @typescript-eslint/no-explicit-any, react-hooks/exhaustive-deps */
import { useRef } from 'react';
import { publishPluginTerminalRuntimeLifecycleEvent } from '../../application/state/pluginTerminalRuntimeLifecycle';
import { markTerminalCommandCompletionPending } from './runtime/promptLineBreak';
import { resolveFontWeightBold } from '../../lib/fontWeightAvailability';
import { bundledFamiliesInStack } from '../../lib/fontAvailability';
import { isMacPlatform } from '../../lib/utils';
import { resolveXTermScrollback } from '../../infrastructure/config/xtermPerformance';
import {
createMacOptionForcedSelectionMouseEvent,
createRightClickMouseTrackingPressClaim,
shouldInterceptMouseTrackingContextMenu,
shouldReplayShiftMouseSelectionAsMacOption,
shouldStopRightClickMouseTrackingMouseUp,
} from './runtime/middleClickBehavior';
import {
hasOpenAppDialog,
TERMINAL_SESSION_RESTORE_FOCUS_EVENT,
type TerminalSessionRestoreFocusDetail,
} from './focusTerminalSession';
import {
resolveHibernatePreferWasmSerialize,
resolveTerminalHibernateEnabledForProtocol,
} from '../../domain/terminalHibernate';
import { setTerminalBootEpoch } from '../../domain/terminalBootEpoch';
import { applyUserCursorBlinkPreference } from './runtime/cursorPreference';
import { resolveCursorLineHighlightBackground } from '../../domain/cursorLineHighlight';
import { getFlowControllerForTerm } from './runtime/terminalSessionAttachment';
import {
prioritizeTerminalInput,
shouldArmTerminalInterruptDisplayGateForProtocol,
} from './runtime/terminalOutputPipeline';
import { scheduleTerminalThemeUpdate, applyTerminalThemeSync, cancelTerminalThemeUpdate } from './terminalThemeScheduler';
import { injectTerminalPaneAppearanceVars } from '../../infrastructure/theme/terminalAppearanceVars';
import {
isTerminalAlternateScreenActive,
nudgeAlternateScreenRedraw,
} from './terminalHibernateRuntime';
import {
cancelScheduledUnfocusedRepaint,
flushPendingTerminalWritesBeforeHibernate,
flushPendingTerminalWritesOnResume,
forceTerminalRepaintBypassingAnimationFrame,
repaintTerminalAfterReveal,
} from './runtime/terminalUnfocusedRepaint';
import {
forceXTermFontRemeasure,
type XTermFontRemeasureTarget,
} from './runtime/terminalFontRemeasure';
import { shouldClaimTerminalKeyboardFocus } from '../../domain/terminalKeyboardFocus';
import {
isTerminalCloseGenerationCurrent,
resolveConnectionLogCapturePayload,
scheduleTerminalCloseTeardown,
serializeTerminalCloseFallback,
} from './runtime/terminalCloseCapture';
import {
getConnectionTimeoutMs,
resolveActiveConnectionTimeoutHost,
shouldRunConnectionTimeout,
} from './connectionTimeouts';
import { resolveHostSshConnectionTimeouts } from '../../domain/sshConnectionTimeouts';
import { resolveEffectiveTerminalProtocol } from '../../domain/terminalProtocol';
import { isPluginHostProtocol } from '../../domain/pluginConnection';
type TerminalEffectsContext = Record<string, any>;
type SelectionOverlayPosition = {
left: number;
top: number;
} | null;
type ZmodemToastInput = {
active?: boolean;
completed?: boolean;
error?: string | null;
filename?: string | null;
transferType?: 'upload' | 'download' | null;
};
type ZmodemToast =
| { kind: 'error'; message: string; title: string }
| { kind: 'success'; message: string; title: string }
| null;
type ZmodemToastApi = {
success: (message: string, title?: string) => void;
error: (message: string, title?: string) => void;
};
const CSS_ONLY_TAB_REVEAL_MAX_HIDDEN_MS = 3000;
export function resolveZmodemTransferToast(zmodem: ZmodemToastInput): ZmodemToast {
if (zmodem.active) return null;
if (zmodem.error) {
return { kind: 'error', message: zmodem.error, title: 'ZMODEM' };
}
if (!zmodem.completed) return null;
const action = zmodem.transferType === 'upload'
? 'Uploaded'
: zmodem.transferType === 'download'
? 'Downloaded'
: 'Transfer completed';
const message = zmodem.filename ? `${action}: ${zmodem.filename}` : action;
return { kind: 'success', message, title: 'ZMODEM' };
}
export function applyZmodemTransferToast(
zmodem: ZmodemToastInput,
toastedRef: { current: boolean },
toast: ZmodemToastApi,
): void {
if (zmodem.active) {
toastedRef.current = false;
return;
}
if (toastedRef.current) return;
const zmodemToast = resolveZmodemTransferToast(zmodem);
if (!zmodemToast) return;
toastedRef.current = true;
if (zmodemToast.kind === 'error') {
toast.error(zmodemToast.message, zmodemToast.title);
} else {
toast.success(zmodemToast.message, zmodemToast.title);
}
}
export function resolveSelectionOverlayPosition(term: any, container: HTMLElement | null): SelectionOverlayPosition {
if (!container || !term?.getSelectionPosition || !term.getSelection()) return null;
const range = term.getSelectionPosition();
if (!range) return null;
const start = range.start;
const end = range.end;
const startsBeforeEnd =
start.y < end.y
|| (start.y === end.y && start.x <= end.x);
const top = startsBeforeEnd ? start : end;
const bottom = startsBeforeEnd ? end : start;
const viewportY = term.buffer?.active?.viewportY ?? 0;
const row = top.y - viewportY;
const rows = Math.max(1, term.rows ?? 1);
const cols = Math.max(1, term.cols ?? 1);
if (row < 0 || row >= rows) return null;
const screen = container.querySelector<HTMLElement>(".xterm-screen") ?? container;
const screenRect = screen.getBoundingClientRect();
const containerRect = container.getBoundingClientRect();
const cellWidth = screen.clientWidth / cols;
const cellHeight = screen.clientHeight / rows;
const spansRows = top.y !== bottom.y;
const rightCol = spansRows ? cols : Math.max(top.x, bottom.x);
const containerOffsetLeft = container.offsetLeft ?? 0;
const containerOffsetTop = container.offsetTop ?? 0;
const selectionRight = containerOffsetLeft + screenRect.left - containerRect.left + Math.min(cols, rightCol) * cellWidth;
const selectionTop = containerOffsetTop + screenRect.top - containerRect.top + row * cellHeight;
return {
left: Math.max(140, Math.min(selectionRight + 8, container.clientWidth - 8)),
top: Math.max(36, Math.min(selectionTop - 8, container.clientHeight - 8)),
};
}
export function useTerminalEffects(ctx: TerminalEffectsContext) {
const { CONNECTION_TIMEOUT, Error, XTERM_PERFORMANCE_CONFIG, applyUserCursorPreference, auth, autocompleteCloseRef, autocompleteInputRef, autocompleteKeyEventRef, captureTerminalLogData, chainHosts, chainProgress, clearTerminalCwd, commandBufferRef, connectionLogBufferRef, containerRef, createPromptLineBreakState, createReplaySafeTerminalLogSanitizer, createXTermRuntime, deferTerminalResizeRef, disableTerminalFontZoomRef, effectiveFontSize, effectiveFontWeight, effectiveTheme, error, executeSnippetCommand, finalizeTerminalLogData, fitAddonRef, fontFamilyId, fontSize, fontWeightFixupDoneRef, forceCloseHibernatedSession, forceSyncRenderAfterResize, handleOsc52ReadRequest, handleTerminalDataCaptureOnce, hasConnectedRef, hasRuntimeRef, host, hotkeySchemeRef, hibernatedRef, identities, inWorkspace, isBootActiveRef, bootEpochRef, isBroadcastEnabledRef, isComposeBarOpen, isConnectionAwaitingUserInput, isConnectionPastTcpDial, isFocusMode, isFocused, isLocalConnection, isNetworkDevice, isResizing, isRestoringSelectionRef, isSearchOpen, isSerialConnection, isVisible, isVisibleRef, keyBindingsRef, keys, kittyKeyboardProtocolEnabledForSession, knownCwdRef, lastFittedSizeRef, lastToastedErrorRef, logger, mouseTrackingRef, needsHostKeyVerification, onBroadcastInputRef, onBroadcastInterruptPriorityChange, onCommandExecuted, onCommandSubmitted, onHotkeyActionRef, onOpenExternalError, onOutputTriggerUserInputRef, onPluginRuntimeCwdChange, onSnippetExecutorChange, onTerminalCwdChange, onTerminalTitleChange, onTerminalBell, onTerminalFontSizeChange, paneLayoutKey, passwordPromptActiveRef, pendingAuthRef, pendingOutputScrollRef, pluginDecorationRules, pluginTerminalLifecycle, pluginTerminalProviderRevision, isPluginTerminalProviderAvailable, requestPluginTerminalProviders, prepareRestoredReconnect, prepareInitialCwdIntent, prevIsResizingRef, promptLineBreakStateRef, resizeSession, resolveHostAuth, resolvedFontFamily, safeFit, scriptRecorderRef, searchAddonRef, serialConfig, serialLineBufferRef, serializeAddonRef, sessionId, sessionRef, sessionStarters, setError, setHasMouseTracking, setIsCancelling, setIsDisconnectedDialogDismissed, requestSearchFocus, setNeedsHostKeyVerification, setPendingHostKeyInfo, setPendingHostKeyRequestId, setProgressLogs, setProgressValue, setShowLogs, setStatus, setTimeLeft, shouldEnableNativeUserInputAutoScroll, shouldProbeSessionCwd, shouldStartTerminalBackend, attachExistingSession, attachAuthorization, attachHomeWebContentsIdRef, onSnippetShortkeyRef, snippetsRef, splitResizeActive, status, statusRef, sudoAutofillRef, t, teardown, telnetLocalEchoRef, termRef, terminalAltKeyOptions, terminalBackend, terminalContextActionsRef, terminalCwdTracker, terminalDataCapturedRef, terminalLogSanitizerRef, terminalSettings, terminalSettingsRef, terminalTitleRef, toHostKeyInfo, toast, updateStatus, useEffect, useLayoutEffect, xtermRuntimeRef, zmodem, zmodemToastedRef, restoreState, vaultInitialized } = ctx;
const effectiveTerminalProtocol = resolveEffectiveTerminalProtocol(host);
const hibernateHiddenTabs = resolveTerminalHibernateEnabledForProtocol(
terminalSettings,
effectiveTerminalProtocol,
) && !kittyKeyboardProtocolEnabledForSession;
ctx.pluginDecorationRulesRef.current = pluginDecorationRules;
const pluginAwareOnCommandSubmitted = (...args: Parameters<NonNullable<typeof onCommandSubmitted>>) => {
markTerminalCommandCompletionPending(promptLineBreakStateRef);
publishPluginTerminalRuntimeLifecycleEvent(pluginTerminalLifecycle, 'commandSubmitted');
void xtermRuntimeRef.current?.pluginProviderHost?.commandSubmitted(args[0]);
};
const pluginAwareOnCommandCompleted = () => {
publishPluginTerminalRuntimeLifecycleEvent(pluginTerminalLifecycle, 'commandCompleted');
void xtermRuntimeRef.current?.pluginProviderHost?.commandCompleted();
};
const isRendererActive = isVisible || !hibernateHiddenTabs;
const isRendererActiveRef = useRef(isRendererActive);
isRendererActiveRef.current = isRendererActive;
// Remember the last layout we successfully refit while visible so revisiting
// the same workspace tab does not replay expensive force-fit/WebGL recovery.
const lastCommittedVisibleLayoutKeyRef = useRef<string | null>(null);
const lastWebglRecoveryLayoutKeyRef = useRef<string | null>(null);
const terminalBootCloseGenerationRef = useRef(0);
const hiddenAtRef = useRef<number | null>(null);
const wasVisibleRef = useRef(isVisible);
useEffect(() => {
if (xtermRuntimeRef.current) {
// Merge global rules with host-level rules
const globalRules = terminalSettings?.keywordHighlightRules ?? [];
const hostRules = host?.keywordHighlightRules ?? [];
const providerRules = pluginDecorationRules.map((rule) => ({
id: rule.id,
label: rule.label,
patterns: [...rule.patterns],
color: rule.color,
enabled: true,
providerId: rule.providerId,
}));
const globalEnabled = terminalSettings?.keywordHighlightEnabled ?? false;
// Host-level toggle: undefined = inherit global, true/false = explicit override
const hostEnabled = host?.keywordHighlightEnabled;
// Global and host-level highlights are independent:
// global toggle controls global rules, host toggle controls host-specific rules
const effectiveGlobalEnabled = globalEnabled;
const effectiveHostEnabled = hostEnabled ?? false;
const mergedRules = [
...(effectiveGlobalEnabled ? globalRules : []),
...(effectiveHostEnabled ? hostRules : []),
...providerRules,
];
const isEnabled = effectiveGlobalEnabled || effectiveHostEnabled || providerRules.length > 0;
xtermRuntimeRef.current.keywordHighlighter.setRules(mergedRules, isEnabled);
}
}, [
terminalSettings?.keywordHighlightEnabled,
terminalSettings?.keywordHighlightRules,
host?.keywordHighlightEnabled,
host?.keywordHighlightRules,
pluginDecorationRules,
]);
useEffect(() => {
const runtime = xtermRuntimeRef.current;
if (!runtime?.cursorLineHighlighter) return;
runtime.cursorLineHighlighter.setBackgroundColor(
resolveCursorLineHighlightBackground(effectiveTheme.colors),
);
runtime.cursorLineHighlighter.setEnabled(
terminalSettings?.highlightCursorLine ?? false,
);
}, [
effectiveTheme.colors.background,
effectiveTheme.colors.foreground,
effectiveTheme.colors.selection,
terminalSettings?.highlightCursorLine,
]);
useEffect(() => {
xtermRuntimeRef.current?.pluginProviderHost?.providerAvailabilityChanged(
effectiveTheme.colors.background,
);
xtermRuntimeRef.current?.pluginLinkProviderHost?.providerAvailabilityChanged();
}, [
effectiveTheme.colors.background,
pluginTerminalProviderRevision,
xtermRuntimeRef,
]);
useEffect(() => {
xtermRuntimeRef.current?.pluginProviderHost?.setActive(
status === 'connected',
effectiveTheme.colors.background,
);
xtermRuntimeRef.current?.pluginLinkProviderHost?.setActive(status === 'connected');
}, [effectiveTheme.colors.background, status, xtermRuntimeRef]);
useEffect(() => {
xtermRuntimeRef.current?.pluginProviderHost?.setVisible(
isVisible,
effectiveTheme.colors.background,
);
xtermRuntimeRef.current?.pluginLinkProviderHost?.setVisible(isVisible);
}, [effectiveTheme.colors.background, isVisible, xtermRuntimeRef]);
// Work around xterm.js WebGL renderer bug: glyphs rendered via the constructor
// look different from dynamically-set ones. After text appears on screen (status
// becomes "connected"), do a fontWeight round-trip to normalize the rendering.
useEffect(() => {
if (status !== 'connected' || fontWeightFixupDoneRef.current || !termRef.current) return;
fontWeightFixupDoneRef.current = true;
const timer = setTimeout(() => {
if (!termRef.current) return;
// Re-read the current weight at fire time to avoid stale closures
const w = termRef.current.options.fontWeight;
if (w === 'normal' || w === 400) return;
termRef.current.options.fontWeight = 'normal';
termRef.current.options.fontWeight = w;
}, 200);
return () => clearTimeout(timer);
}, [status]);
useEffect(() => {
clearTerminalCwd({ persistRestoreMetadata: false });
return () => clearTerminalCwd({ persistRestoreMetadata: false });
}, [clearTerminalCwd, host.id]);
useEffect(() => {
if (host.protocol === "local" || host.protocol === "serial" || host.protocol === "telnet"
|| isPluginHostProtocol(host.protocol)) {
return;
}
if (status !== "connected" || !sessionRef.current || knownCwdRef.current) return;
let cancelled = false;
const timer = setTimeout(async () => {
const id = sessionRef.current;
if (!id) return;
try {
// The pwd probe opens an extra POSIX-shell exec channel, which strict
// network-device CLIs like Huawei VRP answer by closing the whole
// session (#1043). Skip it for known network devices; for a brand-new
// host (distro not classified yet on the first connect) consult the
// SSH banner, which is captured for free at handshake time.
const info = await terminalBackend.getSessionRemoteInfo?.(id);
if (cancelled || id !== sessionRef.current) return;
if (!shouldProbeSessionCwd({ isNetworkDevice, remoteSshVersion: info?.remoteSshVersion })) {
return;
}
const result = await terminalBackend.getSessionPwd(id);
if (!cancelled && !terminalCwdTracker.getRendererCwd() && result.success && result.cwd) {
onPluginRuntimeCwdChange(result.cwd);
}
} catch {
// Best effort only.
}
}, 150);
return () => {
cancelled = true;
clearTimeout(timer);
};
}, [host.protocol, status, terminalBackend, terminalCwdTracker, isNetworkDevice]);
useEffect(() => {
if (!isVisible) {
autocompleteCloseRef.current?.();
}
}, [isVisible]);
useEffect(() => {
applyZmodemTransferToast(zmodem, zmodemToastedRef, toast);
}, [zmodem.active, zmodem.completed, zmodem.error, zmodem.filename, zmodem.transferType]);
useEffect(() => {
if (!error) {
lastToastedErrorRef.current = null;
return;
}
if (lastToastedErrorRef.current === error) return;
lastToastedErrorRef.current = error;
toast.error(error, t("terminal.connectionErrorTitle"));
}, [error, t]);
useEffect(() => {
const dispose = terminalBackend.onHostKeyVerification?.((request) => {
if (request.sessionId !== sessionId) return;
// Disconnect keeps the pane mounted; reject late host-key prompts instead
// of reopening approval UI on a disconnected / aborted boot. After a
// reconnect the shared flags are active again, so also require the
// request's boot epoch (when present) to match the current boot.
const requestBootEpoch = request.bootEpoch;
const bootEpochMismatch = Number.isFinite(requestBootEpoch)
&& bootEpochRef
&& requestBootEpoch !== bootEpochRef.current;
if (
!isBootActiveRef.current
|| statusRef.current === "disconnected"
|| bootEpochMismatch
) {
void terminalBackend.respondHostKeyVerification?.(request.requestId, false);
return;
}
setPendingHostKeyRequestId(request.requestId);
setPendingHostKeyInfo(toHostKeyInfo(request));
setNeedsHostKeyVerification(true);
setError(null);
setProgressLogs((prev) => [
...prev,
request.status === 'changed'
? `Host key changed for ${request.hostname}. Waiting for confirmation...`
: `Host key verification required for ${request.hostname}.`,
]);
});
return () => {
dispose?.();
};
}, [sessionId, terminalBackend]);
useEffect(() => {
// Restored sessions can mount while vault init has published hosts but not
// yet decrypted keys. Wait for hydration (and re-run when it flips) so the
// first SSH dial does not go out with an empty keychain.
if (!attachExistingSession && !vaultInitialized) {
return;
}
let disposed = false;
let initialFitTimer: ReturnType<typeof setTimeout> | undefined;
let ownedRuntime: { dispose: () => void } | null = null;
// Every boot owns a controller so cleanup can cancel an in-flight start
// instead of waiting for the async capture/teardown below to finish.
const bootAbort = new AbortController();
const bootStartOptions = { signal: bootAbort.signal };
const closeGeneration = ++terminalBootCloseGenerationRef.current;
if (bootEpochRef) {
bootEpochRef.current += 1;
setTerminalBootEpoch(sessionId, bootEpochRef.current);
}
isBootActiveRef.current = true;
terminalDataCapturedRef.current = false;
connectionLogBufferRef.current.reset();
terminalLogSanitizerRef.current = createReplaySafeTerminalLogSanitizer();
setError(null);
hasConnectedRef.current = false;
pendingOutputScrollRef.current = false;
setProgressLogs([]);
setShowLogs(false);
setIsCancelling(false);
setIsDisconnectedDialogDismissed(false);
promptLineBreakStateRef.current = createPromptLineBreakState();
const disposeOwnedRuntime = () => {
const runtime = ownedRuntime;
ownedRuntime = null;
if (!runtime) return;
if (xtermRuntimeRef.current === runtime) {
xtermRuntimeRef.current = null;
termRef.current = null;
fitAddonRef.current = null;
serializeAddonRef.current = null;
searchAddonRef.current = null;
hasRuntimeRef.current = false;
}
try {
runtime.dispose();
} catch (err) {
logger.warn("Failed to dispose terminal runtime on unmount", err);
}
};
const boot = async () => {
try {
if (disposed || !containerRef.current) return;
const runtime = createXTermRuntime({
container: containerRef.current,
host,
fontFamilyId,
resolvedFontFamily,
fontSize,
terminalTheme: effectiveTheme,
terminalSettingsRef,
kittyKeyboardProtocolEnabled: kittyKeyboardProtocolEnabledForSession,
terminalBackend,
sessionRef,
hotkeySchemeRef,
disableTerminalFontZoomRef,
keyBindingsRef,
onHotkeyActionRef,
onTerminalFontSizeChange,
onOpenExternalError,
isBroadcastEnabledRef,
onBroadcastInputRef,
snippetsRef,
onSnippetShortkeyRef,
sessionId,
statusRef,
onCommandExecuted,
onCommandSubmitted,
onTrustedCommandSubmitted: pluginAwareOnCommandSubmitted,
onCommandCompleted: pluginAwareOnCommandCompleted,
requestPluginTerminalProviders,
pluginProviderVisible: isVisible,
isPluginTerminalProviderAvailable,
onResize: (cols: number, rows: number) => (
publishPluginTerminalRuntimeLifecycleEvent(pluginTerminalLifecycle, 'resized', { cols, rows })
),
onAlternateScreenChange: (alternateScreen: boolean) => (
publishPluginTerminalRuntimeLifecycleEvent(
pluginTerminalLifecycle,
'alternateScreenChanged',
{ alternateScreen },
)
),
commandBufferRef,
promptLineBreakStateRef,
scriptRecorderRef,
passwordPromptActiveRef,
allowHostStyleGreaterThanPrompt: isNetworkDevice,
onOutputTriggerUserInputRef,
sudoAutofillRef,
requestSearchFocus,
// Serial-specific options
serialLocalEcho: serialConfig?.localEcho,
serialLineMode: serialConfig?.lineMode,
serialLineBufferRef,
telnetLocalEchoRef,
onTerminalLogData: captureTerminalLogData,
onCwdChange: (cwd: string) => {
onPluginRuntimeCwdChange(cwd, { source: 'osc7' });
},
onTitleChange: (title: string | null) => {
terminalTitleRef.current = title || undefined;
publishPluginTerminalRuntimeLifecycleEvent(
pluginTerminalLifecycle,
'titleChanged',
{ ...(title ? { title } : {}) },
);
onTerminalTitleChange?.(sessionId, title);
},
onBell: () => {
onTerminalBell?.(sessionId);
},
onOsc52ReadRequest: handleOsc52ReadRequest,
// Autocomplete integration
onAutocompleteKeyEvent: (e: KeyboardEvent) => autocompleteKeyEventRef.current?.(e) ?? true,
onAutocompleteInput: (data: string) => autocompleteInputRef.current?.(data),
terminalContextActionsRef,
isRestoringSelectionRef,
// Defer WebGL context creation for panes that mount hidden (e.g. the
// background tabs of a batch connect) until they first become visible.
initiallyVisible: isRendererActive,
});
if (disposed) {
runtime.dispose();
return;
}
ownedRuntime = runtime;
xtermRuntimeRef.current = runtime;
termRef.current = runtime.term;
fitAddonRef.current = runtime.fitAddon;
serializeAddonRef.current = runtime.serializeAddon;
searchAddonRef.current = runtime.searchAddon;
hasRuntimeRef.current = true;
// xterm boots asynchronously; ResizeObserver may have already run without
// fitAddon and will not re-attach until isVisible/isResizing changes.
initialFitTimer = setTimeout(() => {
if (disposed) return;
safeFit({ force: true, requireVisible: true });
}, 0);
// Apply merged keyword highlight rules immediately after runtime creation
// This fixes a timing issue where the useEffect for keyword highlighting
// runs before the runtime is created, causing host-level rules to be missed
const globalRules = terminalSettingsRef.current?.keywordHighlightRules ?? [];
const hostRules = host?.keywordHighlightRules ?? [];
const globalEnabled = terminalSettingsRef.current?.keywordHighlightEnabled ?? false;
const hostEnabled = host?.keywordHighlightEnabled;
const effectiveGlobalEnabled = globalEnabled;
const effectiveHostEnabled = hostEnabled ?? false;
const mergedRules = [
...(effectiveGlobalEnabled ? globalRules : []),
...(effectiveHostEnabled ? hostRules : [])
];
const isEnabled = effectiveGlobalEnabled || effectiveHostEnabled;
runtime.keywordHighlighter.setRules(mergedRules, isEnabled);
runtime.cursorLineHighlighter.setBackgroundColor(
resolveCursorLineHighlightBackground(effectiveTheme.colors),
);
runtime.cursorLineHighlighter.setEnabled(
terminalSettingsRef.current?.highlightCursorLine ?? false,
);
const term = runtime.term;
const restoredReconnect = restoreState === "restored-disconnected";
if (restoredReconnect) {
prepareRestoredReconnect?.();
} else {
prepareInitialCwdIntent?.();
}
const setBackendConnectingStatus = () => {
if (restoredReconnect) {
updateStatus("connecting");
} else {
setStatus("connecting");
}
};
if (attachExistingSession) {
// Observe popup: pause → snapshot → rebind → resume so no live bytes
// fall into the gap between snapshot and route handoff.
let outputRebound = false;
let reboundHomeWebContentsId: number | null = null;
const outputPauseLease = await terminalBackend.acquireSessionFlowPauseLease(sessionId);
try {
const paused = await outputPauseLease.waitForPause();
if (!paused?.success && paused?.error === "Output drain unavailable") {
await new Promise((resolve) => setTimeout(resolve, 40));
} else if (!paused?.success) {
throw new Error(paused?.error || "Failed to drain terminal output");
}
if (disposed) {
outputPauseLease.release();
return;
}
// Snapshot while home still owns the display route (and stream is paused).
const snap = await terminalBackend.requestSessionSnapshot?.(
sessionId,
attachAuthorization || "",
);
if (disposed) {
outputPauseLease.release();
return;
}
if (!snap?.success) {
throw new Error(snap?.error || "Failed to capture terminal snapshot");
}
if (typeof snap.kittyKeyboardProtocolEnabled === "boolean") {
runtime.setKittyKeyboardProtocolEnabled(snap.kittyKeyboardProtocolEnabled);
}
if (typeof snap.passwordPromptActive === "boolean") {
passwordPromptActiveRef.current = snap.passwordPromptActive;
}
if (snap.cwd !== undefined) {
const cwd = terminalCwdTracker.setRendererCwd(snap.cwd);
knownCwdRef.current = cwd;
publishPluginTerminalRuntimeLifecycleEvent(
pluginTerminalLifecycle,
'cwdChanged',
{ ...(cwd ? { cwd } : {}) },
);
onTerminalCwdChange?.(sessionId, cwd ?? null);
}
if (snap.title !== undefined) {
const title = snap.title || null;
terminalTitleRef.current = title ?? undefined;
publishPluginTerminalRuntimeLifecycleEvent(
pluginTerminalLifecycle,
'titleChanged',
{ ...(title ? { title } : {}) },
);
onTerminalTitleChange?.(sessionId, title);
}
if (snap.kittyKeyboardModeState) {
runtime.restoreKittyKeyboardModeState(snap.kittyKeyboardModeState);
}
if (snap?.success && snap.snapshot) {
try {
await new Promise<void>((resolve) => term.write(snap.snapshot!, resolve));
} catch (writeErr) {
logger.warn("Failed to write attach snapshot to popup terminal", writeErr);
}
}
const rebind = await terminalBackend.rebindSessionOutput?.(
sessionId,
attachAuthorization || "",
);
if (disposed) {
if (rebind?.success) {
try {
await terminalBackend.restoreSessionOutput?.(
sessionId,
rebind.previousWebContentsId ?? null,
attachAuthorization || "",
);
} catch {
// Main-process closed lifecycle remains the final fallback.
}
}
outputPauseLease.release();
return;
}
if (!rebind?.success) {
outputPauseLease.release();
setError(rebind?.error || "Failed to attach to session");
updateStatus("disconnected");
isBootActiveRef.current = false;
return;
}
outputRebound = true;
reboundHomeWebContentsId = rebind.previousWebContentsId ?? null;
if (attachHomeWebContentsIdRef) {
attachHomeWebContentsIdRef.current = rebind.previousWebContentsId ?? null;
}
sessionRef.current = sessionId;
const attached = sessionStarters.reattachSession(term);
if (!attached) {
throw new Error("Failed to attach display to session");
}
// Resume only after the popup has subscribed to the live session.
outputPauseLease.release();
hasConnectedRef.current = true;
updateStatus("connected");
setTimeout(() => {
if (disposed) return;
safeFit({ force: true, requireVisible: true });
try {
term.scrollToBottom?.();
} catch {
// ignore
}
try {
terminalBackend.resizeSession?.(sessionId, term.cols, term.rows);
} catch {
// ignore
}
}, 50);
} catch (attachErr) {
if (outputRebound) {
try {
const restored = await terminalBackend.restoreSessionOutput?.(
sessionId,
reboundHomeWebContentsId,
attachAuthorization || "",
);
if (restored?.success) outputPauseLease.release();
} catch {
// Main-process close/recovery lifecycle remains the fallback.
}
} else {
outputPauseLease.release();
}
if (disposed) return;
logger.error("Failed to attach existing session", attachErr);
setError(attachErr instanceof Error ? attachErr.message : String(attachErr));
updateStatus("disconnected");
}
isBootActiveRef.current = false;
return;
}
if (!shouldStartTerminalBackend()) {
isBootActiveRef.current = false;
return;
}
const bootStillActive = () => !disposed && isBootActiveRef.current;
if (effectiveTerminalProtocol.startsWith("plugin:")) {
setBackendConnectingStatus();
setProgressLogs(["Initializing plugin connection..."]);
await sessionStarters.startPluginConnection(term, bootStartOptions);
if (!bootStillActive()) return;
} else if (effectiveTerminalProtocol === "serial") {
setBackendConnectingStatus();
setProgressLogs(["Initializing serial connection..."]);
await sessionStarters.startSerial(term, bootStartOptions);
if (!bootStillActive()) return;
} else if (effectiveTerminalProtocol === "local") {
setBackendConnectingStatus();
setProgressLogs(["Initializing local shell..."]);
await sessionStarters.startLocal(term, bootStartOptions);
if (!bootStillActive()) return;
} else if (effectiveTerminalProtocol === "telnet") {
setBackendConnectingStatus();
setProgressLogs(["Initializing Telnet connection..."]);
await sessionStarters.startTelnet(term, bootStartOptions);
if (!bootStillActive()) return;
} else if (effectiveTerminalProtocol === "mosh") {
setBackendConnectingStatus();
setProgressLogs(["Initializing Mosh connection..."]);
await sessionStarters.startMosh(term, bootStartOptions);
if (!bootStillActive()) return;
} else if (effectiveTerminalProtocol === "et") {
setBackendConnectingStatus();
setProgressLogs(["Initializing EternalTerminal connection..."]);
await sessionStarters.startEt(term, bootStartOptions);
if (!bootStillActive()) return;
} else {
const resolvedAuth = resolveHostAuth({ host, keys, identities });
const hasPassword = !!resolvedAuth.password;
const hasKey = !!resolvedAuth.keyId;
const hasPendingAuth = pendingAuthRef.current;
if (
!hasPassword &&
!hasKey &&
!hasPendingAuth &&
!resolvedAuth.username
) {
auth.setNeedsAuth(true);
setStatus("disconnected");
return;
}
setBackendConnectingStatus();
setProgressLogs(["Initializing secure channel..."]);
await sessionStarters.startSSH(term, bootStartOptions);
if (!bootStillActive()) return;
}
} catch (err) {
if (disposed || !isBootActiveRef.current) return;
logger.error("Failed to initialize terminal", err);
setError(err instanceof Error ? err.message : String(err));
updateStatus("disconnected");
}
};
queueMicrotask(() => {
if (disposed) return;
void boot();
});
return () => {
disposed = true;
if (initialFitTimer !== undefined) clearTimeout(initialFitTimer);
// Abort first: a start still awaiting the bridge must stop counting as
// the current attempt before anything below yields to a microtask.
bootAbort.abort();
isBootActiveRef.current = false;
if (hibernatedRef?.current) {
forceCloseHibernatedSession?.();
disposeOwnedRuntime();
return;
}
// A boot that never reached "connected" has nothing worth capturing, and
// the teardown below awaits terminal drain plus serialization before it
// closes anything. Tell the main process now so it can abort the pending
// boot (passphrase prompt, TCP dial) for this epoch instead of letting it
// finish against a pane that is already gone. Attached popups never own
// the backend session (skip closeSession) but still sync-dispose xterm.
if (!hasConnectedRef.current) {
if (!attachExistingSession) {
try {
const closeResult = terminalBackend.closeSession(
sessionRef.current ?? sessionId,
{ bootEpoch: bootEpochRef ? bootEpochRef.current : undefined },
);
void Promise.resolve(closeResult).catch((err: unknown) => {
logger.warn("Failed to cancel pending terminal boot on unmount", err);
});
} catch (err) {
logger.warn("Failed to cancel pending terminal boot on unmount", err);
}
}
disposeOwnedRuntime();
return;
}
const persistCloseCapture = (data: string, source: string, dataLength: number) => {
logger.info("[Terminal] Capturing data on unmount", {
sessionId,
source,
dataLength,
});
handleTerminalDataCaptureOnce(sessionId, data, { finalized: true });
};
const term = termRef.current;
const completeClose = async () => {
if (term) {
// A hidden terminal can have more output queued than the synchronous
// resume helper intentionally drains. Wait for the complete ordered
// backlog before finalizing the saved capture.
const flushed = await flushPendingTerminalWritesBeforeHibernate(term);
if (!isTerminalCloseGenerationCurrent(
closeGeneration,
terminalBootCloseGenerationRef.current,
)) {
// Remount already replaced the live refs; still drop this boot's
// orphaned DOM node if dispose was deferred past the generation bump.
disposeOwnedRuntime();
return;
}
if (!flushed) {
logger.warn("Terminal output did not drain before close capture; skipping stale capture");
teardown();
ownedRuntime = null;
return;
}
}
if (!isTerminalCloseGenerationCurrent(
closeGeneration,
terminalBootCloseGenerationRef.current,
)) {
disposeOwnedRuntime();
return;
}
const connectionLogPayload = !terminalDataCapturedRef.current
? resolveConnectionLogCapturePayload(finalizeTerminalLogData)
: null;
if (connectionLogPayload) {
persistCloseCapture(
connectionLogPayload.data,
connectionLogPayload.source,
connectionLogPayload.data.length,
);
ownedRuntime = null;
scheduleTerminalCloseTeardown(teardown);
return;
}
const serializeAddon = serializeAddonRef.current;
if (!terminalDataCapturedRef.current && term && serializeAddon) {
const preferWasm = resolveHibernatePreferWasmSerialize(terminalSettingsRef.current);
try {
const payload = await serializeTerminalCloseFallback(term, serializeAddon, { preferWasm });
if (!isTerminalCloseGenerationCurrent(
closeGeneration,
terminalBootCloseGenerationRef.current,
)) {
disposeOwnedRuntime();
return;
}
if (payload) {
persistCloseCapture(payload.data, payload.source, payload.data.length);
}
ownedRuntime = null;
scheduleTerminalCloseTeardown(teardown);
} catch (err) {
if (!isTerminalCloseGenerationCurrent(
closeGeneration,
terminalBootCloseGenerationRef.current,
)) {
disposeOwnedRuntime();
return;
}
logger.warn("Failed to serialize terminal data on unmount:", err);
ownedRuntime = null;
scheduleTerminalCloseTeardown(teardown);
}
return;
}
ownedRuntime = null;
teardown();
};
void completeClose();
};
}, [
attachExistingSession,
forceCloseHibernatedSession,
handleTerminalDataCaptureOnce,
host.id,
sessionId,
vaultInitialized,
]);
// Connection timeline and timeout visuals
useEffect(() => {
const hasSshTcpConnectProgress = host.protocol !== "local"
&& host.protocol !== "serial"
&& host.protocol !== "telnet"
&& host.protocol !== "mosh"
&& !host.moshEnabled
&& host.protocol !== "et"
&& !host.etEnabled
&& !isPluginHostProtocol(host.protocol);
const timeoutState = {
status,
needsAuth: auth.needsAuth,
isLocalConnection,
isSerialConnection,
hasSshTcpConnectProgress,
needsHostKeyVerification: Boolean(needsHostKeyVerification),
isConnectionAwaitingUserInput: Boolean(isConnectionAwaitingUserInput),
isConnectionPastTcpDial: Boolean(isConnectionPastTcpDial),
};
if (!shouldRunConnectionTimeout(timeoutState)) return;
const activeTimeoutHost = resolveActiveConnectionTimeoutHost(
host,
chainHosts,
chainProgress?.currentHop,
chainProgress?.connectionPhase,
);
const hostConnectionTimeouts = resolveHostSshConnectionTimeouts(activeTimeoutHost);
const connectionTimeout = getConnectionTimeoutMs(timeoutState, {
tcpConnectTimeoutMs: hostConnectionTimeouts.tcpConnectTimeoutSeconds * 1000,
authReadyTimeoutMs: hostConnectionTimeouts.authReadyTimeoutSeconds * 1000,
}) || CONNECTION_TIMEOUT;
setTimeLeft(connectionTimeout / 1000);
const countdown = setInterval(() => {
setTimeLeft((prev) => (prev > 0 ? prev - 1 : 0));
}, 1000);
const timeout = setTimeout(() => {
setError("Connection timed out. Please try again.");
updateStatus("disconnected");
setProgressLogs((prev) => [...prev, "Connection timed out."]);
}, connectionTimeout);
setProgressValue(5);
const prog = setInterval(() => {
setProgressValue((prev) => {
if (prev >= 95) return prev;
const remaining = 95 - prev;
const increment = Math.max(1, remaining * 0.15);
return Math.min(95, prev + increment);
});
}, 200);
return () => {
clearInterval(countdown);
clearTimeout(timeout);
clearInterval(prog);
};
}, [status, auth.needsAuth, host.protocol, host.hostname, host.moshEnabled, host.etEnabled, host.sshTcpConnectTimeoutSeconds, host.sshAuthReadyTimeoutSeconds, chainHosts, chainProgress?.currentHop, chainProgress?.connectionPhase, isLocalConnection, isSerialConnection, needsHostKeyVerification, isConnectionAwaitingUserInput, isConnectionPastTcpDial]);
useEffect(() => {
if (status === "connecting") {
setIsDisconnectedDialogDismissed(false);
}
}, [status]);
const effectiveThemeKey = `${effectiveTheme.id}:${effectiveTheme.colors.background}:${effectiveTheme.colors.foreground}:${effectiveTheme.colors.cursor}`;
// Sync xterm theme before browser paint; apply synchronously on visible panes.
useLayoutEffect(() => {
const term = termRef.current;
if (!term) return;
if (isRendererActiveRef.current || isFocused) {
cancelTerminalThemeUpdate(sessionId);
applyTerminalThemeSync(term, effectiveTheme);
injectTerminalPaneAppearanceVars(sessionId, effectiveTheme);
return;
}
scheduleTerminalThemeUpdate(
sessionId,
effectiveTheme,
{ visible: false, focused: false },
() => termRef.current,
);
}, [effectiveThemeKey, isFocused, isVisible, sessionId, effectiveTheme]);
// Keep font-size sync separate from terminalSettings so unrelated setting
// updates (or focus/layout re-renders) do not reset a wheel/Ctrl zoom that
// has not yet propagated into React props.
useEffect(() => {
if (!termRef.current) return;
termRef.current.options.fontSize = effectiveFontSize;
xtermRuntimeRef.current?.clearTextureAtlas();
if (isRendererActiveRef.current) {
const refitTimer = setTimeout(() => safeFit({ force: true, requireVisible: true }), 50);
return () => clearTimeout(refitTimer);
} else {
lastFittedSizeRef.current = null;
}
}, [effectiveFontSize]);
useEffect(() => {
if (!termRef.current) return;
termRef.current.options.fontFamily = resolvedFontFamily;
if (terminalSettings) {
applyUserCursorPreference(termRef.current, terminalSettings);
termRef.current.options.scrollback = resolveXTermScrollback(terminalSettings.scrollback);
termRef.current.options.fontWeight = effectiveFontWeight as
| 100
| 200
| 300
| 400
| 500
| 600
| 700
| 800
| 900;
const resolvedFontWeightBold = resolveFontWeightBold({
fontFamilyCss: termRef.current?.options.fontFamily || "",
normalWeight: effectiveFontWeight,
desiredBoldWeight: terminalSettings.fontWeightBold,
fontSize: effectiveFontSize,
});
termRef.current.options.fontWeightBold = resolvedFontWeightBold as
| 100
| 200
| 300
| 400
| 500
| 600
| 700
| 800
| 900;
termRef.current.options.lineHeight = 1 + terminalSettings.linePadding / 10;
termRef.current.options.drawBoldTextInBrightColors =
terminalSettings.drawBoldInBrightColors;
termRef.current.options.minimumContrastRatio =
terminalSettings.minimumContrastRatio;
termRef.current.options.smoothScrollDuration =
terminalSettings.smoothScrolling
? XTERM_PERFORMANCE_CONFIG.rendering.smoothScrollDuration
: 0;
termRef.current.options.scrollOnUserInput =
shouldEnableNativeUserInputAutoScroll(terminalSettings);
const altKeyOpts = terminalAltKeyOptions(terminalSettings.altAsMeta);
termRef.current.options.macOptionIsMeta = altKeyOpts.macOptionIsMeta;
termRef.current.options.altClickMovesCursor = altKeyOpts.altClickMovesCursor;
termRef.current.options.wordSeparator = terminalSettings.wordSeparators;
termRef.current.options.ignoreBracketedPasteMode = terminalSettings.disableBracketedPaste ?? false;
}
// Changing the font can leave the WebGL renderer drawing stale glyphs from
// the old metrics (xterm.js #3280), surfacing as garbled text (issue #1049).
// Clear the texture atlas so glyphs re-rasterize with the new font.
xtermRuntimeRef.current?.clearTextureAtlas();
if (isRendererActiveRef.current) {
const refitTimer = setTimeout(() => safeFit({ force: true, requireVisible: true }), 50);
return () => clearTimeout(refitTimer);
} else {
lastFittedSizeRef.current = null;
}
}, [effectiveFontSize, effectiveFontWeight, resolvedFontFamily, terminalSettings]);
const runImmediateRefit = (options?: { force?: boolean; repeatOnNextFrame?: boolean }) => {
const force = options?.force === true;
const repeatOnNextFrame = options?.repeatOnNextFrame ?? force;
if (force) {
lastFittedSizeRef.current = null;
}
safeFit({ force, requireVisible: true, immediate: true });
if (force && repeatOnNextFrame && typeof requestAnimationFrame === 'function') {
requestAnimationFrame(() => {
safeFit({ force: true, requireVisible: true, immediate: true });
});
}
};
const syncPtySizeAfterLayout = () => {
const term = termRef.current;
const id = sessionRef.current;
if (!term || !id) return;
try {
if (isTerminalAlternateScreenActive(term)) {
nudgeAlternateScreenRedraw(term);
} else {
resizeSession(id, term.cols, term.rows);
}
} catch (err) {
logger.warn('Sync session size after layout failed', err);
}
};
const finishLayoutRecovery = () => {
const term = termRef.current;
if (term) {
forceSyncRenderAfterResize(term);
}
syncPtySizeAfterLayout();
};
const finishLayoutRecoveryAfterFit = () => {
const run = () => finishLayoutRecovery();
if (typeof requestAnimationFrame === 'function') {
requestAnimationFrame(() => requestAnimationFrame(run));
return;
}
window.setTimeout(run, 0);
};
const layoutRecoveryTimersRef = useRef<ReturnType<typeof setTimeout>[]>([]);
const clearLayoutRecoveryTimers = () => {
for (const timerId of layoutRecoveryTimersRef.current) {
clearTimeout(timerId);
}
layoutRecoveryTimersRef.current = [];
};
// Re-fit after the app returns from the background, macOS fullscreen toggles,
// or other layout changes that do not reliably fire window.resize /
// ResizeObserver (common after App Nap / GPU context eviction).
const scheduleLayoutRecoveryRefit = (delaysMs: number[] = [80, 250]) => {
clearLayoutRecoveryTimers();
for (const delayMs of delaysMs) {
const timerId = setTimeout(() => {
layoutRecoveryTimersRef.current = layoutRecoveryTimersRef.current.filter((id) => id !== timerId);
if (!isVisibleRef.current) return;
runImmediateRefit({ force: true, repeatOnNextFrame: false });
finishLayoutRecoveryAfterFit();
}, delayMs);
layoutRecoveryTimersRef.current.push(timerId);
}
};
useEffect(() => {
const handleRestoreFocus = (event: Event) => {
const detail = (event as CustomEvent<TerminalSessionRestoreFocusDetail>).detail;
if (detail?.sessionId !== sessionId) return;
if (!isVisibleRef.current) return;
const term = termRef.current;
if (!term) return;
applyUserCursorBlinkPreference(term, terminalSettingsRef.current);
if (hasOpenAppDialog()) return;
term.focus();
scheduleLayoutRecoveryRefit([0, 100]);
};
window.addEventListener(TERMINAL_SESSION_RESTORE_FOCUS_EVENT, handleRestoreFocus);
return () => window.removeEventListener(TERMINAL_SESSION_RESTORE_FOCUS_EVENT, handleRestoreFocus);
}, [sessionId]);
const layoutAlreadyCommitted = () => (
lastCommittedVisibleLayoutKeyRef.current === paneLayoutKey
);
const commitVisibleLayout = () => {
lastCommittedVisibleLayoutKeyRef.current = paneLayoutKey;
};
const currentContainerSizeAlreadyFit = () => {
const container = containerRef.current;
const lastSize = lastFittedSizeRef.current;
if (!container || !lastSize) return false;
const width = container.clientWidth;
const height = container.clientHeight;
return width > 0 && height > 0 && lastSize.width === width && lastSize.height === height;
};
const getHiddenDurationMs = () => (
hiddenAtRef.current !== null
? Date.now() - hiddenAtRef.current
: Number.POSITIVE_INFINITY
);
const flushPendingOutputScroll = () => {
if (!pendingOutputScrollRef.current) return;
termRef.current?.scrollToBottom();
if (typeof requestAnimationFrame === "function") {
requestAnimationFrame(() => {
termRef.current?.scrollToBottom();
});
}
pendingOutputScrollRef.current = false;
};
const flushTerminalWritesAfterBecomeVisible = () => {
lastCommittedVisibleLayoutKeyRef.current = null;
const term = termRef.current;
if (term) {
cancelScheduledUnfocusedRepaint(term);
flushPendingTerminalWritesOnResume(term);
repaintTerminalAfterReveal(term, () => isVisibleRef.current);
}
};
const recoverTerminalAfterBecomeVisible = () => {
flushTerminalWritesAfterBecomeVisible();
if (
getHiddenDurationMs() < CSS_ONLY_TAB_REVEAL_MAX_HIDDEN_MS
&& currentContainerSizeAlreadyFit()
) {
lastWebglRecoveryLayoutKeyRef.current = paneLayoutKey;
flushPendingOutputScroll();
commitVisibleLayout();
return;
}
xtermRuntimeRef.current?.ensureWebglRenderer();
xtermRuntimeRef.current?.clearTextureAtlas();
lastWebglRecoveryLayoutKeyRef.current = paneLayoutKey;
if (currentContainerSizeAlreadyFit()) {
finishLayoutRecovery();
flushPendingOutputScroll();
commitVisibleLayout();
return;
}
lastFittedSizeRef.current = null;
runImmediateRefit({ force: true, repeatOnNextFrame: false });
finishLayoutRecoveryAfterFit();
flushPendingOutputScroll();
commitVisibleLayout();
scheduleLayoutRecoveryRefit([100, 350]);
};
// Refit synchronously when a split pane becomes visible or its bounds change.
// Tab switches hide inactive panes without resizing xterm; becoming visible
// again does not always fire ResizeObserver, leaving a gap below content.
// Skip during split-divider drag — refit runs once when split resizing ends.
// Recover every visible pane immediately so split workspaces return with
// fresh terminal buffers, scroll positions, and PTY sizes.
useLayoutEffect(() => {
const becameVisible = isVisible && !wasVisibleRef.current;
if (!isVisible) {
wasVisibleRef.current = false;
return;
}
if (splitResizeActive) return;
wasVisibleRef.current = true;
if (becameVisible) {
recoverTerminalAfterBecomeVisible();
return;
}
if (layoutAlreadyCommitted()) {
safeFit({ requireVisible: true });
return;
}
commitVisibleLayout();
runImmediateRefit({ force: true, repeatOnNextFrame: false });
finishLayoutRecoveryAfterFit();
}, [isVisible, paneLayoutKey, splitResizeActive]);
useLayoutEffect(() => {
if (isVisible) return;
lastCommittedVisibleLayoutKeyRef.current = null;
lastWebglRecoveryLayoutKeyRef.current = null;
if (hiddenAtRef.current === null) {
hiddenAtRef.current = Date.now();
}
}, [isVisible]);
useEffect(() => {
if (!isVisible) return;
const hiddenMs = hiddenAtRef.current
? Date.now() - hiddenAtRef.current
: Number.POSITIVE_INFINITY;
hiddenAtRef.current = null;
if (
lastWebglRecoveryLayoutKeyRef.current === paneLayoutKey
&& hiddenMs < CSS_ONLY_TAB_REVEAL_MAX_HIDDEN_MS
) {
flushPendingOutputScroll();
return;
}
const timer = setTimeout(() => {
lastWebglRecoveryLayoutKeyRef.current = paneLayoutKey;
// A pane that mounted hidden deferred its WebGL renderer; create it now
// that it's visible (no-op if already active or WebGL is disabled).
xtermRuntimeRef.current?.ensureWebglRenderer();
// Recover the WebGL renderer now that this tab is visible again. Hidden
// panes stay mounted off-screen (visibility:hidden) so each keeps a live
// WebGL context; creating another terminal's context — or the GPU dropping
// a non-composited off-screen canvas — can leave this terminal's drawing
// buffer corrupted ("花屏", issue #1063). Because a hidden pane keeps its
// dimensions, becoming visible triggers no resize and therefore no redraw,
// so the corruption persists until the user resizes the window. Force the
// same recovery a resize performs: clear the texture atlas (no-op on the
// DOM renderer) and synchronously repaint every row.
xtermRuntimeRef.current?.clearTextureAtlas();
runImmediateRefit({ force: true });
finishLayoutRecoveryAfterFit();
flushPendingOutputScroll();
}, 50);
return () => clearTimeout(timer);
}, [isVisible, paneLayoutKey]);
useEffect(() => {
let cancelled = false;
// Re-derive cell metrics and repaint after a font finishes loading. xterm
// measures the cell grid once at open(); a webfont that swaps in later
// (font-display: swap on the bundled JetBrains Mono / Sarasa Mono SC, or
// any user-chosen webfont) leaves the grid sized to the fallback until a
// manual resize (#1647). This performs the same recovery a resize does.
const remeasureAfterFontLoad = () => {
const term = termRef.current as {
cols: number;
rows: number;
} & XTermFontRemeasureTarget | null;
if (cancelled || !term) return;
if (!isRendererActiveRef.current) {
lastFittedSizeRef.current = null;
return;
}
const fitAddon = fitAddonRef.current;
try {
if (!forceXTermFontRemeasure(term)) {
logger.warn("Font remeasure skipped: xterm measurement hook unavailable");
}
} catch (err) {
logger.warn("Font remeasure failed", err);
}
// Font remeasurement does not invalidate cells rasterized before fonts were ready.
xtermRuntimeRef.current?.clearTextureAtlas();
const visibleTerm = termRef.current;
if (visibleTerm) {
forceSyncRenderAfterResize(visibleTerm);
}
try {
fitAddon?.fit();
} catch (err) {
logger.warn("Fit after fonts ready failed", err);
}
if (terminalSettings && termRef.current) {
const resolvedBold = resolveFontWeightBold({
fontFamilyCss: termRef.current.options?.fontFamily || "",
normalWeight: effectiveFontWeight,
desiredBoldWeight: terminalSettings.fontWeightBold,
fontSize: effectiveFontSize,
});
termRef.current.options.fontWeightBold = resolvedBold as
| 100
| 200
| 300
| 400
| 500
| 600
| 700
| 800
| 900;
}
const id = sessionRef.current;
if (id) {
try {
resizeSession(id, term.cols, term.rows);
} catch (err) {
logger.warn("Resize session after fonts ready failed", err);
}
}
};
const fontFaceSet = document.fonts as FontFaceSet | undefined;
// Coalesce bursts of loadingdone events (a cold start loads several faces
// in quick succession) into a single remeasure.
let remeasureTimer: ReturnType<typeof setTimeout> | null = null;
const scheduleRemeasure = () => {
if (cancelled) return;
if (remeasureTimer) clearTimeout(remeasureTimer);
remeasureTimer = setTimeout(() => {
remeasureTimer = null;
remeasureAfterFontLoad();
}, 50);
};
// Any font finishing later than the initial measurement — including a
// user-chosen webfont primary — triggers a remeasure, so recovery no
// longer depends on the single document.fonts.ready resolution below.
const onLoadingDone = () => scheduleRemeasure();
fontFaceSet?.addEventListener?.("loadingdone", onLoadingDone);
const waitForFonts = async () => {
try {
if (!fontFaceSet?.ready) return;
await fontFaceSet.ready;
if (cancelled) return;
// Ensure bundled Nerd Font icon fallbacks are loaded at the terminal's
// cell size. Shell prompts can arrive before these faces finish loading
// on cold start (Linux), leaving Powerline glyphs cached as tofu (#1363).
try {
await fontFaceSet.load(`${effectiveFontSize}px "Symbols Nerd Font Mono"`);
} catch (err) {
logger.warn("Nerd Font preload failed", err);
}
// Explicitly load the bundled webfonts the terminal actually renders
// with (the Latin JetBrains Mono fallback, the Sarasa Mono SC CJK
// fallback). document.fonts.ready can resolve before these are even
// requested, so without this the cold-start grid stays mis-sized (#1647).
const fontFamilyCss = (termRef.current as { options?: { fontFamily?: string } } | null)
?.options?.fontFamily || "";
for (const family of bundledFamiliesInStack(fontFamilyCss)) {
try {
await fontFaceSet.load(`${effectiveFontSize}px "${family}"`);
} catch (err) {
logger.warn(`Bundled font preload failed: ${family}`, err);
}
}
if (cancelled) return;
remeasureAfterFontLoad();
} catch (err) {
logger.warn("Waiting for fonts failed", err);
}
};
waitForFonts();
return () => {
cancelled = true;
if (remeasureTimer) clearTimeout(remeasureTimer);
fontFaceSet?.removeEventListener?.("loadingdone", onLoadingDone);
};
}, [effectiveFontSize, effectiveFontWeight, resizeSession, resolvedFontFamily, terminalSettings]);
useEffect(() => {
if (!isRendererActive || !containerRef.current) return;
let resizeTimeout: ReturnType<typeof setTimeout> | null = null;
const observer = new ResizeObserver(() => {
if (deferTerminalResizeRef?.current || !isRendererActiveRef.current) return;
if (!fitAddonRef.current) return;
if (resizeTimeout) {
clearTimeout(resizeTimeout);
}
resizeTimeout = setTimeout(() => {
safeFit({ requireVisible: true });
}, 250);
});
observer.observe(containerRef.current);
return () => {
if (resizeTimeout) clearTimeout(resizeTimeout);
observer.disconnect();
};
}, [isRendererActive, isResizing]);
useLayoutEffect(() => {
if (splitResizeActive) {
prevIsResizingRef.current = true;
return;
}
if (!prevIsResizingRef.current || !isVisible) {
prevIsResizingRef.current = splitResizeActive;
return;
}
prevIsResizingRef.current = splitResizeActive;
lastFittedSizeRef.current = null;
safeFit({ force: true, requireVisible: true });
finishLayoutRecoveryAfterFit();
if (typeof requestAnimationFrame === 'function') {
requestAnimationFrame(() => {
safeFit({ force: true, requireVisible: true });
const term = termRef.current;
if (term) {
forceSyncRenderAfterResize(term);
syncPtySizeAfterLayout();
}
});
}
}, [splitResizeActive, isVisible]);
useEffect(() => {
if (!isVisible || !fitAddonRef.current) return;
// Fit twice: once after initial layout (100ms) and again after layout settles
// (350ms) to handle race conditions during split operations where the container
// dimensions may not be final on the first pass.
const timer1 = setTimeout(() => {
safeFit({ requireVisible: true });
finishLayoutRecoveryAfterFit();
}, 100);
const timer2 = setTimeout(() => {
safeFit({ force: true, requireVisible: true });
finishLayoutRecoveryAfterFit();
}, 350);
return () => { clearTimeout(timer1); clearTimeout(timer2); };
}, [inWorkspace, isVisible]);
// When search bar opens/closes, re-fit terminal and maintain scroll position
useEffect(() => {
const term = termRef.current;
if (!term || !fitAddonRef.current) return;
const buffer = term.buffer.active;
const wasAtBottom = buffer.viewportY >= buffer.baseY;
const prevViewportY = buffer.viewportY;
const timer = setTimeout(() => {
safeFit({ force: true, requireVisible: true });
requestAnimationFrame(() => {
if (wasAtBottom) {
term.scrollToBottom();
} else {
term.scrollToLine(prevViewportY);
}
});
}, 0);
return () => clearTimeout(timer);
}, [isSearchOpen]);
// When compose bar opens/closes, re-fit terminal and maintain scroll position
useEffect(() => {
const term = termRef.current;
if (!term || !fitAddonRef.current) return;
const buffer = term.buffer.active;
const wasAtBottom = buffer.viewportY >= buffer.baseY;
const prevViewportY = buffer.viewportY;
const timer = setTimeout(() => {
safeFit({ force: true, requireVisible: true });
requestAnimationFrame(() => {
safeFit({ force: true, requireVisible: true });
if (wasAtBottom) {
term.scrollToBottom();
} else {
term.scrollToLine(prevViewportY);
}
});
}, 0);
return () => clearTimeout(timer);
}, [isComposeBarOpen]);
useEffect(() => {
const shouldAutoFocus = isVisible && termRef.current && (!inWorkspace || isFocusMode);
if (shouldAutoFocus) {
const timer = setTimeout(() => {
// Pane focus ≠ document focus: do not yank caret from AI/side-panel inputs.
if (!shouldClaimTerminalKeyboardFocus(document.activeElement)) return;
termRef.current?.focus();
}, 50);
return () => clearTimeout(timer);
}
}, [isVisible, inWorkspace, isFocusMode]);
useEffect(() => {
if (isFocused && termRef.current && isVisible) {
const timer = setTimeout(() => {
if (!shouldClaimTerminalKeyboardFocus(document.activeElement)) return;
termRef.current?.focus();
}, 10);
return () => clearTimeout(timer);
}
}, [isFocused, isVisible, sessionId]);
// Selection overlay + copy-on-select live in TerminalSelectionAIOverlay so
// selection churn does not re-render the whole Terminal tree (e.g. when focus
// moves to the AI side panel and the selection clears).
// Track whether the terminal application has enabled mouse tracking
// (e.g. tmux with `set -g mouse on`, vim with `set mouse=a`).
// When mouse tracking is active, disable Netcatty's context menu to avoid
// conflicting with the application's own mouse handling.
useEffect(() => {
const term = termRef.current;
if (!term) return;
const disposable = term.onWriteParsed(() => {
const tracking = term.modes.mouseTrackingMode !== 'none';
if (tracking !== mouseTrackingRef.current) {
mouseTrackingRef.current = tracking;
setHasMouseTracking(tracking);
}
});
// Set initial state
const initial = term.modes.mouseTrackingMode !== 'none';
mouseTrackingRef.current = initial;
setHasMouseTracking(initial);
return () => disposable.dispose();
}, [sessionId]);
// Prevent xterm.js's built-in rightClickHandler from interfering with
// mouse-tracking TUIs. On macOS, xterm forces selection with Option, while
// most terminal users expect Shift to bypass mouse reporting. Replay
// Shift+left-click as that native xterm force-selection gesture before
// xterm receives the original.
// - mousedown (button 2 + Shift / fullscreen-apps menu): keep the press
// local so the terminal app does not also receive it
// - contextmenu: xterm.js calls textarea.select() which steals focus
// - mouseup (button 2): only stop when we also claimed the matching
// mousedown. App-owned right-clicks (Herdr, tmux, vim, ...) must receive
// the release or the TUI stays stuck with the button held (#2721).
// Intercepted at the capture phase before xterm.js's own listeners.
useEffect(() => {
const el = containerRef.current;
if (!el) return;
const rightClickPressClaim = createRightClickMouseTrackingPressClaim();
const handleContextMenuCapture = (e: MouseEvent) => {
if (!shouldInterceptMouseTrackingContextMenu({
event: e,
mouseTracking: mouseTrackingRef.current,
status: statusRef.current,
rightClickBehavior: terminalSettingsRef.current?.rightClickBehavior,
forceMenuInAlternateScreen: terminalSettingsRef.current?.showContextMenuOverFullscreenApps,
})) {
return;
}
e.preventDefault();
e.stopImmediatePropagation();
// stopImmediatePropagation blocks the event from reaching React's
// bubble-phase root listener, so the onContextMenu handler in
// TerminalContextMenu (which dispatches paste / select-word) never
// fires inside a mouse-tracking TUI. Without dispatching the user's
// chosen action here, right-click paste silently stops working in
// opencode, tmux with `mouse on`, vim with `set mouse=a`, etc. (#941).
// Middle-click still works because its auxclick listener lives in
// createXTermRuntime and isn't gated by mouseTracking.
const behavior = terminalSettingsRef.current?.rightClickBehavior;
if (behavior === 'paste') {
void terminalContextActionsRef.current?.onPaste?.();
} else if (behavior === 'select-word') {
terminalContextActionsRef.current?.onSelectWord?.();
}
// 'context-menu' is intentionally not handled — Radix opens the
// menu via its own pointerdown listener, which our capture handler
// does not intercept.
};
const handleMouseDownCapture = (e: MouseEvent) => {
if (rightClickPressClaim.noteMouseDown({
event: e,
mouseTracking: mouseTrackingRef.current,
status: statusRef.current,
rightClickBehavior: terminalSettingsRef.current?.rightClickBehavior,
forceMenuInAlternateScreen: terminalSettingsRef.current?.showContextMenuOverFullscreenApps,
})) {
e.stopImmediatePropagation();
return;
}
if (!shouldReplayShiftMouseSelectionAsMacOption({
event: e,
mouseTracking: mouseTrackingRef.current,
status: statusRef.current,
isMacPlatform: isMacPlatform(),
})) {
return;
}
const target = e.target as EventTarget | null;
if (!target || typeof target.dispatchEvent !== 'function') return;
e.preventDefault();
e.stopImmediatePropagation();
target.dispatchEvent(createMacOptionForcedSelectionMouseEvent(e));
};
const handleMouseUpCapture = (e: MouseEvent) => {
if (shouldStopRightClickMouseTrackingMouseUp({
event: e,
claimedMatchingMouseDown: rightClickPressClaim.consumeMouseUpClaim(e),
})) {
e.stopImmediatePropagation();
}
};
el.addEventListener('mousedown', handleMouseDownCapture, true);
el.addEventListener('contextmenu', handleContextMenuCapture, true);
el.addEventListener('mouseup', handleMouseUpCapture, true);
return () => {
el.removeEventListener('mousedown', handleMouseDownCapture, true);
el.removeEventListener('contextmenu', handleContextMenuCapture, true);
el.removeEventListener('mouseup', handleMouseUpCapture, true);
};
}, [sessionId]);
useEffect(() => {
if (!isRendererActive) return;
let resizeTimeout: ReturnType<typeof setTimeout> | null = null;
const handler = () => {
if (!isRendererActiveRef.current) return;
if (resizeTimeout) {
clearTimeout(resizeTimeout);
}
resizeTimeout = setTimeout(() => {
safeFit({ requireVisible: true });
}, 250);
};
window.addEventListener("resize", handler);
return () => {
if (resizeTimeout) clearTimeout(resizeTimeout);
window.removeEventListener("resize", handler);
};
}, [isRendererActive]);
useEffect(() => {
if (!isVisible) return;
const recoverWebglRendererOnAppResume = () => {
xtermRuntimeRef.current?.ensureWebglRenderer();
};
const recoverTerminalOnAppResume = () => {
const term = termRef.current;
if (term) {
cancelScheduledUnfocusedRepaint(term);
flushPendingTerminalWritesOnResume(term);
forceTerminalRepaintBypassingAnimationFrame(term);
}
flushPendingOutputScroll();
recoverWebglRendererOnAppResume();
scheduleLayoutRecoveryRefit([0, 100, 300]);
};
const handleVisibilityChange = () => {
if (document.visibilityState !== 'visible') return;
recoverTerminalOnAppResume();
};
const handleWindowFocus = () => {
recoverTerminalOnAppResume();
};
document.addEventListener('visibilitychange', handleVisibilityChange);
window.addEventListener('focus', handleWindowFocus);
const unsubscribeWindowShown = terminalBackend.onWindowShown?.(() => {
recoverTerminalOnAppResume();
});
// Fullscreen changes layout for every visible pane.
const unsubscribeFullscreen = terminalBackend.onWindowFullScreenChanged?.((isFullscreen) => {
scheduleLayoutRecoveryRefit(isFullscreen ? [0, 150, 400] : [0, 100, 300]);
});
return () => {
clearLayoutRecoveryTimers();
document.removeEventListener('visibilitychange', handleVisibilityChange);
window.removeEventListener('focus', handleWindowFocus);
unsubscribeWindowShown?.();
unsubscribeFullscreen?.();
};
}, [isVisible, terminalBackend]);
// Only register the snippet executor once the terminal session is ready.
// Before that, TerminalLayer falls back to raw writeToSession which is the
// correct path for sessions that are still connecting.
useEffect(() => {
if (status !== "connected") {
onSnippetExecutorChange?.(sessionId, null);
return;
}
onSnippetExecutorChange?.(sessionId, executeSnippetCommand);
return () => onSnippetExecutorChange?.(sessionId, null);
}, [executeSnippetCommand, onSnippetExecutorChange, sessionId, status]);
useEffect(() => {
if (status !== "connected") {
onBroadcastInterruptPriorityChange?.(sessionId, null);
return;
}
const prioritizeBroadcastInterrupt = () => {
const term = termRef.current;
if (!term) return;
prioritizeTerminalInput(
term,
sessionId,
getFlowControllerForTerm(term),
terminalBackend,
{
reason: "interrupt",
drainStaleOutput: shouldArmTerminalInterruptDisplayGateForProtocol(host.protocol),
},
);
};
onBroadcastInterruptPriorityChange?.(sessionId, prioritizeBroadcastInterrupt);
return () => onBroadcastInterruptPriorityChange?.(sessionId, null);
}, [
host.protocol,
onBroadcastInterruptPriorityChange,
sessionId,
status,
terminalBackend,
termRef,
]);
}