Files
Netcatty/components/terminal/autocomplete/useTerminalAutocomplete.ts
T
陈大猫andClaude Opus 4.7 73b27ad7c4 fix(autocomplete): sync ghost text to live input on every keystroke (#815)
* fix(autocomplete): sync ghost text to live input on every keystroke

Ghost text was displayed based on whatever input was passed to
GhostTextAddon.show() at fetch time. Between a user's keystroke and
the next debounced fetchSuggestions firing (~100ms), the on-screen
line had already advanced one character but ghost.getGhostText() still
returned the pre-update tail. Pressing → during that window pasted the
stale tail on top of the new char — e.g. type "do", suggestion shows
"cker ls"; type "c", accept immediately → "doc" + "cker ls" lands as
"doccker ls" instead of the expected "docker ls".

Two-layer fix:

1. New GhostTextAddon.adjustToInput(newInput) that re-renders the ghost
   against a fresh input without waiting for a new fetch: shrinks /
   grows the tail if the suggestion still prefix-matches, hides
   otherwise. Called from handleInput after every buffer mutation
   (printable, backspace, Ctrl-W, paste tail) when the buffer is
   reliable. Unreliable-buffer paths skip the call to avoid making the
   ghost lie.

2. Defense-in-depth at both ghost-accept sites (→ and Ctrl-→):
   recompute the tail against the live typed buffer instead of trusting
   getGhostText's show()-time state. If the suggestion no longer
   prefixes the live buffer, hide without writing. Ctrl-→ additionally
   resyncs ghost.show() to the live buffer before picking the next word
   so getNextWord operates on an up-to-date tail.

* fix(autocomplete): defer ghost text updates to the next xterm render

The previous pass made adjustToInput re-show the ghost synchronously on
every keystroke, but xterm hasn't echoed the triggering char yet at
that moment — cursorX is still the pre-keystroke position. Painting
the shrunken tail there left it visibly overlapping with the char
xterm was about to draw, and the ghost only snapped to the right
column on the next onRender tick. That one-frame overlap is the
"jitter" the reporter still saw.

Switch adjustToInput to a defer-and-reapply pattern:

- On every keystroke that should re-align the ghost, stash the desired
  input in pendingInput and hide the element immediately. The
  transient blank frame is preferable to an overlap glyph.
- The existing term.onRender listener now checks for a pending update
  first: by that tick xterm has processed the echo, cursorX has
  advanced, and we can paint the new tail at the correct column via
  applyInputUpdate.
- New isActive() exposes "has a live suggestion even if hidden waiting
  for render" so a fast "type + →" / "type + Ctrl-→" sequence in the
  hide-until-render gap still hits the accept branch and grabs the
  recomputed tail from the live buffer.

show() and hide() clear pendingInput so an explicit state change
supersedes any queued adjust.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): restore ghost text, predict-anchor-shift on each keystroke

The previous refactor broke inline completion entirely:

1. useTerminalAutocomplete force-disabled showGhostText whenever
   showPopupMenu was on — and both are true by default, so ghost
   never rendered.
2. GhostTextAddon put its overlay container *under* xterm's screen
   via insertBefore + no z-index. xterm's default renderer paints
   theme.background across every cell including empty ones, so the
   ghost was fully occluded by the canvas even when the hook *did*
   call show().

Fixes both issues and lands the correct per-keystroke strategy the
jitter report was asking for:

- Drop the showGhostText-vs-showPopupMenu gate; respect user settings.
- Put the ghost container back on top of the screen (appendChild +
  z-index 1).
- Track anchorInputLength at show() time. adjustToInput now advances
  the ghost's left by (newInput.length - anchorInputLength) cells
  *synchronously* — i.e. it predicts where xterm's cursor will land
  once the echo arrives, instead of re-reading the live cursorX that
  hasn't advanced yet. textContent is trimmed in the same call, so
  ghost + real-input stay aligned across SSH echo latency with no
  one-frame overlap or blank gap.
- Updated GhostTextAddon.test.ts expectations for the new behavior
  (and cast the fake-document through unknown to fix the pre-existing
  TS error).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): address ghost text review feedback

Follow-ups on the predict-anchor-shift from the previous commit,
based on a code-reviewer pass:

- Backspace / Ctrl-W de-sync: updatePosition's Math.max(0, ...) was
  clamping the delta to zero when newInput shrank below the show-time
  input length. The ghost then stayed pinned at the original anchor
  column while the real cursor walked back left, leaving a gap
  between the cursor and the ghost. Let the delta go negative so the
  ghost tracks the cursor backwards; clamp the resulting left at 0
  instead of clamping the delta.
- Resize staleness: onResize now also resets lastLeft/lastTop and
  re-renders, so the dedup cache in updatePosition doesn't hide a
  now-stale pixel coordinate after xterm recomputes cell dims.
- Added a regression test for the backspace path covering both the
  step-back-below-anchor case and the clamp-at-0-on-overshoot case.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): don't accept whole suggestion when buffer is unreliable

Codex flagged (#815 P1 ×2) that the live-buffer recompute on → and
Ctrl-→ falls into a degenerate path when typedBufferReliableRef is
false. My previous cut used live = "" as the fallback, but
fullSuggestion.startsWith("") is always true — so:

- → would write the entire suggestion over whatever is on the line
  (post history-recall ↑, Ctrl-R reverse search, etc.).
- Ctrl-→ would reanchor the ghost at the start and getNextWord would
  hand back the first token, duplicating leading content on top of
  the recalled command.

When the buffer is unreliable, empty buffer ≠ empty line — the line
has content we're not tracking. Fall back to the ghost's own cached
state instead of recomputing:

- → reliable: recompute tail vs live buffer, flip buffer to the
  accepted suggestion, reliability back on.
- → unreliable: use ghost.getGhostText() (shown-at-show-time tail)
  and don't touch the buffer/reliability flag.
- Ctrl-→ reliable: resync ghost to live, then proceed as before.
- Ctrl-→ unreliable: skip the resync, derive the shrink baseline from
  fullSuggestion - current-ghost-tail so the next-word logic still
  works off whatever the ghost was actually showing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): hide ghost on single-byte cursor/recall control chars

Reviewer caught that Ctrl-P / Ctrl-N / Ctrl-R / Ctrl-A / Ctrl-E and
friends flip typedBufferReliableRef to false but don't hide the
ghost — leaving it rendering a tail tied to the pre-recall line. The
previous commit's unreliable-→ fallback then reads that stale tail
via ghost.getGhostText() and writes it onto the recalled line,
reproducing the very duplication class the fallback was meant to
prevent (just triggered by Ctrl-P instead of ↑).

Mirror what the escape-sequence branch already does: clearState() +
return. Once the ghost is hidden, ghost.isActive() is false at the →
and Ctrl-→ gates, so the accept-path doesn't fire at all until a
fresh fetchSuggestions re-anchors it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): drop accepted-command cache on cursor/recall keys

Reviewer pointed out that the early returns in the single-byte
ctrl-char and escape-sequence branches leave lastAcceptedCommandRef
untouched. If the user accepts a suggestion via → and then immediately
hits Ctrl-R or ↑ to pick a different command, the fast Enter path
(lines ~611-612) still reads the cached accepted command and records
it — logging the old suggestion instead of whichever command the
reverse-search or history-recall actually ran.

Null lastAcceptedCommandRef at the top of both branches (same place
we hide the ghost and flip reliability off) so accept + recall + Enter
records the recalled command, not the stale accept.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): also null accepted-command cache on Ctrl-C / Ctrl-U

Reviewer flagged this class of bug is still reachable via Ctrl-C /
Ctrl-U. The branch handling those kills the zle line, but the early
return leaves lastAcceptedCommandRef pointing at a command that is
no longer on the line: accept "git status" via → → Ctrl-C to abandon
→ type "ls" → Enter logs "git status" via the fast path instead of
"ls".

Same one-liner as the other early-return branches: null the cache
alongside clearState(). Now the cache's lifetime truly ends at any
event that invalidates the accept.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): null accepted-command cache on bracketed paste too

Fifth-pass reviewer caught the last symmetric gap: the bracketed-paste
branch appends pasted bytes to the buffer but leaves lastAcceptedCommandRef
set. Accept "git status" via → then bracketed-paste " --short" (no
embedded newline), press Enter — the fast path at line 611 still reads
"git status" and logs that instead of "git status --short".

Mirror the non-bracketed paste branch: null the cache before clearState()
returns. All handleInput paths that extend or invalidate the line now
consistently end the cache's lifetime.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): predict ghost column by cell width + wrap at EOL

Review caught two geometry bugs in GhostTextAddon.updatePosition that
only surfaced outside the ASCII happy path:

- CJK / fullwidth / emoji glyphs occupy two xterm cells but the
  predictor advanced by one char-length per code unit, so ghost
  drifted one cell left for every wide char typed and visibly
  overlapped the user's glyph.
- When the predicted column crossed term.cols the real cursor wrapped
  to the next row, but the predictor just piled more pixels onto
  `left` — ghost walked off the right edge instead of following
  onto the next line.

Fix both by switching from code-unit count to a small EAW-style
width classifier, then applying row wrapping via
  col = (anchorX + cellDelta) % cols
  rowOffset = Math.floor((anchorX + cellDelta) / cols)
against the current term.cols. Fake terminal in the test suite now
exposes cols/rows so the unit tests can exercise both invariants:

- "advances the anchor by two cells when a CJK glyph is typed"
- "wraps the ghost to the next row when the predicted column crosses cols"

Known limitation the review already flagged: on backspace-after-wide
we don't have per-grapheme widths to reverse exactly, so the negative
delta falls back to code-unit width on the deleted slice. The slice
is `currentSuggestion[currentInput.length..anchorInputLength]` which
is the same text the user would have typed, so it's correct when
only ASCII edits; wide-char backspace can still drift by one cell.
Fixing this cleanly needs a per-grapheme buffer and is out of scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): honor showGhostText toggle while a ghost is on screen

Codex flagged (#815 P2) that fetchSuggestions gates new ghost shows
on settingsRef.current.showGhostText, but handleInput's adjustToInput
call had no such guard. A ghost that was already active at the moment
the user turned showGhostText off would keep tracking the typed
buffer via adjustToInput on every keystroke, so the "disabled" setting
only took hold after some unrelated path called clearState().

Two-part fix:

- Add a useEffect watching settings.showGhostText. When it flips false,
  hide the active ghost immediately so the disabled setting applies to
  whatever was already on screen.
- Gate the adjustToInput call in handleInput behind
  settingsRef.current.showGhostText too, so subsequent keystrokes under
  the disabled setting don't try to move or re-show a ghost.

Codex's earlier P2 about wrap-at-EOL on line 236 is already resolved
by e61f0e8b (predict-column-with-wrap + CJK width); that comment is
against an older commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): self-heal stale anchor + handle backward-wrap on delete

Codex flagged two real geometry gaps in the predict-anchor-shift math:

1. Stale anchor on high-latency shells. show() captures cursorX from
   xterm at debounce-fire time, but under SSH round-trip latency the
   user's latest keystroke may not have echoed yet — cursorX is still
   the pre-echo column. With updatePosition now purely anchor-based
   (no longer reading live cursorX on every render), that stale anchor
   becomes frozen; the ghost stays one-plus cells off for the whole
   suggestion session until another show() rebuilds it.
2. Backspace crossing a wrapped row boundary. Math.max(0, ...) clamped
   targetCol at zero, so deletions past column 0 stayed pinned to the
   current row instead of wrapping back to the previous row — exactly
   the symmetric case the forward wrap added in e61f0e8b handles.

Fixes:

- Self-heal in updatePosition: while no adjustToInput has moved us
  from the show-time baseline (currentInput.length === anchorInputLength),
  re-read live cursorX/Y each render tick. Once the user starts typing
  the anchor is frozen and delta math takes over.
- Normalize the wrap for negative targetCol: `col = targetCol % cols`
  plus `if (col < 0) col += cols`, `rowOffset = Math.floor(targetCol/cols)`
  naturally yielding -1 on underflow. Clamp `top` at row 0 so a
  runaway negative doesn't render above the terminal.

Two new tests cover both invariants:
- "self-heals a stale anchor on render while no adjustToInput has fired"
- "wraps the ghost to the previous row when deletion crosses a row boundary"

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(autocomplete): restore ghost/popup mutual-exclusivity guard in hook

Codex flagged (#815 P2) that dropping the popup-wins-over-ghost
normalization inside useTerminalAutocomplete weakens the hook's own
defensive invariant. The repo enforces mutual exclusivity in two
places already — SettingsTerminalTab toggles one off when the other
turns on, and domain/models.ts normalizes stored settings so
autocompletePopupMenu === true forces autocompleteGhostText to false
— so on the normal Terminal.tsx → store path only one of the two
arrives as true. But the hook's own defaults (DEFAULT_AUTOCOMPLETE_SETTINGS)
have both flags true, and any caller that builds settings directly
from those defaults (tests, future embedders) would end up rendering
popup + inline ghost simultaneously against the repo-wide contract.

Restore the guard, comment it as defensive rather than load-bearing
so future readers don't mistake it for the hiding-invisible-ghost
bug I was fixing last time (that was really the insertBefore /
z-index issue in GhostTextAddon.ts, not this normalization).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 02:06:26 +08:00

1364 lines
53 KiB
TypeScript

/**
* React hook for terminal autocomplete.
* Orchestrates:
* - Prompt detection
* - Ghost text addon
* - Popup menu state
* - Keyboard interaction (→ accept, Tab toggle popup, ↑↓ navigate, Esc close)
* - Input debouncing
*/
import { startTransition, useCallback, useEffect, useRef, useState, type RefObject } from "react";
import type { Terminal as XTerm } from "@xterm/xterm";
import { GhostTextAddon } from "./GhostTextAddon";
import { getAlignedPrompt, type PromptDetectionResult } from "./promptDetector";
import { getCompletions, parseCommandLine, type CompletionSuggestion } from "./completionEngine";
import { recordCommand } from "./commandHistoryStore";
import { shellEscape } from "./completionEngine";
import { preloadCommonSpecs } from "./figSpecLoader";
import { getXTermCellDimensions } from "./xtermUtils";
import { listDirectoryEntries, normalizePathTokenForLookup } from "./remotePathCompleter";
import { decideGhostSuggestion } from "./ghostSuggestionPolicy";
export interface AutocompleteSettings {
enabled: boolean;
showGhostText: boolean;
showPopupMenu: boolean;
debounceMs: number;
minChars: number;
maxSuggestions: number;
/** Typing speed threshold — suppress suggestions when typing faster than this (ms between keystrokes) */
fastTypingThresholdMs: number;
}
export const DEFAULT_AUTOCOMPLETE_SETTINGS: AutocompleteSettings = {
enabled: true,
showGhostText: true,
showPopupMenu: true,
debounceMs: 100,
minChars: 1,
maxSuggestions: 8,
fastTypingThresholdMs: 40,
};
/** Shared empty state to avoid creating new objects on every reset */
const EMPTY_STATE: AutocompleteState = Object.freeze({
suggestions: [],
selectedIndex: -1,
popupVisible: false,
popupPosition: { x: 0, y: 0 },
popupCursorLineTop: 0,
popupCursorLineBottom: 0,
expandUpward: false,
subDirPanels: [],
subDirFocusLevel: -1,
});
export interface SubDirEntry {
name: string;
type: "file" | "directory" | "symlink";
}
export interface SubDirPanel {
entries: SubDirEntry[];
selectedIndex: number;
/** The absolute directory path this panel lists */
dirPath: string;
}
export interface AutocompleteState {
suggestions: CompletionSuggestion[];
selectedIndex: number;
popupVisible: boolean;
popupPosition: { x: number; y: number };
popupCursorLineTop: number;
popupCursorLineBottom: number;
expandUpward: boolean;
/** Stack of sub-directory panels (cascading: panel 0 → panel 1 → ...) */
subDirPanels: SubDirPanel[];
/** Which level has focus: -1 = main panel, 0+ = sub-dir panel index */
subDirFocusLevel: number;
}
interface UseTerminalAutocompleteOptions {
termRef: RefObject<XTerm | null>;
sessionId: string;
hostId: string;
hostOs: "linux" | "windows" | "macos";
settings?: Partial<AutocompleteSettings>;
/** Callback to write text to the terminal session — replaces CustomEvent */
onAcceptText?: (text: string) => void;
/** Connection protocol for path completion routing */
protocol?: string;
/** Get current working directory (from OSC 7 or other source) */
getCwd?: () => string | undefined;
}
export interface TerminalAutocompleteHandle {
state: AutocompleteState;
ghostTextAddon: GhostTextAddon | null;
handleInput: (data: string) => void;
handleKeyEvent: (e: KeyboardEvent) => boolean;
selectSuggestion: (suggestion: CompletionSuggestion) => void;
repositionPopup: () => void;
closePopup: () => void;
dispose: () => void;
}
export function useTerminalAutocomplete(
options: UseTerminalAutocompleteOptions,
): TerminalAutocompleteHandle {
const { termRef, sessionId, hostId, hostOs, settings: userSettings, onAcceptText, protocol, getCwd } = options;
const rawSettings: AutocompleteSettings = {
...DEFAULT_AUTOCOMPLETE_SETTINGS,
...userSettings,
};
// Mutual-exclusivity guard matching the repo-wide contract:
// - SettingsTerminalTab toggles one off when the other is enabled.
// - domain/models.ts normalizes stored settings so popup wins.
// Keep the guard here too so callers that pass DEFAULT_AUTOCOMPLETE_SETTINGS
// directly (e.g. tests or future embedders) don't end up rendering both
// systems at once. In the normal Terminal.tsx → store path only one of
// the two arrives as true, so this is defensive, not load-bearing.
const settings: AutocompleteSettings = {
...rawSettings,
showGhostText: rawSettings.showPopupMenu ? false : rawSettings.showGhostText,
};
// Use refs for values accessed in callbacks to avoid stale closures
const settingsRef = useRef(settings);
settingsRef.current = settings;
const onAcceptTextRef = useRef(onAcceptText);
onAcceptTextRef.current = onAcceptText;
const hostIdRef = useRef(hostId);
hostIdRef.current = hostId;
const hostOsRef = useRef(hostOs);
hostOsRef.current = hostOs;
const sessionIdRef = useRef(sessionId);
sessionIdRef.current = sessionId;
const protocolRef = useRef(protocol);
protocolRef.current = protocol;
const getCwdRef = useRef(getCwd);
getCwdRef.current = getCwd;
const [state, setState] = useState<AutocompleteState>(EMPTY_STATE);
const ghostAddonRef = useRef<GhostTextAddon | null>(null);
const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const lastKeystrokeRef = useRef<number>(0);
const lastPromptRef = useRef<PromptDetectionResult | null>(null);
const disposedRef = useRef(false);
const stateRef = useRef(state);
stateRef.current = state;
/** Flag to suppress handleInput's Enter recording when selectAndExecute already did it */
const suppressNextEnterRecordRef = useRef(false);
/** Monotonic counter to invalidate stale async completion results */
const fetchVersionRef = useRef(0);
/** Last accepted suggestion text — for accurate history recording on fast Enter after accept */
const lastAcceptedCommandRef = useRef<string | null>(null);
/** Monotonic counter to invalidate stale async sub-dir fetches */
const subDirFetchVersionRef = useRef(0);
/**
* Keystroke buffer mirroring what the user has typed since the last
* prompt boundary (Enter / Ctrl-C / Ctrl-U / cursor movement).
*
* detectPrompt parses the xterm buffer and can misattribute theme
* content — e.g. oh-my-zsh robbyrussell's "➜ ~ " — as user input.
* Keeping an independent keystroke log lets getAlignedPrompt snap the
* detected userInput back to what was actually typed (and only when
* the buffer matches the live line's tail), which in turn keeps
* history recording and Tab insertion honest (#806).
*/
const typedInputBufferRef = useRef<string>("");
/**
* Whether typedInputBufferRef can be trusted as the full tail of the
* current command line. Cleared after any event this append-only buffer
* can't follow (history recall via ↑/Ctrl-P, cursor moves, reverse
* search, etc.). Reset to true on clean line boundaries — Enter,
* Ctrl-C, Ctrl-U — and after we explicitly re-align via
* insertSuggestion or a ghost-text accept.
*
* Without this flag, an Up-arrow-recall workflow would leave the buffer
* holding only the post-navigation suffix, and Enter would record that
* suffix as a command (pollutes history, misleads future completions).
*/
const typedBufferReliableRef = useRef<boolean>(true);
// Preload common specs on first mount (only if enabled)
useEffect(() => {
if (settings.enabled) {
preloadCommonSpecs();
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
// Initialize ghost text addon — poll for termRef since it's set after xterm runtime creation
// Also clears popup/ghost when autocomplete is disabled at runtime
useEffect(() => {
if (!settings.enabled) {
// Clear any visible popup/ghost when disabled
clearState();
return;
}
let addon: GhostTextAddon | null = null;
let pollTimer: ReturnType<typeof setTimeout> | null = null;
let cancelled = false;
const tryActivate = () => {
const term = termRef.current;
if (!term || cancelled) return;
addon = new GhostTextAddon();
addon.activate(term);
ghostAddonRef.current = addon;
};
// termRef may not be set yet on first render — poll briefly
if (termRef.current) {
tryActivate();
} else {
const poll = () => {
if (cancelled) return;
if (termRef.current) {
tryActivate();
} else {
pollTimer = setTimeout(poll, 50);
}
};
pollTimer = setTimeout(poll, 50);
}
return () => {
cancelled = true;
if (pollTimer) clearTimeout(pollTimer);
addon?.dispose();
ghostAddonRef.current = null;
};
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [sessionId, settings.enabled]);
// Hide any active ghost when the user turns showGhostText off mid-
// session. The fetchSuggestions branch (~L531) already gates new
// shows on the flag, but a ghost that was already on screen at toggle
// time would otherwise keep sliding around under a disabled setting
// until something unrelated called clearState (Codex #815 P2).
useEffect(() => {
if (!settings.showGhostText) {
ghostAddonRef.current?.hide();
}
}, [settings.showGhostText]);
/**
* Write accepted text to the terminal via callback (no CustomEvent).
*/
const writeToTerminal = useCallback((text: string) => {
onAcceptTextRef.current?.(text);
}, []);
/**
* Clear popup/ghost state. Skips re-render if already empty.
*/
const clearState = useCallback(() => {
ghostAddonRef.current?.hide();
// Bump version to invalidate any in-flight async completions
fetchVersionRef.current++;
subDirFetchVersionRef.current++;
setState((prev) =>
prev.popupVisible || prev.suggestions.length > 0 ? { ...EMPTY_STATE } : prev,
);
}, []);
/** Fetch directory listing via IPC. */
const fetchDirEntries = useCallback(async (dirPath: string): Promise<SubDirEntry[]> => {
return listDirectoryEntries(dirPath, {
sessionId: sessionIdRef.current,
protocol: protocolRef.current,
foldersOnly: false,
limit: 50,
});
}, []);
/** Fetch sub-dir entries for the main panel's selected item (level 0). */
const fetchSubDirForIndex = useCallback((index: number) => {
const s = stateRef.current;
if (index < 0 || index >= s.suggestions.length) return;
const item = s.suggestions[index];
if (item.source !== "path" || item.fileType !== "directory") {
subDirFetchVersionRef.current++;
setState((prev) => prev.subDirPanels.length > 0
? { ...prev, subDirPanels: [], subDirFocusLevel: -1 }
: prev);
return;
}
const term = termRef.current;
const { prompt: livePrompt } = getAlignedPrompt(
term,
typedInputBufferRef.current,
typedBufferReliableRef.current,
);
const activePrompt = livePrompt.isAtPrompt ? livePrompt : lastPromptRef.current;
const activeWord = activePrompt?.isAtPrompt
? parseCommandLine(activePrompt.userInput).currentWord
: parseCommandLine(item.text).currentWord;
const cwd = resolveAutocompleteCwd(
activePrompt?.promptText ?? "",
activeWord,
getCwdRef.current?.(),
hostOsRef.current,
);
const dirPath = normalizePathTokenForLookup(parseCommandLine(item.text).currentWord, cwd);
if (!dirPath) return;
const requestVersion = ++subDirFetchVersionRef.current;
fetchDirEntries(dirPath).then((entries) => {
if (requestVersion !== subDirFetchVersionRef.current) return;
startTransition(() => {
setState((prev) => {
if (prev.selectedIndex !== index) return prev;
const nextPanels = entries.length > 0 ? [{ entries, selectedIndex: -1, dirPath }] : [];
if (
prev.subDirFocusLevel === -1 &&
prev.subDirPanels.length === nextPanels.length &&
areSubDirPanelsEqual(prev.subDirPanels, nextPanels)
) {
return prev;
}
return {
...prev,
subDirPanels: nextPanels,
subDirFocusLevel: -1,
};
});
});
});
}, [fetchDirEntries, termRef]);
/** Expand a directory at the given panel level → fetch contents and push new panel.
* Does NOT change focus level — use moveFocus param to override. */
const expandSubDir = useCallback((level: number, entry: SubDirEntry, moveFocus = false) => {
const s = stateRef.current;
const panel = s.subDirPanels[level];
if (!panel || entry.type !== "directory") return;
const parentPath = panel.dirPath.endsWith("/") ? panel.dirPath : panel.dirPath + "/";
const childPath = parentPath + entry.name + "/";
const requestVersion = ++subDirFetchVersionRef.current;
fetchDirEntries(childPath).then((entries) => {
if (requestVersion !== subDirFetchVersionRef.current || entries.length === 0) return;
startTransition(() => {
setState((prev) => {
const currentPanel = prev.subDirPanels[level];
if (!currentPanel || currentPanel.dirPath !== panel.dirPath) return prev;
const nextPanels = prev.subDirPanels.slice(0, level + 1);
nextPanels.push({ entries, selectedIndex: moveFocus ? 0 : -1, dirPath: childPath });
const nextFocusLevel = moveFocus ? level + 1 : prev.subDirFocusLevel;
if (
prev.subDirFocusLevel === nextFocusLevel &&
prev.subDirPanels.length === nextPanels.length &&
areSubDirPanelsEqual(prev.subDirPanels, nextPanels)
) {
return prev;
}
return {
...prev,
subDirPanels: nextPanels,
subDirFocusLevel: nextFocusLevel,
};
});
});
// When moving focus into a newly opened panel, the first item is auto-selected.
// If that first item is itself a directory, eagerly show its next level so the
// user doesn't need to move ↓↑ just to trigger the usual auto-expand behavior.
const firstEntry = moveFocus ? entries[0] : null;
if (firstEntry?.type !== "directory") return;
const nestedChildPath = `${childPath}${firstEntry.name}/`;
fetchDirEntries(nestedChildPath).then((nestedEntries) => {
if (requestVersion !== subDirFetchVersionRef.current || nestedEntries.length === 0) return;
startTransition(() => {
setState((prev) => {
const currentChildPanel = prev.subDirPanels[level + 1];
if (
!currentChildPanel ||
currentChildPanel.dirPath !== childPath ||
currentChildPanel.selectedIndex !== 0
) {
return prev;
}
const nextPanels = prev.subDirPanels.slice(0, level + 2);
nextPanels.push({ entries: nestedEntries, selectedIndex: -1, dirPath: nestedChildPath });
if (
prev.subDirPanels.length === nextPanels.length &&
areSubDirPanelsEqual(prev.subDirPanels, nextPanels)
) {
return prev;
}
return {
...prev,
subDirPanels: nextPanels,
};
});
});
});
});
}, [fetchDirEntries]);
// Ref to fetchSuggestions (avoids circular dep — defined after fetchSuggestions)
const fetchSuggestionsRef = useRef<() => void>(() => {});
const repositionPopup = useCallback(() => {
const term = termRef.current;
if (!term) return;
setState((prev) => {
if (!prev.popupVisible || prev.suggestions.length === 0) return prev;
const { position, cursorLineTop, cursorLineBottom, expandUpward } = calculatePopupPosition(term, prev.suggestions.length);
// Force a re-render even when the relative cursor cell hasn't changed.
// The terminal container may have moved in the viewport after a fit/resize.
return {
...prev,
popupPosition: position,
popupCursorLineTop: cursorLineTop,
popupCursorLineBottom: cursorLineBottom,
expandUpward,
};
});
}, [termRef]);
/** Handle selecting a file/directory from any sub-dir panel.
* Builds the full path from the panel stack and replaces the current input. */
const handleSubDirSelect = useCallback((level: number, entry: SubDirEntry) => {
const s = stateRef.current;
const term = termRef.current;
if (!term) return;
// Build the full path: panel's dirPath + entry name
const panel = s.subDirPanels[level];
if (!panel) return;
// Get current prompt to know what command prefix to keep (e.g., "cd ").
// getAlignedPrompt handles robbyrussell-style themes by trimming the
// cwd marker out of userInput when the typed buffer is aligned (#806).
const { prompt } = getAlignedPrompt(term, typedInputBufferRef.current, typedBufferReliableRef.current);
if (!prompt.isAtPrompt) return;
// Find the command part (everything before the path argument)
// e.g., userInput = "cd /usr/" → command prefix = "cd ", we replace the whole path
const parsedPrompt = parseCommandLine(prompt.userInput);
const cmdPrefix = parsedPrompt.tokens
.slice(0, parsedPrompt.wordIndex)
.join(" ") + (parsedPrompt.wordIndex > 0 ? " " : "");
const currentToken = parsedPrompt.currentWord;
const quotePrefix = currentToken.startsWith('"') || currentToken.startsWith("'")
? currentToken[0]
: "";
const quoteSuffix = quotePrefix && currentToken.endsWith(quotePrefix) ? quotePrefix : "";
const suffix = entry.type === "directory" ? "/" : "";
const entryName = quotePrefix || !/[\\$'"|!<>;#~` ]/.test(entry.name)
? entry.name
: shellEscape(entry.name);
const fullPath = panel.dirPath + entryName + suffix;
const replacementPath = `${quotePrefix}${fullPath}${quoteSuffix}`;
// Clear current input and write: cmdPrefix + fullPath
const isWindows = hostOsRef.current === "windows";
const clearSeq = isWindows
? "\b".repeat(prompt.userInput.length)
: "\x15";
const newCommand = cmdPrefix + replacementPath;
writeToTerminal(clearSeq + newCommand);
// Sub-dir selection rewrote the whole command line; re-align the
// keystroke buffer so the next Enter records the executed command
// instead of whatever partial input we had before (P2 from #814).
typedInputBufferRef.current = newCommand;
typedBufferReliableRef.current = true;
clearState();
if (entry.type === "directory") {
setTimeout(() => fetchSuggestionsRef.current(), 50);
}
}, [writeToTerminal, clearState, termRef]);
/**
* Fetch and display suggestions based on current input.
* Single query path for both ghost text and popup (no duplicate queries).
*/
const fetchSuggestions = useCallback(async () => {
const term = termRef.current;
if (!term || disposedRef.current || !settingsRef.current.enabled) {
return;
}
// Capture version at start — if it changes during async work, discard results
const version = ++fetchVersionRef.current;
const { prompt } = getAlignedPrompt(term, typedInputBufferRef.current, typedBufferReliableRef.current);
lastPromptRef.current = prompt;
if (!prompt.isAtPrompt || prompt.userInput.length < settingsRef.current.minChars) {
clearState();
return;
}
// Suppress autocomplete when cursor is not at end of input —
// inserting text mid-line would corrupt the command (e.g., "git st|tus" → "git statustus")
const buffer = term.buffer.active;
const lineAfterCursor = buffer.getLine(buffer.cursorY + buffer.baseY)
?.translateToString(false).substring(buffer.cursorX).trimEnd();
if (lineAfterCursor && lineAfterCursor.length > 0) {
clearState();
return;
}
const input = prompt.userInput;
const parsedInput = parseCommandLine(input);
const cwd = resolveAutocompleteCwd(
prompt.promptText,
parsedInput.currentWord,
getCwdRef.current?.(),
hostOsRef.current,
);
// Single query for both ghost text and popup
const completions = await getCompletions(input, {
hostId: hostIdRef.current,
os: hostOsRef.current,
maxResults: settingsRef.current.maxSuggestions,
sessionId: sessionIdRef.current,
protocol: protocolRef.current,
cwd,
});
if (disposedRef.current || version !== fetchVersionRef.current) return;
// Discard stale results: if the user kept typing while getCompletions was running,
// the current prompt input will have changed. Re-detect and compare.
const { prompt: currentPrompt } = getAlignedPrompt(term, typedInputBufferRef.current, typedBufferReliableRef.current);
if (!currentPrompt.isAtPrompt || currentPrompt.userInput !== input) {
return; // Input changed — these completions are stale
}
// Ghost text: keep the active prediction stable while the user's
// input still fits within it. Only swap to a fresh prediction once
// the current one no longer matches the typed prefix.
if (settingsRef.current.showGhostText) {
const ghost = ghostAddonRef.current;
const activeSuggestion = ghost?.isActive() ? ghost.getSuggestion() : null;
const nextSuggestion = completions.length > 0 ? completions[0].text : null;
const ghostDecision = decideGhostSuggestion(activeSuggestion, input, nextSuggestion);
if (ghostDecision.type === "show") {
ghost?.show(ghostDecision.suggestion, input);
} else if (ghostDecision.type === "hide") {
ghost?.hide();
}
}
// Popup
if (settingsRef.current.showPopupMenu && completions.length > 0) {
const { position, cursorLineTop, cursorLineBottom, expandUpward } = calculatePopupPosition(term, completions.length);
startTransition(() => {
setState((prev) => {
const nextState: AutocompleteState = {
suggestions: completions,
selectedIndex: -1,
popupVisible: true,
popupPosition: position,
popupCursorLineTop: cursorLineTop,
popupCursorLineBottom: cursorLineBottom,
expandUpward,
subDirPanels: [],
subDirFocusLevel: -1,
};
if (
prev.popupVisible &&
prev.selectedIndex === nextState.selectedIndex &&
prev.expandUpward === nextState.expandUpward &&
prev.popupPosition.x === nextState.popupPosition.x &&
prev.popupPosition.y === nextState.popupPosition.y &&
prev.popupCursorLineTop === nextState.popupCursorLineTop &&
prev.popupCursorLineBottom === nextState.popupCursorLineBottom &&
prev.subDirFocusLevel === -1 &&
prev.subDirPanels.length === 0 &&
areSuggestionsEqual(prev.suggestions, nextState.suggestions)
) {
return prev;
}
return nextState;
});
});
} else {
startTransition(() => {
setState((prev) =>
prev.popupVisible || prev.suggestions.length > 0
? { ...EMPTY_STATE }
: prev,
);
});
}
}, [termRef, clearState]);
// Keep ref in sync so handleSubDirSelect can call it
fetchSuggestionsRef.current = fetchSuggestions;
/**
* Handle terminal input data. Called on every character.
*/
const handleInput = useCallback(
(data: string) => {
if (!settingsRef.current.enabled) return;
const now = Date.now();
const timeSinceLastKeystroke = now - lastKeystrokeRef.current;
lastKeystrokeRef.current = now;
// Command recording: Enter key
if (data === "\r" || data === "\n") {
// Skip recording if selectAndExecute already recorded this command
if (suppressNextEnterRecordRef.current) {
suppressNextEnterRecordRef.current = false;
} else {
// If user accepted a completion (Tab/→) and immediately pressed Enter,
// the buffer may not reflect the accepted text yet. Use the tracked value.
if (lastAcceptedCommandRef.current) {
recordCommand(lastAcceptedCommandRef.current, hostIdRef.current, hostOsRef.current);
} else {
// Require a live prompt before trusting either keystroke buffer
// or buffer-based detection — otherwise sudo password Enter
// would record the typed password as a command.
const { prompt: livePrompt, alignedTyped } = getAlignedPrompt(
termRef.current,
typedInputBufferRef.current,
typedBufferReliableRef.current,
);
if (livePrompt.isAtPrompt) {
// alignedTyped is only non-null when the buffer is reliable
// AND matches the live line's tail — that single signal
// covers both the robbyrussell "~ " case (#806) and the
// stale-buffer cases from out-of-band pastes / history
// recall (#814 P1/P2). When it's null we fall back to the
// reconciled livePrompt.userInput, which for paste-bypass
// scenarios lands on pre-PR behavior (no regression).
if (alignedTyped && alignedTyped.trim()) {
recordCommand(alignedTyped.trim(), hostIdRef.current, hostOsRef.current);
} else if (livePrompt.userInput.trim()) {
recordCommand(livePrompt.userInput.trim(), hostIdRef.current, hostOsRef.current);
}
} else if (lastPromptRef.current?.isAtPrompt && lastPromptRef.current.userInput.trim()) {
// Only fall back to the cached prompt when we have no live
// reading at all — guards against recording during interactive
// prompts where detectPrompt correctly bails out.
recordCommand(lastPromptRef.current.userInput.trim(), hostIdRef.current, hostOsRef.current);
}
}
lastAcceptedCommandRef.current = null;
}
typedInputBufferRef.current = "";
typedBufferReliableRef.current = true;
clearState();
return;
}
// Ctrl+C, Ctrl+U — clear. These kill the zle line entirely, so the
// buffer is once again a true reflection of the (empty) line.
if (data === "\x03" || data === "\x15") {
typedInputBufferRef.current = "";
typedBufferReliableRef.current = true;
// Same rationale as the ctrl/escape early returns below: any
// previously-accepted suggestion is gone from the line too, so
// accept → Ctrl-C → type "foo" → Enter must not log the stale
// accepted command via the Enter fast path.
lastAcceptedCommandRef.current = null;
clearState();
return;
}
// Backspace / DEL: drop the last typed char so the buffer stays aligned
// with what the shell actually holds.
if (data === "\x7f" || data === "\b") {
typedInputBufferRef.current = typedInputBufferRef.current.slice(0, -1);
} else if (data === "\x17") {
// Ctrl+W: word-erase — kill the trailing whitespace + word.
typedInputBufferRef.current = typedInputBufferRef.current.replace(/\s*\S+\s*$/, "");
} else if (data.startsWith("\x1b[200~")) {
// Bracketed paste: "\x1b[200~...\x1b[201~". The inner bytes are
// literal input, so newlines stay on the zle line instead of
// executing each segment — meaning we must preserve the whole
// content in the buffer, not just the post-final-newline tail
// (Codex #814 P2).
//
// Reliability is *inherited*, not reset: if the buffer was
// already aligned with the line (reliable=true), appending this
// paste keeps it aligned; if the buffer was unreliable (e.g.
// after ↑ recalled a history command so line ≠ buffer), the
// paste only extends the tail but the head is still whatever
// the shell had, so the buffer stays unreliable. Without this,
// a paste-after-recall flow would flip reliability back on and
// Enter would record just the pasted suffix as the command
// (Codex #814 P1 follow-up).
const endIdx = data.indexOf("\x1b[201~");
const content = endIdx >= 0
? data.slice("\x1b[200~".length, endIdx)
: data.slice("\x1b[200~".length);
typedInputBufferRef.current += content;
// Paste extends the line past whatever was accepted, so the
// Enter fast-path must not record the pre-paste accepted
// command — mirrors the non-bracketed paste branch below.
lastAcceptedCommandRef.current = null;
clearState();
return;
} else if (data.startsWith("\x1b") && data !== "\x1b") {
// Cursor-movement / function keys — we lose track of where the
// cursor sits relative to our append-only buffer. Mark the
// buffer unreliable and drop it; detectPrompt takes over until
// the next Enter / Ctrl-C / Ctrl-U.
typedInputBufferRef.current = "";
typedBufferReliableRef.current = false;
} else if (data.length === 1 && data.charCodeAt(0) >= 32) {
typedInputBufferRef.current += data;
} else if (data.length > 1 && !data.startsWith("\x1b")) {
// Paste chunk. Any \r / \n inside executes the preceding text as
// a command in the shell, so keeping the pre-newline portion in
// our buffer would leave stale content that a later Enter could
// record (Codex #814 P2). Drop everything up to and including
// the last terminator and keep only the tail as new content.
// Intermediate executed lines aren't synthesized back into
// recordCommand here — the onCommandExecuted path in
// createXTermRuntime still captures them independently.
const lastCR = data.lastIndexOf("\r");
const lastLF = data.lastIndexOf("\n");
const nlIdx = Math.max(lastCR, lastLF);
if (nlIdx >= 0) {
typedInputBufferRef.current = data.slice(nlIdx + 1);
typedBufferReliableRef.current = true;
// The embedded newline flushed any previously-accepted
// suggestion too — clearing the cache here prevents the next
// Enter from falling into the lastAcceptedCommandRef fast path
// and recording that stale command.
lastAcceptedCommandRef.current = null;
clearState();
return;
}
typedInputBufferRef.current += data;
} else if (data.length === 1 && data.charCodeAt(0) < 32) {
// Any other single control char (Ctrl-A, Ctrl-E, Ctrl-B, Ctrl-F,
// Ctrl-R, Ctrl-P, Ctrl-N, ...) moves the cursor or swaps the
// line in ways this append-only buffer can't follow. Same story
// as escape sequences above — and hide the ghost too, so the
// unreliable-accept fallback doesn't pull a stale tail onto a
// recalled line (Codex #815 follow-up).
typedInputBufferRef.current = "";
typedBufferReliableRef.current = false;
// Null the fast-path accepted-command cache: accept-then-Ctrl-R
// should not let an old accepted command sneak back in via the
// Enter fast path after reverse-search picks a different one.
lastAcceptedCommandRef.current = null;
clearState();
return;
}
// Escape sequences (arrow keys, Home, End, etc.): clear stale suggestions
// since cursor position may have changed, making current suggestions invalid.
// Up/Down/Right/Tab are handled by handleKeyEvent; other sequences land here.
if (data.startsWith("\x1b") && data !== "\x1b") {
// Same fast-path reset as the single-byte ctrl-char branch above —
// accept-then-↑/↓ must not record the stale accepted command if
// the user then presses Enter on a different recalled line.
lastAcceptedCommandRef.current = null;
clearState();
return;
}
// User is typing more — invalidate accepted command fallback since the
// command is being edited further (e.g., accepted "git status" then added " --short")
lastAcceptedCommandRef.current = null;
// Re-align any visible ghost text to the freshly-updated buffer
// immediately. Without this the ghost keeps the tail it captured at
// show() time; a fast "type + press →" sequence then pastes the
// pre-update tail on top of the new input ("doc" + "cker ls" →
// "doccker ls"). Only safe to call when the buffer is reliable —
// otherwise its content doesn't correspond to the live line and
// adjustToInput would make the ghost lie. Also skip when the user
// has turned showGhostText off mid-session: otherwise a ghost that
// was active before the toggle would keep moving around under a
// setting the user just said to disable (Codex #815 P2).
if (typedBufferReliableRef.current && settingsRef.current.showGhostText) {
ghostAddonRef.current?.adjustToInput(typedInputBufferRef.current);
}
// Fast typing suppression: if typing faster than threshold, skip this debounce cycle
const isFastTyping = timeSinceLastKeystroke < settingsRef.current.fastTypingThresholdMs;
// Debounced suggestion fetch
if (debounceTimerRef.current) {
clearTimeout(debounceTimerRef.current);
}
if (isFastTyping) {
// Still debounce, but with a longer delay to wait for typing to pause
debounceTimerRef.current = setTimeout(() => {
fetchSuggestions();
}, settingsRef.current.debounceMs * 3);
} else {
debounceTimerRef.current = setTimeout(() => {
fetchSuggestions();
}, settingsRef.current.debounceMs);
}
},
[fetchSuggestions, termRef, clearState],
);
/**
* Handle keyboard events for autocomplete interaction.
* Returns false if the event was consumed (should not propagate to terminal).
*/
const handleKeyEvent = useCallback(
(e: KeyboardEvent): boolean => {
if (!settingsRef.current.enabled || e.type !== "keydown") return true;
const s = stateRef.current;
const ghost = ghostAddonRef.current;
// Right arrow: if popup has selected directory with sub-dir panel, enter it
// Skip this handler entirely when sub-dir panels are focused — let the
// sub-panel navigation block handle → for deeper expansion.
if (e.key === "ArrowRight" && !e.ctrlKey && !e.metaKey && !e.altKey && !e.shiftKey && s.subDirFocusLevel < 0) {
if (s.popupVisible && s.selectedIndex >= 0 && s.subDirPanels.length > 0) {
const selected = s.suggestions[s.selectedIndex];
if (selected?.fileType === "directory") {
e.preventDefault();
const firstEntry = s.subDirPanels[0]?.entries[0];
setState((prev) => {
const panels = [...prev.subDirPanels];
if (panels[0]) panels[0] = { ...panels[0], selectedIndex: 0 };
return { ...prev, subDirPanels: panels, subDirFocusLevel: 0 };
});
if (firstEntry?.type === "directory") {
expandSubDir(0, firstEntry, false);
}
return false;
}
}
// Otherwise: accept ghost text. Use isActive(), not isVisible(),
// so a fast "type + →" that lands in the hide-until-render gap
// still hits this branch and accepts the pending ghost.
if (ghost?.isActive()) {
e.preventDefault();
const fullSuggestion = ghost.getSuggestion();
// When the keystroke buffer is reliable, recompute the tail
// against the *live* buffer so a fast "type + →" in the
// hide-until-render gap still writes the correct tail. When
// it's not reliable (post history-recall / Ctrl-R), we can't
// treat empty buffer as "nothing typed" — the line actually
// has content we're not tracking — so fall back to the
// ghost's own cached tail instead of writing the entire
// suggestion onto an already-populated line.
let ghostText: string;
let newBuffer: string | null;
if (typedBufferReliableRef.current) {
const live = typedInputBufferRef.current;
if (fullSuggestion && fullSuggestion.startsWith(live)) {
ghostText = fullSuggestion.substring(live.length);
newBuffer = fullSuggestion;
} else {
ghostText = "";
newBuffer = null;
}
} else {
ghostText = ghost.getGhostText();
newBuffer = null; // buffer is unreliable; don't flip it back on
}
if (ghostText) {
writeToTerminal(ghostText);
lastAcceptedCommandRef.current = fullSuggestion;
if (newBuffer !== null) {
typedInputBufferRef.current = newBuffer;
typedBufferReliableRef.current = true;
}
ghost.hide();
clearState();
} else {
ghost.hide();
}
return false;
}
}
// Ctrl+Right / Alt+Right (Mac): accept next word
if (e.key === "ArrowRight" && (e.ctrlKey || e.altKey) && !e.metaKey && !e.shiftKey) {
if (ghost?.isActive()) {
e.preventDefault();
const fullSuggestion = ghost.getSuggestion();
if (!fullSuggestion) {
ghost.hide();
return false;
}
// Determine the baseline the next word should extend. Reliable
// buffer: resync the ghost to the live buffer so getNextWord
// operates on the up-to-date tail. Unreliable buffer (post
// history-recall / Ctrl-R): don't reanchor to "" — that would
// make getNextWord hand back the very first word and the shell
// would duplicate leading tokens on top of the recalled line.
// Fall back to the ghost's existing cached input instead.
if (typedBufferReliableRef.current) {
const live = typedInputBufferRef.current;
if (fullSuggestion.startsWith(live)) {
ghost.show(fullSuggestion, live);
} else {
ghost.hide();
return false;
}
}
const base = ghost.getGhostText().length > 0
? fullSuggestion.substring(0, fullSuggestion.length - ghost.getGhostText().length)
: fullSuggestion;
const nextWord = ghost.getNextWord();
if (nextWord) {
writeToTerminal(nextWord);
// Only extend the buffer if it was already aligned with the
// line — otherwise we'd end up with just the appended word,
// which the next Enter would then record as the command.
if (typedBufferReliableRef.current) {
typedInputBufferRef.current += nextWord;
}
// Shrink the ghost to reflect what's left after the accept.
const newInput = base + nextWord;
if (fullSuggestion.startsWith(newInput) && fullSuggestion.length > newInput.length) {
ghost.show(fullSuggestion, newInput);
} else {
ghost.hide();
}
}
return false;
}
}
// Tab: accept selected popup suggestion. Ghost text is accepted via → only —
// letting Tab pass through lets the shell's native completion (bash/zsh) run,
// which is otherwise shadowed by our single-Tab ghost accept.
if (e.key === "Tab" && !e.ctrlKey && !e.metaKey && !e.altKey && s.subDirFocusLevel < 0) {
if (s.popupVisible && s.suggestions.length > 0) {
e.preventDefault();
const selected = s.suggestions[Math.max(0, s.selectedIndex)];
if (selected) insertSuggestion(selected, false);
return false;
}
// Hide stale ghost text before Tab reaches the shell — the shell's
// completion will rewrite the line and the old ghost would mislead.
if (ghost?.isActive()) {
ghost.hide();
}
}
// Up/Down/Left/Right: navigate popup + sub-dir panel
if (s.popupVisible && s.suggestions.length > 0) {
const focusLevel = s.subDirFocusLevel;
const focusedPanel = focusLevel >= 0 ? s.subDirPanels[focusLevel] : null;
// Sub-dir panel focused: ↑↓ navigate, ← go back, → go deeper
if (focusLevel >= 0 && focusedPanel) {
if (e.key === "ArrowUp" || e.key === "ArrowDown") {
e.preventDefault();
const newIdx = e.key === "ArrowUp"
? (focusedPanel.selectedIndex <= 0 ? focusedPanel.entries.length - 1 : focusedPanel.selectedIndex - 1)
: (focusedPanel.selectedIndex >= focusedPanel.entries.length - 1 ? 0 : focusedPanel.selectedIndex + 1);
setState((prev) => {
const panels = [...prev.subDirPanels];
const p = panels[focusLevel];
if (!p) return prev;
panels[focusLevel] = { ...p, selectedIndex: newIdx };
return { ...prev, subDirPanels: panels.slice(0, focusLevel + 1) };
});
// Auto-expand next level if the newly selected item is a directory
const newEntry = focusedPanel.entries[newIdx];
if (newEntry?.type === "directory") {
expandSubDir(focusLevel, newEntry);
}
return false;
}
if (e.key === "ArrowLeft") {
e.preventDefault();
setState((prev) => ({
...prev,
subDirPanels: prev.subDirPanels.slice(0, focusLevel + 1),
subDirFocusLevel: focusLevel - 1,
}));
return false;
}
if (e.key === "ArrowRight") {
const entry = focusedPanel.entries[focusedPanel.selectedIndex];
if (entry?.type === "directory") {
e.preventDefault();
expandSubDir(focusLevel, entry, true); // moveFocus = true
return false;
}
}
if (e.key === "Enter" || e.key === "Tab") {
const entry = focusedPanel.entries[focusedPanel.selectedIndex];
if (entry && focusedPanel.selectedIndex >= 0) {
e.preventDefault();
handleSubDirSelect(focusLevel, entry);
return false;
}
}
if (e.key === "Escape") {
e.preventDefault();
if (focusLevel > 0) {
setState((prev) => ({
...prev,
subDirPanels: prev.subDirPanels.slice(0, focusLevel),
subDirFocusLevel: focusLevel - 1,
}));
} else {
setState((prev) => ({ ...prev, subDirPanels: [], subDirFocusLevel: -1 }));
}
return false;
}
if (
e.key.length === 1 ||
e.key === "Backspace" ||
e.key === "Delete" ||
e.key === "Home" ||
e.key === "End"
) {
clearState();
}
return true;
}
// Main panel navigation
if (e.key === "ArrowUp") {
e.preventDefault();
setState((prev) => ({
...prev,
selectedIndex: prev.selectedIndex <= 0 ? prev.suggestions.length - 1 : prev.selectedIndex - 1,
subDirPanels: [], subDirFocusLevel: -1,
}));
fetchSubDirForIndex(s.selectedIndex <= 0 ? s.suggestions.length - 1 : s.selectedIndex - 1);
return false;
}
if (e.key === "ArrowDown") {
e.preventDefault();
setState((prev) => ({
...prev,
selectedIndex: prev.selectedIndex >= prev.suggestions.length - 1 ? 0 : prev.selectedIndex + 1,
subDirPanels: [], subDirFocusLevel: -1,
}));
fetchSubDirForIndex(s.selectedIndex >= s.suggestions.length - 1 ? 0 : s.selectedIndex + 1);
return false;
}
// Enter on popup
if (e.key === "Enter") {
if (s.selectedIndex >= 0) {
const selected = s.suggestions[s.selectedIndex];
if (selected) {
e.preventDefault();
insertSuggestion(selected, true);
return false;
}
}
clearState();
}
}
// Escape: close popup and hide ghost text
// Only consume Escape if popup is visible; don't block Escape for vi-mode shells
// when only ghost text is showing (ghost text is passive/non-intrusive)
if (e.key === "Escape" && s.popupVisible) {
e.preventDefault();
ghost?.hide();
clearState();
return false;
}
return true;
},
// eslint-disable-next-line react-hooks/exhaustive-deps -- insertSuggestion uses refs, stable identity
[writeToTerminal],
);
/**
* Insert a suggestion into the terminal.
* @param execute If true, also sends \r to execute the command.
*/
const insertSuggestion = useCallback(
(suggestion: CompletionSuggestion, execute: boolean) => {
const term = termRef.current;
if (!term) return;
// Always use real-time prompt detection — lastPromptRef may be stale
// if the user typed more characters after suggestions were fetched.
const { prompt } = getAlignedPrompt(term, typedInputBufferRef.current, typedBufferReliableRef.current);
if (!prompt.isAtPrompt) return;
// If suggestion starts with the current input, insert only the remaining part.
// Otherwise (fuzzy match), clear the line first and write the full suggestion.
let payload: string;
if (suggestion.text.startsWith(prompt.userInput)) {
const textToInsert = suggestion.text.substring(prompt.userInput.length);
payload = execute ? textToInsert + "\r" : textToInsert;
} else {
// Fuzzy match: clear current input, then write full command.
// Ctrl+U works on POSIX shells (bash/zsh/fish).
// On Windows (cmd.exe/PowerShell), use backspaces to erase instead.
const isWindows = hostOsRef.current === "windows";
const clearSequence = isWindows
? "\b".repeat(prompt.userInput.length) // Backspace to erase
: "\x15"; // Ctrl+U (readline kill-line)
payload = clearSequence + suggestion.text + (execute ? "\r" : "");
}
if (payload) {
writeToTerminal(payload);
}
// Keystroke buffer now reflects the accepted text (either extended by
// the insertion suffix, or wholesale replaced by the fuzzy-match path
// that emits Ctrl-U first). Re-aligning it here keeps the subsequent
// Enter-record honest, and flips reliability back on since we know
// the line content exactly.
if (execute) {
typedInputBufferRef.current = "";
} else {
typedInputBufferRef.current = suggestion.text;
}
typedBufferReliableRef.current = true;
// Track accepted command for accurate history recording on fast Enter
if (!execute) {
lastAcceptedCommandRef.current = suggestion.text;
}
// When executing, record command here and suppress the handleInput Enter recording
if (execute) {
recordCommand(suggestion.text, hostIdRef.current, hostOsRef.current);
suppressNextEnterRecordRef.current = true;
// Safety timeout: clear the flag if handleInput's Enter doesn't consume it
// (e.g., if xterm doesn't fire onData because handleKeyEvent returned false)
setTimeout(() => { suppressNextEnterRecordRef.current = false; }, 100);
}
clearState();
},
// eslint-disable-next-line react-hooks/exhaustive-deps -- clearState is stable
[termRef, writeToTerminal],
);
/**
* Select a suggestion from the popup (Tab / mouse click — insert only, no execute).
*/
const selectSuggestion = useCallback(
(suggestion: CompletionSuggestion) => {
insertSuggestion(suggestion, false);
},
[insertSuggestion],
);
const closePopup = useCallback(() => {
clearState();
}, [clearState]);
const dispose = useCallback(() => {
disposedRef.current = true;
if (debounceTimerRef.current) {
clearTimeout(debounceTimerRef.current);
}
ghostAddonRef.current?.dispose();
ghostAddonRef.current = null;
}, []);
useEffect(() => {
return () => { dispose(); };
}, [dispose]);
return {
state,
ghostTextAddon: ghostAddonRef.current,
handleInput,
handleKeyEvent,
selectSuggestion,
repositionPopup,
closePopup,
dispose,
};
}
function resolveAutocompleteCwd(
promptText: string,
currentWord: string,
fallbackCwd: string | undefined,
os: "linux" | "windows" | "macos",
): string | undefined {
if (os === "windows") return fallbackCwd;
const normalizedWord = currentWord.trim().replace(/^['"]/, "");
// Absolute or home-relative paths don't depend on cwd
if (normalizedWord.startsWith("/") || normalizedWord.startsWith("~/")) {
return fallbackCwd;
}
// For empty word (e.g. "cd ") and relative paths, try prompt-based cwd
// extraction which reflects the current visible prompt — more up-to-date
// than fallbackCwd when OSC 7 is not supported.
const promptCwd = extractPosixCwdFromPrompt(promptText);
return chooseAutocompleteCwd(promptCwd, fallbackCwd);
}
function chooseAutocompleteCwd(
promptCwd: string | undefined,
fallbackCwd: string | undefined,
): string | undefined {
if (!promptCwd) return fallbackCwd;
if (!fallbackCwd) return promptCwd;
// Prompt cwd is extracted from the currently visible prompt, so it tracks
// directory changes even when OSC 7 is not supported. Prefer it over
// fallbackCwd (which may be stale from initial connection) whenever it
// looks like a usable path.
if (promptCwd.startsWith("/") || promptCwd === "~" || promptCwd.startsWith("~/")) {
return promptCwd;
}
// Bare directory name (e.g. "xunlong") can't be used as a path — fallback
return fallbackCwd;
}
function extractPosixCwdFromPrompt(promptText: string): string | undefined {
const trimmed = promptText.trimEnd().replace(/[#$%>]\s*$/, "");
if (!trimmed) return undefined;
const patterns = [
/:(\/[^\s\]]*|~(?:\/[^\s\]]*)?)$/,
/\s(\/[^\s\]]*|~(?:\/[^\s\]]*)?)\]$/,
/(^|[\s:])(\/[^\s\]]*|~(?:\/[^\s\]]*)?)$/,
];
for (const pattern of patterns) {
const match = trimmed.match(pattern);
if (!match) continue;
const candidate = match[match.length - 1];
if (candidate === "/" || candidate.startsWith("/") || candidate === "~" || candidate.startsWith("~/")) {
return candidate;
}
}
const fallbackTokens = trimmed
.split(/\s+/)
.map((token) => token.replace(/^[([{:]+/, "").replace(/[\])}:]+$/, ""));
for (let index = fallbackTokens.length - 1; index >= 0; index--) {
const candidate = fallbackTokens[index];
if (candidate === "/" || candidate.startsWith("/") || candidate === "~" || candidate.startsWith("~/")) {
return candidate;
}
}
return undefined;
}
function areSuggestionsEqual(
left: CompletionSuggestion[],
right: CompletionSuggestion[],
): boolean {
if (left.length !== right.length) return false;
for (let i = 0; i < left.length; i++) {
const a = left[i];
const b = right[i];
if (
a.text !== b.text ||
a.displayText !== b.displayText ||
a.description !== b.description ||
a.source !== b.source ||
a.score !== b.score ||
a.frequency !== b.frequency ||
a.fileType !== b.fileType
) {
return false;
}
}
return true;
}
function areSubDirPanelsEqual(left: SubDirPanel[], right: SubDirPanel[]): boolean {
if (left.length !== right.length) return false;
for (let i = 0; i < left.length; i++) {
const a = left[i];
const b = right[i];
if (a.dirPath !== b.dirPath || a.selectedIndex !== b.selectedIndex) return false;
if (a.entries.length !== b.entries.length) return false;
for (let j = 0; j < a.entries.length; j++) {
if (a.entries[j].name !== b.entries[j].name || a.entries[j].type !== b.entries[j].type) {
return false;
}
}
}
return true;
}
/**
* Calculate popup position based on terminal cursor.
*/
function calculatePopupPosition(
term: XTerm,
itemCount: number,
): {
position: { x: number; y: number };
cursorLineTop: number;
cursorLineBottom: number;
expandUpward: boolean;
} {
const termElement = term.element;
if (!termElement) {
return {
position: { x: 0, y: 0 },
cursorLineTop: 0,
cursorLineBottom: 0,
expandUpward: false,
};
}
const dims = getXTermCellDimensions(term);
const buffer = term.buffer.active;
const cursorX = buffer.cursorX;
const cursorY = buffer.cursorY;
const cursorLineTop = cursorY * dims.height;
const cursorLineBottom = (cursorY + 1) * dims.height;
const estimatedPopupHeight = itemCount * 28 + 8;
const totalRows = term.rows;
const spaceBelow = (totalRows - cursorY - 1) * dims.height;
const expandUpward = spaceBelow < estimatedPopupHeight && cursorY > 2;
if (expandUpward) {
return {
position: { x: cursorX * dims.width, y: cursorY * dims.height },
cursorLineTop,
cursorLineBottom,
expandUpward: true,
};
}
return {
position: { x: cursorX * dims.width, y: (cursorY + 1) * dims.height + 4 },
cursorLineTop,
cursorLineBottom,
expandUpward: false,
};
}