AblyCliTerminal.tsx

import React, {
  useEffect,
  useRef,
  useState,
  useCallback,
  useImperativeHandle,
  forwardRef,
} from "react";
import { Terminal } from "@xterm/xterm";
import { FitAddon } from "@xterm/addon-fit";
import "@xterm/xterm/css/xterm.css";
import TerminalOverlay, { OverlayVariant } from "./TerminalOverlay";
import {
  drawBox,
  clearBox,
  updateLine,
  colour as boxColour,
  colour,
  type TerminalBox,
} from "./terminal-box";
import {
  getAttempts as grGetAttempts,
  getMaxAttempts as grGetMaxAttempts,
  isCancelledState as grIsCancelledState,
  isMaxAttemptsReached as grIsMaxAttemptsReached,
  resetState as grResetState,
  cancelReconnect as grCancelReconnect,
  scheduleReconnect as grScheduleReconnect,
  setCountdownCallback as grSetCountdownCallback,
  setMaxAttempts as grSetMaxAttempts,
  successfulConnectionReset as grSuccessfulConnectionReset,
  increment as grIncrement,
} from "./global-reconnect";
import { useTerminalVisibility } from "./use-terminal-visibility.js";
import { SplitSquareHorizontal, X } from "lucide-react";
import { hashCredentials } from "./utils/crypto";
import { getConnectionMessage } from "./connection-messages";
import {
  HandshakeFilterState,
  createHandshakeFilterState,
  filterDockerHandshake,
  createTerminal,
  createFitAddon,
  safeFit,
  createAuthPayload,
  parseControlMessage,
  messageDataToUint8Array,
  clearConnectingMessage,
  showConnectingMessage,
  debugLog as sharedDebugLog,
  CONTROL_MESSAGE_PREFIX,
  MAX_PTY_BUFFER_LENGTH,
  TERMINAL_PROMPT_PATTERN,
} from "./terminal-shared";

/**
 * Simple debounce utility function to prevent rapid successive calls
 */
function debounce<T extends (...arguments_: any[]) => any>(
  function_: T,
  wait: number,
): (...arguments_: Parameters<T>) => void {
  let timeout: ReturnType<typeof setTimeout> | null = null;

  return function (...arguments_: Parameters<T>): void {
    if (timeout !== null) {
      clearTimeout(timeout);
    }
    timeout = setTimeout(() => {
      function_(...arguments_);
      timeout = null;
    }, wait);
  };
}

export type ConnectionStatus =
  | "initial"
  | "connecting"
  | "connected"
  | "disconnected"
  | "reconnecting"
  | "error";

// Prompts that indicate the terminal is ready for input
const TERMINAL_PROMPT_IDENTIFIER = "ably> "; // Basic prompt

// Shared CLI installation tip
const CLI_INSTALL_TIP = {
  lines: [
    "Pro tip: Want full control and speed? Install the CLI locally",
    "         $ npm install -g @ably/cli",
  ],
};

export interface AblyCliTerminalProperties {
  websocketUrl: string;
  ablyAccessToken?: string;
  ablyApiKey?: string;
  initialCommand?: string;
  onConnectionStatusChange?: (status: ConnectionStatus) => void;
  onSessionEnd?: (reason: string) => void;
  /**
   * Called once when the server sends the initial "hello" message containing the sessionId.
   * This is useful for embedding apps that want to display or persist the current session.
   */
  onSessionId?: (sessionId: string) => void;
  /**
   * When true, the component stores the current sessionId in localStorage on
   * page unload and attempts to resume that session on the next mount.
   */
  resumeOnReload?: boolean;
  maxReconnectAttempts?: number;
  /**
   * CI authentication token for bypassing rate limits in tests
   */
  ciAuthToken?: string;
  /**
   * When true, enables split-screen mode with a second independent terminal.
   * A split icon will be displayed in the top-right corner when in single-pane mode.
   */
  enableSplitScreen?: boolean;
  /**
   * When true (default), shows the internal split control button.
   * Set to false when controlling split externally to hide the internal UI affordance.
   */
  showSplitControl?: boolean;
  /**
   * An optional value to set as the ABLY_ENDPOINT environment variable when
   * starting the CLI, which controls which endpoint the SDK client uses.
   *
   * For example, to start the CLI configured to use the sandbox cluster, set
   * ablyEndpoint to 'nonprod:sandbox'.
   *
   * When unset, the CLI will use the main production endpoint.
   *
   * See https://sdk.ably.com/builds/ably/specification/main/features/#endpoint-configuration
   */
  ablyEndpoint?: string;
  /**
   * An optional value to set as the ABLY_CONTROL_HOST environment variable
   * when starting the CLI, which controls which hostname the CLI uses to
   * connect to the Control API.
   *
   * For example, to start the CLI configured to use the staging Control API,
   * set ablyControlHost to 'staging-control.ably-dev.net'.
   *
   * When unset, the CLI uses the production Control API at control.ably.net.
   */
  ablyControlHost?: string;
}

export interface AblyCliTerminalHandle {
  /** Enable split-screen mode programmatically. No-op if split-screen is disabled by props. */
  enableSplitScreen: () => void;
  /** Disable split-screen mode programmatically (closes secondary terminal). */
  disableSplitScreen: () => void;
  /** Toggle split-screen mode. */
  toggleSplitScreen: () => void;
  /** Set split position as a percentage (0-100). Values are clamped. */
  setSplitPosition: (percent: number) => void;
  /** Read current split state. */
  getSplitState: () => { isSplit: boolean; splitPosition: number };
}

// Use shared debug logging
const debugLog = sharedDebugLog;

// Automatically enable debug logging if ?cliDebug=true is present in the URL
if (globalThis.window !== undefined) {
  try {
    const urlFlag = new URLSearchParams(globalThis.location.search).get(
      "cliDebug",
    );
    if (urlFlag === "true") {
      (globalThis as any).ABLY_CLI_DEBUG = true;
    }
  } catch {
    /* ignore URL parsing errors in non-browser env */
  }
}

// Import isHijackMetaChunk from shared module for backward compatibility
import { isHijackMetaChunk } from "./terminal-shared";

const AblyCliTerminalInner = (
  {
    websocketUrl,
    ablyAccessToken,
    ablyApiKey,
    initialCommand,
    onConnectionStatusChange,
    onSessionEnd,
    onSessionId,
    resumeOnReload,
    maxReconnectAttempts,
    enableSplitScreen = false,
    showSplitControl = true,
    ablyEndpoint,
    ablyControlHost,
  }: AblyCliTerminalProperties,
  reference: React.Ref<AblyCliTerminalHandle>,
) => {
  const [componentConnectionStatus, setComponentConnectionStatusState] =
    useState<ConnectionStatus>("initial");
  const [isSessionActive, setIsSessionActive] = useState(false);
  const [connectionHelpMessage, setConnectionHelpMessage] = useState("");
  const [reconnectAttemptMessage, setReconnectAttemptMessage] = useState("");
  const [countdownMessage, setCountdownMessage] = useState("");
  const [overlay, setOverlay] = useState<null | {
    variant: OverlayVariant;
    title: string;
    lines: string[];
    drawer?: { lines: string[] };
  }>(null);
  const [connectionStartTime, setConnectionStartTime] = useState<number | null>(
    null,
  );
  const [showInstallInstructions, setShowInstallInstructions] = useState(false);

  // -------------------------------------------------------------
  // Split-screen UI state
  // -------------------------------------------------------------

  /**
   * `isSplit` controls whether the UI is currently displaying a secondary pane.
   * We now initialize a second terminal session when this is enabled.
   */
  const [isSplit, setIsSplit] = useState<boolean>(() => {
    if (
      resumeOnReload &&
      globalThis.window !== undefined &&
      enableSplitScreen
    ) {
      return globalThis.sessionStorage.getItem("ably.cli.isSplit") === "true";
    }
    return false;
  });

  /**
   * `splitPosition` controls the relative width of the left pane as a percentage (0-100)
   */
  const [splitPosition, setSplitPosition] = useState<number>(() => {
    if (
      resumeOnReload &&
      globalThis.window !== undefined &&
      enableSplitScreen
    ) {
      const saved = globalThis.sessionStorage.getItem("ably.cli.splitPosition");
      return saved ? Number.parseFloat(saved) : 50; // Default to 50% if not found
    }
    return 50; // Default to 50% split
  });

  // Track whether we're currently dragging the divider
  const [isDragging, setIsDragging] = useState(false);
  // Ref to the outer container for calculating percentages
  const outerContainerReference = useRef<HTMLDivElement>(null);

  // Updated handler to initialize the secondary terminal
  const handleSplitScreenWithSecondTerminal = useCallback(() => {
    // First update the UI state
    setIsSplit(true);

    // Save split state to session storage if resume enabled
    if (resumeOnReload && globalThis.window !== undefined) {
      globalThis.sessionStorage.setItem("ably.cli.isSplit", "true");
    }

    // Secondary terminal will be initialized in useEffect that watches isSplit
  }, [resumeOnReload]);

  /** Toggle into split-screen mode with terminal session */
  const handleSplitScreen = useCallback(() => {
    // We now use the handler that will initialize a second terminal session
    handleSplitScreenWithSecondTerminal();
  }, [handleSplitScreenWithSecondTerminal]);

  /** Close both terminals and reset the split */
  const handleCloseSplit = useCallback(() => {
    // When closing the split, clean up the secondary terminal
    if (
      secondarySocketReference.current &&
      secondarySocketReference.current.readyState < WebSocket.CLOSING
    ) {
      secondarySocketReference.current.close();
      secondarySocketReference.current = null;
    }

    if (secondaryTerm.current) {
      secondaryTerm.current.dispose();
      secondaryTerm.current = null;
    }

    // Reset secondary terminal state
    updateSecondaryConnectionStatus("initial");
    setIsSecondarySessionActive(false);
    setSecondaryShowManualReconnectPrompt(false);
    setSecondarySessionId(null);
    setSecondaryOverlay(null);

    // Return to single-pane mode
    setIsSplit(false);

    // Clear split state in session storage
    if (resumeOnReload && globalThis.window !== undefined) {
      globalThis.sessionStorage.removeItem("ably.cli.isSplit");
      globalThis.sessionStorage.removeItem("ably.cli.secondarySessionId");
    }

    // Resize the primary terminal after a delay
    setTimeout(() => {
      if (term.current && fitAddon.current) {
        try {
          fitAddon.current.fit();
        } catch (error) {
          console.warn(
            "Error fitting primary terminal after closing split:",
            error,
          );
        }
      }
    }, 50);
  }, []);

  // Imperative handle for external control of split operations
  useImperativeHandle(
    reference,
    () => ({
      enableSplitScreen: () => {
        if (!enableSplitScreen) {
          console.warn(
            "[AblyCLITerminal] enableSplitScreen prop is false; cannot enable split.",
          );
          return;
        }
        if (!isSplit) {
          handleSplitScreenWithSecondTerminal();
        }
      },
      disableSplitScreen: () => {
        if (isSplit) {
          handleCloseSplit();
        }
      },
      toggleSplitScreen: () => {
        if (!enableSplitScreen) {
          console.warn(
            "[AblyCLITerminal] enableSplitScreen prop is false; cannot toggle split.",
          );
          return;
        }
        if (isSplit) {
          handleCloseSplit();
        } else {
          handleSplitScreenWithSecondTerminal();
        }
      },
      setSplitPosition: (percent: number) => {
        const clamped = Math.max(0, Math.min(100, Number(percent)));
        setSplitPosition(clamped);
      },
      getSplitState: () => ({ isSplit, splitPosition }),
    }),
    [
      enableSplitScreen,
      handleSplitScreenWithSecondTerminal,
      handleCloseSplit,
      isSplit,
      splitPosition,
    ],
  );

  /** Handle clicking Close on Terminal 1 (primary) */
  const handleClosePrimary = useCallback(() => {
    // When closing the primary terminal but keeping the secondary one,
    // make sure the secondary terminal is properly displayed

    if (secondaryTerm.current && secondarySocketReference.current) {
      debugLog("[AblyCLITerminal] Closing primary terminal, keeping secondary");

      // Close the primary socket cleanly
      if (
        socketReference.current &&
        socketReference.current.readyState < WebSocket.CLOSING
      ) {
        debugLog("[AblyCLITerminal] Closing primary socket");
        socketReference.current.close(1000, "user-closed-primary");
        socketReference.current = null;
      }

      // Store the secondary values before reset
      const temporarySocket = secondarySocketReference.current;
      const temporaryTerm = secondaryTerm.current;
      const temporaryFitAddon = secondaryFitAddon.current;
      const temporarySessionId = secondarySessionId;
      const temporaryIsActive = isSecondarySessionActive;

      // Dispose the primary terminal if it exists
      if (term.current) {
        term.current.dispose();
        term.current = null;
      }

      // Clear the secondary terminal's state AFTER saving references
      secondarySocketReference.current = null;
      secondaryTerm.current = null;
      secondaryFitAddon.current = undefined;

      // Ensure we properly transfer the DOM element
      // This is critical - we need to move the secondary terminal's
      // DOM element to the primary terminal's container
      if (
        rootReference.current &&
        temporaryTerm &&
        secondaryRootReference.current
      ) {
        // Get the xterm DOM element from the secondary container
        const xtermElement =
          secondaryRootReference.current.querySelector(".xterm");
        if (xtermElement) {
          // Clear the primary container
          while (rootReference.current.firstChild) {
            rootReference.current.firstChild.remove();
          }

          // Move the xterm element to the primary container
          rootReference.current.append(xtermElement);
          debugLog(
            "[AblyCLITerminal] Moved secondary terminal DOM element to primary container",
          );
        }
      }

      // Swap references
      term.current = temporaryTerm;
      fitAddon.current = temporaryFitAddon;
      socketReference.current = temporarySocket;

      // Update state
      setIsSplit(false);
      setSessionId(temporarySessionId);
      updateSessionActive(temporaryIsActive);

      // Reset secondary terminal state
      updateSecondaryConnectionStatus("initial");
      setIsSecondarySessionActive(false);
      setSecondaryShowManualReconnectPrompt(false);
      setSecondarySessionId(null);
      setSecondaryOverlay(null);

      // Clear split state in session storage
      if (resumeOnReload && globalThis.window !== undefined) {
        globalThis.sessionStorage.removeItem("ably.cli.isSplit");
        globalThis.sessionStorage.removeItem("ably.cli.secondarySessionId");
      }

      // Resize the terminal after a delay
      setTimeout(() => {
        if (term.current && fitAddon.current) {
          try {
            fitAddon.current.fit();
          } catch (error) {
            console.warn(
              "Error fitting terminal after closing primary:",
              error,
            );
          }
        }
      }, 50);
    } else {
      // If there's no secondary terminal, just close everything (same as handleCloseSplit)
      handleCloseSplit();
    }
  }, [handleCloseSplit, resumeOnReload]);

  /** Close the secondary pane and return to single-pane mode */
  const handleCloseSecondary = useCallback(() => {
    // When closing the secondary terminal, clean it up but keep the primary one
    if (
      secondarySocketReference.current &&
      secondarySocketReference.current.readyState < WebSocket.CLOSING
    ) {
      debugLog("[AblyCLITerminal] Closing secondary socket");
      secondarySocketReference.current.close(1000, "user-closed-secondary");
      secondarySocketReference.current = null;
    }

    if (secondaryTerm.current) {
      secondaryTerm.current.dispose();
      secondaryTerm.current = null;
    }

    // Reset secondary terminal state
    updateSecondaryConnectionStatus("initial");
    setIsSecondarySessionActive(false);
    setSecondaryShowManualReconnectPrompt(false);
    setSecondarySessionId(null);
    setSecondaryOverlay(null);

    // Return to single-pane mode
    setIsSplit(false);

    // Clear split state in session storage
    if (resumeOnReload && globalThis.window !== undefined) {
      globalThis.sessionStorage.removeItem("ably.cli.isSplit");
      globalThis.sessionStorage.removeItem("ably.cli.secondarySessionId");
    }

    // Resize the primary terminal after a delay
    setTimeout(() => {
      if (term.current && fitAddon.current) {
        try {
          fitAddon.current.fit();
        } catch (error) {
          console.warn(
            "Error fitting primary terminal after closing split:",
            error,
          );
        }
      }
    }, 50);
  }, [resumeOnReload]);

  // Track the current sessionId received from the server (if any)
  const [sessionId, setSessionId] = useState<string | null>(null);
  const [credentialHash, setCredentialHash] = useState<string | null>(null);
  const [credentialsInitialized, setCredentialsInitialized] = useState(false);
  const [sessionIdInitialized, setSessionIdInitialized] = useState(false);

  // Track the second terminal's sessionId
  const [secondarySessionId, setSecondarySessionId] = useState<string | null>(
    () => {
      if (
        resumeOnReload &&
        globalThis.window !== undefined &&
        globalThis.sessionStorage.getItem("ably.cli.isSplit") === "true"
      ) {
        return globalThis.sessionStorage.getItem("ably.cli.secondarySessionId");
      }
      return null;
    },
  );

  const [socket, setSocket] = useState<WebSocket | null>(null);
  const [showManualReconnectPrompt, setShowManualReconnectPrompt] =
    useState(false);

  const rootReference = useRef<HTMLDivElement>(null);
  // Determine if terminal is visible (drawer open & tab visible)
  const isVisible = useTerminalVisibility(rootReference);
  const term = useRef<Terminal | null>(null);
  const fitAddon = useRef<FitAddon>();
  const ptyBuffer = useRef("");
  const handshakeFilterState = useRef<HandshakeFilterState>(
    createHandshakeFilterState(),
  );
  // Keep a ref in sync with the latest connection status so event handlers have up-to-date value
  const connectionStatusReference = useRef<ConnectionStatus>("initial");
  // Store cleanup function for terminal resize handler
  const termCleanupReference = useRef<() => void>(() => {});

  // Ref to track manual reconnect prompt visibility inside stable event handlers
  const showManualReconnectPromptReference = useRef<boolean>(false);
  // Guard to ensure we do NOT double-count a failed attempt when both the
  // `error` and the subsequent `close` events fire for the *same* socket.
  const reconnectScheduledThisCycleReference = useRef<boolean>(false);

  // Keep a ref in sync with session active state for use in closures
  const isSessionActiveReference = useRef<boolean>(false);

  // Keep a ref for sessionId to use in closures
  const sessionIdReference = useRef<string | null>(sessionId);

  // Use block-based spinner where empty dots are invisible in most monospace fonts
  const spinnerFrames = ["●  ", " ● ", "  ●", " ● "];
  const spinnerIntervalReference = useRef<ReturnType<
    typeof setInterval
  > | null>(null);
  const spinnerIndexReference = useRef<number>(0);
  const spinnerPrefixReference = useRef<string>("");
  const statusBoxReference = useRef<TerminalBox | null>(null);

  // ANSI colour / style helpers
  const colour = {
    reset: "\u001B[0m",
    bold: "\u001B[1m",
    dim: "\u001B[2m",
    red: "\u001B[31m",
    green: "\u001B[32m",
    yellow: "\u001B[33m",
    blue: "\u001B[34m",
    magenta: "\u001B[35m",
    cyan: "\u001B[36m",
  } as const;

  const clearStatusDisplay = useCallback(() => {
    if (spinnerIntervalReference.current) {
      clearInterval(spinnerIntervalReference.current);
      spinnerIntervalReference.current = null;
    }
    spinnerIndexReference.current = 0;
    if (statusBoxReference.current && term.current) {
      clearBox(statusBoxReference.current);
      statusBoxReference.current = null;
      /* status box cleared */
    }
    setOverlay(null);
    /* clearStatusDisplay completed */
  }, []);

  /**
   * Clears spinner interval and the xterm drawn box **without** touching the React overlay.
   * Useful when we want the overlay to persist between automatic reconnect attempts.
   */
  const clearTerminalBoxOnly = useCallback(() => {
    // Intentionally keep the spinner interval running so the overlay continues
    // to animate between failed attempts. Only the ANSI/xterm box is cleared.
    if (statusBoxReference.current && term.current) {
      clearBox(statusBoxReference.current);
      statusBoxReference.current = null;
      /* Terminal box cleared (overlay retained) */
    }
  }, []);

  // Keep the ref in sync with React state so key handlers can rely on it
  useEffect(() => {
    showManualReconnectPromptReference.current = showManualReconnectPrompt;
  }, [showManualReconnectPrompt]);

  const updateConnectionStatusAndExpose = useCallback(
    (status: ConnectionStatus) => {
      // updateConnectionStatusAndExpose debug removed
      setComponentConnectionStatusState(status);
      // (window as any).componentConnectionStatusForTest = status; // Keep for direct inspection if needed, but primary is below
      // console.log(`[AblyCLITerminal] (window as any).componentConnectionStatusForTest SET TO: ${status}`);

      connectionStatusReference.current = status;

      // Only report status changes from the primary terminal
      if (
        typeof (globalThis as any).setWindowTestFlagOnStatusChange ===
        "function"
      ) {
        (globalThis as any).setWindowTestFlagOnStatusChange(status);
      }

      if (onConnectionStatusChange) {
        onConnectionStatusChange(status);
      }
    },
    [onConnectionStatusChange],
  );

  useEffect(() => {
    connectionStatusReference.current = componentConnectionStatus;
  }, [componentConnectionStatus]);

  useEffect(() => {
    if (isSessionActive) {
      setConnectionHelpMessage("Connected to Ably CLI terminal server");
    } else {
      setConnectionHelpMessage(""); // Clear help message when not active
    }
  }, [isSessionActive]);

  // Keep sessionId ref in sync
  useEffect(() => {
    sessionIdReference.current = sessionId;
  }, [sessionId]);

  const clearPtyBuffer = useCallback(() => {
    debugLog(
      `⚠️ DIAGNOSTIC: Clearing PTY buffer, current size: ${ptyBuffer.current.length}`,
    );
    if (ptyBuffer.current.length > 0) {
      const sanitizedBuffer = ptyBuffer.current
        .replaceAll("\r", "\\r")
        .replaceAll("\n", "\\n")
        .slice(-100); // Only show last 100 chars to avoid log bloat
      debugLog(
        `⚠️ DIAGNOSTIC: Buffer content before clear: "${sanitizedBuffer}"`,
      );
    }
    ptyBuffer.current = "";
  }, []);

  // Helper to update both session active state and ref
  const updateSessionActive = useCallback((active: boolean) => {
    debugLog(`⚠️ DIAGNOSTIC: Updating session active to: ${active}`);
    setIsSessionActive(active);
    isSessionActiveReference.current = active;
  }, []);

  // Connection timeout management
  const connectionTimeoutReference = useRef<NodeJS.Timeout | null>(null);
  const CONNECTION_TIMEOUT_MS = 30_000; // 30 seconds
  const installInstructionsTimerReference = useRef<NodeJS.Timeout | null>(null);
  const SHOW_INSTALL_AFTER_MS = 6000; // 6 seconds

  const clearConnectionTimeout = useCallback(() => {
    if (connectionTimeoutReference.current) {
      clearTimeout(connectionTimeoutReference.current);
      connectionTimeoutReference.current = null;
    }
  }, []);

  const clearInstallInstructionsTimer = useCallback(() => {
    if (installInstructionsTimerReference.current) {
      clearTimeout(installInstructionsTimerReference.current);
      installInstructionsTimerReference.current = null;
    }
  }, []);

  // Ref to track if we should send initial command when prompt is detected
  const pendingInitialCommandReference = useRef<string | null>(null);

  // Timeout reference for prompt detection fallback
  const promptDetectionTimeoutReference = useRef<NodeJS.Timeout | null>(null);
  const PROMPT_DETECTION_TIMEOUT_MS = 5000; // 5 seconds

  const clearPromptDetectionTimeout = useCallback(() => {
    if (promptDetectionTimeoutReference.current) {
      clearTimeout(promptDetectionTimeoutReference.current);
      promptDetectionTimeoutReference.current = null;
    }
  }, []);

  // Shared logic for activating session (called by both prompt detection and timeout)
  const activateSessionAndSendCommand = useCallback(() => {
    updateSessionActive(true);
    grSuccessfulConnectionReset();
    updateConnectionStatusAndExpose("connected");

    if (term.current) {
      debugLog(`⚠️ DIAGNOSTIC: Session is now active, focusing terminal`);
      term.current.focus();
    }

    // Reset connection tracking
    setConnectionStartTime(null);
    setShowInstallInstructions(false);
    clearInstallInstructionsTimer();
    clearPromptDetectionTimeout();

    // Send initial command if one is pending
    if (pendingInitialCommandReference.current) {
      const commandToSend = pendingInitialCommandReference.current;
      pendingInitialCommandReference.current = null;
      debugLog(
        `⚠️ DIAGNOSTIC: Sending pending initial command: "${commandToSend}"`,
      );
      setTimeout(() => {
        if (
          socketReference.current &&
          socketReference.current.readyState === WebSocket.OPEN
        ) {
          socketReference.current.send(`${commandToSend}\r`);
        }
      }, 100);
    }
  }, [
    updateSessionActive,
    updateConnectionStatusAndExpose,
    clearInstallInstructionsTimer,
    clearPromptDetectionTimeout,
  ]);

  const handlePtyData = useCallback(
    (data: string) => {
      // Always log what data we receive
      const sanitizedData = data
        .replaceAll("\r", "\\r")
        .replaceAll("\n", "\\n")
        .replaceAll("\t", "\\t");
      debugLog(
        `⚠️ DIAGNOSTIC: handlePtyData called. isSessionActive: ${isSessionActiveReference.current}, data: "${sanitizedData}"`,
      );

      if (!isSessionActiveReference.current) {
        ptyBuffer.current += data;

        debugLog(
          `⚠️ DIAGNOSTIC: Received PTY data (session inactive): "${sanitizedData}"`,
        );
        debugLog(
          `⚠️ DIAGNOSTIC: Current connection status: ${connectionStatusReference.current}, sessionId: ${sessionIdReference.current}`,
        );

        if (ptyBuffer.current.length > MAX_PTY_BUFFER_LENGTH) {
          ptyBuffer.current = ptyBuffer.current.slice(
            ptyBuffer.current.length - MAX_PTY_BUFFER_LENGTH,
          );
        }

        // Strip ANSI colour/formatting codes before looking for the prompt
        const cleanBuf = ptyBuffer.current.replaceAll(
          /\u001B\[[0-9;]*[mGKHF]/g,
          "",
        );
        debugLog(
          `⚠️ DIAGNOSTIC: Clean buffer (${cleanBuf.length} chars): "${cleanBuf.slice(-50)}"`,
        );

        // Only detect the prompt if it appears at the end of the buffer,
        // not somewhere in the middle of previous output
        // Also check for common Ably CLI prompts
        const hasShellPrompt = TERMINAL_PROMPT_PATTERN.test(cleanBuf);
        const hasAblyPrompt =
          cleanBuf.endsWith("ably> ") ||
          cleanBuf.endsWith("> ") ||
          cleanBuf.endsWith("$ ");

        debugLog(
          `⚠️ DIAGNOSTIC: Checking for prompt. hasShellPrompt: ${hasShellPrompt}, hasAblyPrompt: ${hasAblyPrompt}, buffer end: "${cleanBuf.slice(-20)}"`,
        );

        if (hasShellPrompt || hasAblyPrompt) {
          debugLog(
            `⚠️ DIAGNOSTIC: Prompt detected at end of buffer (shell: ${hasShellPrompt}, ably: ${hasAblyPrompt})`,
          );
          clearStatusDisplay(); // Clear the status box as per plan

          // Only set active if not already active to prevent multiple state updates
          if (!isSessionActiveReference.current) {
            activateSessionAndSendCommand();
          }

          clearPtyBuffer();
        }
      } else {
        debugLog(`⚠️ DIAGNOSTIC: Session already active, not buffering data`);
      }
    },
    [
      updateConnectionStatusAndExpose,
      updateSessionActive,
      clearPtyBuffer,
      clearStatusDisplay,
      clearInstallInstructionsTimer,
      activateSessionAndSendCommand,
    ],
  );

  // Secondary terminal instance references
  const secondaryRootReference = useRef<HTMLDivElement>(null);
  const secondaryTerm = useRef<Terminal | null>(null);
  const secondaryFitAddon = useRef<FitAddon>();
  const secondarySocketReference = useRef<WebSocket | null>(null);
  const secondaryPtyBuffer = useRef("");
  const secondaryHandshakeFilterState = useRef<HandshakeFilterState>(
    createHandshakeFilterState(),
  );
  const secondaryTermCleanupReference = useRef<() => void>(() => {});

  // Secondary terminal state
  const [secondarySocket, setSecondarySocket] = useState<WebSocket | null>(
    null,
  );
  const [isSecondarySessionActive, setIsSecondarySessionActive] =
    useState(false);
  const [secondaryOverlay, setSecondaryOverlay] = useState<null | {
    variant: OverlayVariant;
    title: string;
    lines: string[];
  }>(null);

  // Secondary terminal refs - need their own copies for event handlers
  const secondaryConnectionStatusReference =
    useRef<ConnectionStatus>("initial");
  const [secondaryConnectionStatus, setSecondaryConnectionStatus] =
    useState<ConnectionStatus>("initial");
  const secondarySpinnerPrefixReference = useRef<string>("");
  const secondarySpinnerIndexReference = useRef<number>(0);
  const secondaryStatusBoxReference = useRef<TerminalBox | null>(null);
  const secondarySpinnerIntervalReference = useRef<ReturnType<
    typeof setInterval
  > | null>(null);
  const secondaryShowManualReconnectPromptReference = useRef<boolean>(false);
  const [
    secondaryShowManualReconnectPrompt,
    setSecondaryShowManualReconnectPrompt,
  ] = useState(false);
  const secondaryReconnectScheduledThisCycleReference = useRef<boolean>(false);

  // Secondary terminal: pending initial command and timeout refs
  const pendingSecondaryInitialCommandReference = useRef<string | null>(null);
  const secondaryPromptDetectionTimeoutReference =
    useRef<NodeJS.Timeout | null>(null);

  // Extracted control message handler to avoid duplication
  const handleControlMessage = useCallback(
    (message: any) => {
      if (message.type === "hello" && typeof message.sessionId === "string") {
        debugLog(
          `⚠️ DIAGNOSTIC: Received hello message with sessionId=${message.sessionId}`,
        );
        const wasReconnecting =
          connectionStatusReference.current === "reconnecting";
        const wasConnecting =
          connectionStatusReference.current === "connecting";
        setSessionId(message.sessionId);
        if (onSessionId) onSessionId(message.sessionId);
        debugLog(
          "Received hello. sessionId=",
          message.sessionId,
          " (was:",
          sessionId,
          ")",
        );

        // Clear the "Connecting..." message and status box
        if (term.current) {
          clearConnectingMessage(term.current);
          term.current.focus();
        }

        // Clear the status box
        clearStatusDisplay();

        // Check if this is a resumed session (we sent a sessionId in auth payload)
        const isResumedSession =
          sessionId !== null && sessionId === message.sessionId;

        if (isResumedSession) {
          // For resumed sessions, activate immediately without waiting for prompt
          debugLog(
            `⚠️ DIAGNOSTIC: Resumed existing session ${message.sessionId} - activating immediately`,
          );
          updateConnectionStatusAndExpose("connected");

          // Activate session immediately for resumed sessions
          if (!isSessionActiveReference.current) {
            activateSessionAndSendCommand();
          }
        } else {
          // For new sessions, wait for prompt detection
          debugLog(
            `⚠️ DIAGNOSTIC: New session ${message.sessionId} - waiting for prompt before activating`,
          );
          updateConnectionStatusAndExpose("connected");
        }

        // Don't clear the buffer yet - let prompt detection handle it (for new sessions)

        // Persist to session storage if enabled (domain-scoped)
        if (resumeOnReload && globalThis.window !== undefined) {
          const urlDomain = new URL(websocketUrl).host;
          globalThis.sessionStorage.setItem(
            `ably.cli.sessionId.${urlDomain}`,
            message.sessionId,
          );

          // Store credential hash if it's already computed
          if (credentialHash) {
            globalThis.sessionStorage.setItem(
              `ably.cli.credentialHash.${urlDomain}`,
              credentialHash,
            );
          }
        }
        return;
      }

      if (message.type === "status") {
        debugLog(
          `⚠️ DIAGNOSTIC: Received server status message: ${message.payload}`,
        );

        // Handle different status payloads
        if (message.payload === "connected") {
          debugLog(`⚠️ DIAGNOSTIC: Handling 'connected' status message`);
          clearStatusDisplay();

          // Clear the "Connecting..." message
          if (term.current) {
            debugLog(
              `⚠️ DIAGNOSTIC: Clearing connecting message and focusing terminal`,
            );
            clearConnectingMessage(term.current);
            term.current.focus();
          }

          // Check if we're resuming an existing session
          const isResuming = sessionIdReference.current !== null;

          if (isResuming) {
            // For resumed sessions, activate immediately
            debugLog(
              `⚠️ DIAGNOSTIC: Resuming session ${sessionIdReference.current} - activating immediately`,
            );
            updateConnectionStatusAndExpose("connected");

            if (!isSessionActiveReference.current) {
              activateSessionAndSendCommand();
            }
          } else {
            // For new sessions, wait for prompt detection
            debugLog(
              `⚠️ DIAGNOSTIC: New session - waiting for prompt before activating`,
            );
            updateConnectionStatusAndExpose("connected");

            // Start timeout fallback in case prompt is never detected
            clearPromptDetectionTimeout();
            promptDetectionTimeoutReference.current = setTimeout(() => {
              debugLog(
                `⚠️ DIAGNOSTIC: Prompt detection timeout - activating session anyway after ${PROMPT_DETECTION_TIMEOUT_MS}ms`,
              );
              if (!isSessionActiveReference.current) {
                activateSessionAndSendCommand();
              }
            }, PROMPT_DETECTION_TIMEOUT_MS);
          }

          // Don't clear the buffer or set session active yet - let prompt detection handle it
          return;
        }

        // Handle error & disconnected payloads
        if (message.payload === "error" || message.payload === "disconnected") {
          const reason =
            message.reason ||
            (message.payload === "error"
              ? "Server error"
              : "Server disconnected");
          if (term.current) {
            term.current.writeln(
              `\r\n--- ${message.payload === "error" ? "Error" : "Session Ended (from server)"}: ${reason} ---`,
            );
          }
          if (onSessionEnd) onSessionEnd(reason);
          updateConnectionStatusAndExpose(message.payload);

          // Handle session cleanup for disconnected status
          if (resumeOnReload && globalThis.window !== undefined) {
            const urlDomain = new URL(websocketUrl).host;
            globalThis.sessionStorage.removeItem(
              `ably.cli.sessionId.${urlDomain}`,
            );
            globalThis.sessionStorage.removeItem(
              `ably.cli.credentialHash.${urlDomain}`,
            );
            setSessionId(null);
          }

          // Show appropriate overlay for disconnected status
          if (term.current && message.payload === "disconnected") {
            const title = "SERVER DISCONNECTED";
            const message1 = `Connection closed by server (${message.code})${message.reason ? `: ${message.reason}` : ""}.`;
            const message2 = "";
            const message3 = `Press ⏎ to reconnect`;

            const lines = [message1, message2, message3];

            statusBoxReference.current = drawBox(
              term.current,
              boxColour.red,
              title,
              lines,
              60,
            );
            setOverlay({
              variant: "error",
              title,
              lines: lines,
              drawer: {
                lines: [
                  "Pro tip: Install the CLI locally for a faster experience with all features",
                  "    npm install -g @ably/cli",
                ],
              },
            });
          }
          return;
        }

        return;
      }

      // Log any unrecognized control messages
      console.warn("[WebSocket] Unrecognized control message:", message);
    },
    [
      sessionId,
      onSessionId,
      clearStatusDisplay,
      updateSessionActive,
      updateConnectionStatusAndExpose,
      clearPtyBuffer,
      resumeOnReload,
      websocketUrl,
      credentialHash,
      onSessionEnd,
      grSuccessfulConnectionReset,
    ],
  );

  // Function to clear the secondary terminal overlay and status displays
  const clearSecondaryStatusDisplay = useCallback(() => {
    if (secondarySpinnerIntervalReference.current) {
      clearInterval(secondarySpinnerIntervalReference.current);
      secondarySpinnerIntervalReference.current = null;
    }
    secondarySpinnerIndexReference.current = 0;
    if (secondaryStatusBoxReference.current && secondaryTerm.current) {
      clearBox(secondaryStatusBoxReference.current);
      secondaryStatusBoxReference.current = null;
    }
    setSecondaryOverlay(null);
    debugLog("[AblyCLITerminal] Secondary terminal status display cleared");
  }, []);

  const clearSecondaryPromptDetectionTimeout = useCallback(() => {
    if (secondaryPromptDetectionTimeoutReference.current) {
      clearTimeout(secondaryPromptDetectionTimeoutReference.current);
      secondaryPromptDetectionTimeoutReference.current = null;
    }
  }, []);

  // Shared logic for activating secondary session
  const activateSecondarySessionAndSendCommand = useCallback(() => {
    setIsSecondarySessionActive(true);
    updateSecondaryConnectionStatus("connected");

    if (secondaryTerm.current) {
      debugLog(
        "[AblyCLITerminal] [Secondary] Session is now active, focusing terminal",
      );
      secondaryTerm.current.focus();
    }

    clearSecondaryPromptDetectionTimeout();

    // Send initial command if one is pending
    if (pendingSecondaryInitialCommandReference.current) {
      const commandToSend = pendingSecondaryInitialCommandReference.current;
      pendingSecondaryInitialCommandReference.current = null;
      debugLog(
        `[AblyCLITerminal] [Secondary] Sending pending initial command: "${commandToSend}"`,
      );
      setTimeout(() => {
        if (
          secondarySocketReference.current &&
          secondarySocketReference.current.readyState === WebSocket.OPEN
        ) {
          secondarySocketReference.current.send(`${commandToSend}\r`);
        }
      }, 50);
    }
  }, [clearSecondaryPromptDetectionTimeout]);

  const handleSecondaryPtyData = useCallback(
    (data: string) => {
      if (!isSecondarySessionActive) {
        secondaryPtyBuffer.current += data;

        if (secondaryPtyBuffer.current.length > MAX_PTY_BUFFER_LENGTH) {
          secondaryPtyBuffer.current = secondaryPtyBuffer.current.slice(
            secondaryPtyBuffer.current.length - MAX_PTY_BUFFER_LENGTH,
          );
        }

        // Strip ANSI colour/formatting codes before looking for the prompt
        const cleanBuf = secondaryPtyBuffer.current.replaceAll(
          /\u001B\[[0-9;]*[mGKHF]/g,
          "",
        );

        // Only detect the prompt if it appears at the end of the buffer
        // Also check for common Ably CLI prompts
        const hasShellPrompt = TERMINAL_PROMPT_PATTERN.test(cleanBuf);
        const hasAblyPrompt =
          cleanBuf.endsWith("ably> ") ||
          cleanBuf.endsWith("> ") ||
          cleanBuf.endsWith("$ ");

        if (hasShellPrompt || hasAblyPrompt) {
          debugLog(
            "[AblyCLITerminal] [Secondary] Prompt detected – session active",
          );
          clearSecondaryStatusDisplay(); // Clear the overlay when prompt is detected

          // Only set active if not already active
          if (!isSecondarySessionActive) {
            activateSecondarySessionAndSendCommand();
          }

          secondaryPtyBuffer.current = "";
        }
      }
    },
    [
      clearSecondaryStatusDisplay,
      isSecondarySessionActive,
      activateSecondarySessionAndSendCommand,
    ],
  );

  const clearAnimationMessages = useCallback(() => {
    setReconnectAttemptMessage("");
    setCountdownMessage("");
    clearStatusDisplay();
    // lastWriteLine.current = ''; // No longer directly managing this for single status line
  }, [clearStatusDisplay]);

  const startConnectingAnimation = useCallback(
    (isRetry: boolean) => {
      if (!term.current) return;
      clearAnimationMessages(); // This already calls clearStatusDisplay

      const currentAttempts = grGetAttempts();
      const maxAttempts = grGetMaxAttempts();
      const title = isRetry ? "RECONNECTING" : "CONNECTING";
      const titleColor = isRetry ? boxColour.yellow : boxColour.cyan;

      let statusText = isRetry
        ? `Attempt ${currentAttempts + 1}/${maxAttempts} - Reconnecting to Ably CLI server...`
        : "Connecting to Ably CLI server...";
      const initialContent = [statusText, ""]; // Second line for potential countdown or messages

      // Write connecting message to terminal
      // Only show if it's not a retry AND not resuming a session
      if (term.current && !isRetry && !sessionIdReference.current) {
        showConnectingMessage(term.current, statusText);
      }

      // Draw the initial box (even though it's a stub, keep for compatibility)
      if (term.current) {
        // Keep content as is - no install instructions in the reconnecting box
        const boxContent = [...initialContent];

        statusBoxReference.current = drawBox(
          term.current,
          titleColor,
          title,
          boxContent,
          60,
        );
        spinnerPrefixReference.current = statusText; // Store base text for spinner line

        spinnerIndexReference.current = 0;
        const initialSpinnerChar =
          spinnerFrames[spinnerIndexReference.current % spinnerFrames.length];
        if (statusBoxReference.current) {
          // Initial spinner render
          const fullLineText = `${initialSpinnerChar} ${spinnerPrefixReference.current}`;
          updateLine(statusBoxReference.current, 0, fullLineText, titleColor);
        }

        spinnerIntervalReference.current = setInterval(() => {
          // Stop spinner when no longer in connecting states
          const currentState = connectionStatusReference.current;
          if (!["connecting", "reconnecting"].includes(currentState)) {
            if (spinnerIntervalReference.current)
              clearInterval(spinnerIntervalReference.current);
            return;
          }

          spinnerIndexReference.current += 1;
          const frame =
            spinnerFrames[spinnerIndexReference.current % spinnerFrames.length];
          const lineContent = `${frame} ${spinnerPrefixReference.current}`;

          // Update ANSI box if still present
          if (statusBoxReference.current) {
            updateLine(statusBoxReference.current, 0, lineContent, titleColor);
          }

          // Update overlay - preserve drawer or add it if showInstallInstructions is true
          setOverlay((previous) => {
            if (!previous) return previous;
            const newLines = [...previous.lines];
            // Only update the first line (spinner)
            newLines[0] = lineContent;
            return {
              ...previous,
              lines: newLines,
              ...(showInstallInstructions
                ? {
                    drawer: CLI_INSTALL_TIP,
                  }
                : { drawer: previous.drawer }),
            };
          });
        }, 250);
      }

      // startConnectingAnimation debug removed
      setReconnectAttemptMessage(
        isRetry
          ? `Attempt ${currentAttempts + 1}/${maxAttempts}`
          : "Connecting",
      );

      // Ensure the overlay shows the spinner immediately (not only after first interval tick)
      const initialSpinnerChar =
        spinnerFrames[spinnerIndexReference.current % spinnerFrames.length];
      const initialLines = [
        `${initialSpinnerChar} ${spinnerPrefixReference.current}`,
        "",
      ]; // Include empty line for countdown

      // Include drawer if install instructions should be shown
      const overlayConfig = {
        variant: (isRetry ? "reconnecting" : "connecting") as OverlayVariant,
        title,
        lines: initialLines,
        ...(showInstallInstructions
          ? {
              drawer: CLI_INSTALL_TIP,
            }
          : {}),
      };

      setOverlay(overlayConfig);
    },
    [clearAnimationMessages, showInstallInstructions],
  );

  const connectWebSocket = useCallback(() => {
    // console.log('[AblyCLITerminal] connectWebSocket called.');
    debugLog(
      "⚠️ DIAGNOSTIC: connectWebSocket called - start of connection process",
    );
    debugLog(
      `⚠️ DIAGNOSTIC: Current sessionId: ${sessionId}, credentialsInitialized: ${credentialsInitialized}`,
    );

    // Skip attempt if terminal not visible to avoid unnecessary server load
    if (!isVisible) {
      debugLog(
        "⚠️ DIAGNOSTIC: Terminal not visible, skipping connection attempt",
      );
      return;
    }

    // Prevent duplicate connections if one is already open/connecting
    if (
      !showManualReconnectPromptReference.current &&
      socketReference.current &&
      socketReference.current.readyState === WebSocket.OPEN
    ) {
      if ((globalThis as any).ABLY_CLI_DEBUG)
        console.warn(
          "[AblyCLITerminal] connectWebSocket already open/connecting – skip",
        );
      debugLog(
        "⚠️ DIAGNOSTIC: Socket already open/connecting, skipping connection attempt",
      );
      return;
    } else if (
      socketReference.current &&
      socketReference.current.readyState !== WebSocket.CLOSED
    ) {
      debugLog(
        "⚠️ DIAGNOSTIC: Existing socket state",
        socketReference.current.readyState,
        "→ will proceed to open new socket",
      );
    }

    if (
      socketReference.current &&
      socketReference.current.readyState < WebSocket.CLOSING
    ) {
      debugLog(
        "⚠️ DIAGNOSTIC: Closing existing socket before creating new one",
      );
      socketReference.current.close();
    }

    debugLog(
      "⚠️ DIAGNOSTIC: Creating fresh WebSocket instance to " + websocketUrl,
    );

    // Reset handshake filter for new connection
    handshakeFilterState.current = createHandshakeFilterState();
    debugLog("⚠️ DIAGNOSTIC: Reset handshake filter for new connection");

    // Track when connection attempts started and set timer only once
    if (!connectionStartTime) {
      setConnectionStartTime(Date.now());

      // Only start timer once on the first connection attempt
      clearInstallInstructionsTimer();
      installInstructionsTimerReference.current = setTimeout(() => {
        setShowInstallInstructions(true);
      }, SHOW_INSTALL_AFTER_MS);
    }

    updateConnectionStatusAndExpose(
      grIsCancelledState() || grIsMaxAttemptsReached()
        ? "disconnected"
        : grGetAttempts() > 0
          ? "reconnecting"
          : "connecting",
    );
    startConnectingAnimation(grGetAttempts() > 0);

    const newSocket = new WebSocket(websocketUrl);
    debugLog(
      `⚠️ DIAGNOSTIC: New WebSocket created with ID: ${Math.random().toString(36).slice(2, 10)}`,
    );

    (globalThis as any).ablyCliSocket = newSocket; // For E2E tests
    socketReference.current = newSocket; // Use ref for listeners
    setSocket(newSocket); // Trigger effect to add listeners

    // Reset the per-cycle guard now that we have started a *fresh* connection
    // attempt.  Any failure events for this socket may schedule (at most) one
    // reconnect.
    reconnectScheduledThisCycleReference.current = false;

    // Set up connection timeout
    clearConnectionTimeout(); // Clear any existing timeout
    connectionTimeoutReference.current = setTimeout(() => {
      debugLog(
        "⚠️ CONNECTION TIMEOUT: WebSocket connection attempt timed out after",
        CONNECTION_TIMEOUT_MS,
        "ms",
      );

      // Close the socket if it's still connecting
      if (
        socketReference.current &&
        socketReference.current.readyState === WebSocket.CONNECTING
      ) {
        debugLog(
          "⚠️ CONNECTION TIMEOUT: Closing socket that is still in CONNECTING state",
        );
        socketReference.current.close(4003, "connection-timeout");

        // Manually trigger error handling since the browser might not fire events for a stuck connection
        const timeoutError = new Event("error");
        Object.defineProperty(timeoutError, "message", {
          value: "Connection timeout",
        });
        Object.defineProperty(timeoutError, "isTimeout", { value: true });
        socketReference.current.dispatchEvent(timeoutError);
      }
    }, CONNECTION_TIMEOUT_MS);

    // new WebSocket created
    debugLog(
      "⚠️ DIAGNOSTIC: WebSocket connection initiation complete. sessionId:",
      sessionId,
      "showManualReconnectPrompt:",
      showManualReconnectPromptReference.current,
    );

    return;
  }, [
    websocketUrl,
    updateConnectionStatusAndExpose,
    startConnectingAnimation,
    isVisible,
    sessionId,
    showManualReconnectPromptReference,
    clearConnectionTimeout,
    connectionStartTime,
    clearInstallInstructionsTimer,
    term,
  ]);

  const socketReference = useRef<WebSocket | null>(null); // Ref to hold the current socket for cleanup

  const additionalEnvironmentVariables: Record<string, string> = {};
  if (ablyEndpoint) {
    debugLog(`⚠️ DIAGNOSTIC: Setting ABLY_ENDPOINT to "${ablyEndpoint}"`);
    additionalEnvironmentVariables["ABLY_ENDPOINT"] = ablyEndpoint;
  }
  if (ablyControlHost) {
    debugLog(
      `⚠️ DIAGNOSTIC: Setting ABLY_CONTROL_HOST to "${ablyControlHost}"`,
    );
    additionalEnvironmentVariables["ABLY_CONTROL_HOST"] = ablyControlHost;
  }

  const handleWebSocketOpen = useCallback(() => {
    // console.log('[AblyCLITerminal] WebSocket opened');
    // Clear connection timeout since we successfully connected
    clearConnectionTimeout();

    // Do not reset reconnection attempts here; wait until terminal prompt confirms full session
    setShowManualReconnectPrompt(false);

    // Only clear buffer for new sessions, not when resuming
    if (!sessionId) {
      clearPtyBuffer(); // Clear buffer for new session prompt detection
      debugLog(`⚠️ DIAGNOSTIC: Cleared PTY buffer for new session`);
    } else {
      debugLog(
        `⚠️ DIAGNOSTIC: Skipping PTY buffer clear for resumed session ${sessionId}`,
      );
      // For resumed sessions, we might already be at a prompt
      // Check if we need to activate the session immediately
      if (
        connectionStatusReference.current === "connected" &&
        !isSessionActiveReference.current
      ) {
        debugLog(
          `⚠️ DIAGNOSTIC: Resumed session but not active - checking for existing prompt`,
        );
      }
    }

    debugLog(
      "⚠️ DIAGNOSTIC: WebSocket open handler started - tracking initialization sequence",
    );

    if (term.current) {
      debugLog("⚠️ DIAGNOSTIC: Focusing terminal");
      term.current.focus();
      // Don't send the initial command yet - wait for prompt detection
    }

    // Send auth payload - but no additional data
    const payload = createAuthPayload(
      ablyApiKey,
      ablyAccessToken,
      sessionId,
      additionalEnvironmentVariables,
    );

    debugLog(
      `⚠️ DIAGNOSTIC: Preparing to send auth payload with env vars: ${JSON.stringify(payload.environmentVariables)}`,
    );
    debugLog(
      `⚠️ DIAGNOSTIC: Auth payload includes sessionId: ${payload.sessionId || "none (new session)"}`,
    );

    if (
      socketReference.current &&
      socketReference.current.readyState === WebSocket.OPEN
    ) {
      debugLog("⚠️ DIAGNOSTIC: Sending auth payload to server");
      socketReference.current.send(JSON.stringify(payload));
    }

    // Set up initial command to be sent when prompt is detected
    // Skip initial command if we're resuming an existing session
    if (initialCommand && !sessionId) {
      debugLog(
        `⚠️ DIAGNOSTIC: Initial command present: "${initialCommand}" - will be sent when prompt is detected`,
      );
      pendingInitialCommandReference.current = initialCommand;
    } else if (initialCommand && sessionId) {
      debugLog(
        `⚠️ DIAGNOSTIC: Skipping initial command for resumed session ${sessionId}`,
      );
    } else if (!initialCommand) {
      debugLog("⚠️ DIAGNOSTIC: No initial command provided");
    }

    // persistence handled by dedicated useEffect
    debugLog("WebSocket OPEN handler completed. sessionId:", sessionId);
  }, [
    clearAnimationMessages,
    ablyAccessToken,
    ablyApiKey,
    initialCommand,
    updateConnectionStatusAndExpose,
    clearPtyBuffer,
    sessionId,
    resumeOnReload,
    clearConnectionTimeout,
    credentialHash,
  ]);

  const handleWebSocketMessage = useCallback(
    async (event: MessageEvent) => {
      debugLog(
        `⚠️ DIAGNOSTIC: handleWebSocketMessage called with event.data type: ${typeof event.data}`,
      );
      try {
        const data = await messageDataToUint8Array(event.data);

        const message = parseControlMessage(data);
        if (message) {
          // Handle control messages

          // Handle control messages using the extracted handler
          handleControlMessage(message);
          return;
        }

        // Everything else is terminal output (including --json command results)
        // Convert back to string for terminal display
        const dataString = new TextDecoder().decode(data);
        debugLog(
          `⚠️ DIAGNOSTIC: Processing as terminal output: "${dataString}"`,
        );

        // Filter Docker handshake JSON using the shared buffering logic
        const filteredData = filterDockerHandshake(
          dataString,
          handshakeFilterState.current,
        );
        debugLog(`⚠️ DIAGNOSTIC: After filtering: "${filteredData}"`);

        // Only write and process if we have data after filtering
        if (filteredData.length > 0) {
          debugLog(
            `⚠️ DIAGNOSTIC: Filtered data received, length: ${filteredData.length}`,
          );

          // Check for text-based control messages (e.g., from proxies that strip binary prefixes)
          if (filteredData.includes("ABLY_CTRL:")) {
            // Process the data to extract control messages and regular output
            let regularOutput = "";
            let currentPos = 0;

            while (currentPos < filteredData.length) {
              const ctrlIndex = filteredData.indexOf("ABLY_CTRL:", currentPos);

              if (ctrlIndex === -1) {
                // No more control messages, append the rest
                regularOutput += filteredData.slice(Math.max(0, currentPos));
                break;
              }

              // Append any text before the control message
              if (ctrlIndex > currentPos) {
                regularOutput += filteredData.substring(currentPos, ctrlIndex);
              }

              // Find the end of the control message (either newline or end of string)
              let messageEnd = filteredData.indexOf("\n", ctrlIndex);
              if (messageEnd === -1)
                messageEnd = filteredData.indexOf("\r", ctrlIndex);
              if (messageEnd === -1) messageEnd = filteredData.length;

              // Extract the control message
              const ctrlLine = filteredData.substring(ctrlIndex, messageEnd);

              try {
                const jsonString = ctrlLine.slice("ABLY_CTRL:".length);
                const message_ = JSON.parse(jsonString);
                debugLog(
                  `⚠️ DIAGNOSTIC: Found text-based control message:`,
                  message_,
                );

                // Process the control message using the extracted handler
                handleControlMessage(message_);
              } catch (error) {
                console.warn(
                  "[WebSocket] Failed to parse text-based control message:",
                  error,
                );
              }

              // Move past this control message
              currentPos = messageEnd;
              // Skip the newline if present
              if (
                currentPos < filteredData.length &&
                (filteredData[currentPos] === "\n" ||
                  filteredData[currentPos] === "\r")
              ) {
                if (
                  filteredData[currentPos] === "\r" &&
                  currentPos + 1 < filteredData.length &&
                  filteredData[currentPos + 1] === "\n"
                ) {
                  currentPos += 2; // Skip \r\n
                } else {
                  currentPos += 1; // Skip single \n or \r
                }
              }
            }

            // Write the regular output to terminal (without control messages)
            if (regularOutput && term.current) {
              term.current.write(regularOutput);
            }
          } else {
            // No control messages, write filtered data as-is
            if (term.current) {
              term.current.write(filteredData);
            }
          }

          // Always process the data for prompt detection
          handlePtyData(filteredData);
        } else if (handshakeFilterState.current.handshakeHandled) {
          // If handshake was just handled and no data remains, still process empty string
          // to ensure any state updates happen
          handlePtyData("");
        }
      } catch (error) {
        console.error("[AblyCLITerminal] Error processing message:", error);
      }
    },
    [
      handlePtyData,
      onSessionEnd,
      updateConnectionStatusAndExpose,
      updateSessionActive,
      credentialHash,
      resumeOnReload,
      sessionId,
    ],
  );

  const handleWebSocketError = useCallback(
    (event: Event) => {
      console.error("[AblyCLITerminal] WebSocket error event received:", event);
      // Clear connection timeout on error
      clearConnectionTimeout();

      // Add more details if possible, though Event object is generic
      if (event instanceof ErrorEvent) {
        console.error(
          `[AblyCLITerminal] WebSocket ErrorEvent: message=${event.message}, filename=${event.filename}, lineno=${event.lineno}, colno=${event.colno}`,
        );
      }

      // Check if max attempts reached or cancelled
      if (grIsCancelledState() || grIsMaxAttemptsReached()) {
        // Clear any existing animations
        clearTerminalBoxOnly();
        updateConnectionStatusAndExpose("disconnected");

        if (term.current) {
          let message: ReturnType<typeof getConnectionMessage>;

          if (grIsMaxAttemptsReached()) {
            message = getConnectionMessage("maxReconnects");
          } else if (grIsCancelledState()) {
            message = getConnectionMessage("reconnectCancelled");
          } else if ((event as any).isTimeout) {
            message = getConnectionMessage("connectionTimeout");
          } else {
            message = getConnectionMessage("connectionFailed");
          }

          statusBoxReference.current = drawBox(
            term.current,
            boxColour.yellow,
            message.title,
            message.lines,
            60,
          );
          setOverlay({
            variant: "error",
            title: message.title,
            lines: message.lines,
          });
        }

        setShowManualReconnectPrompt(true);
        reconnectScheduledThisCycleReference.current = true; // Prevent double handling
        return;
      }

      if (!reconnectScheduledThisCycleReference.current) {
        // Immediately enter "reconnecting" state so countdown / spinner UI is active
        updateConnectionStatusAndExpose("reconnecting");

        console.log(
          "[AblyCLITerminal handleWebSocketError] Entered reconnection branch. isCancelled=",
          grIsCancelledState(),
          "maxReached=",
          grIsMaxAttemptsReached(),
        );
        // Browsers don't always fire a subsequent `close` event when the WebSocket
        // handshake itself fails (e.g. server down).  In that scenario our usual
        // reconnection logic in `handleWebSocketClose` never runs, so we need to
        // kick-off the retry sequence from here.

        debugLog(
          "[AblyCLITerminal handleWebSocketError] Triggering auto-reconnect sequence. Current grAttempts (before increment):",
          grGetAttempts(),
        );

        startConnectingAnimation(true);
        grIncrement();
        console.log(
          "[AblyCLITerminal handleWebSocketError] grIncrement done. Attempts now:",
          grGetAttempts(),
        );

        if (connectWebSocketReference.current) {
          console.log(
            "[AblyCLITerminal handleWebSocketError] Scheduling reconnect...",
          );
          grScheduleReconnect(connectWebSocketReference.current!, websocketUrl);
        } else {
          console.error(
            "[AblyCLITerminal handleWebSocketError] connectWebSocketRef.current is null, cannot schedule reconnect!",
          );
        }

        // Mark that we have already handled scheduling for this cycle so the
        // forthcoming `close` event (which most browsers still emit after a
        // handshake failure) does NOT double-increment or re-schedule.
        reconnectScheduledThisCycleReference.current = true;
      }
    },
    [
      updateConnectionStatusAndExpose,
      startConnectingAnimation,
      websocketUrl,
      clearTerminalBoxOnly,
      clearConnectionTimeout,
    ],
  );

  const handleWebSocketClose = useCallback(
    (event: CloseEvent) => {
      debugLog(
        `[AblyCLITerminal] WebSocket closed. Code: ${event.code}, Reason: ${event.reason}, Clean: ${event.wasClean}`,
      );
      clearConnectionTimeout(); // Clear timeout on close
      clearTerminalBoxOnly();
      updateSessionActive(false);

      // Check if this was a user-initiated close
      const userClosedTerminal =
        event.reason === "user-closed-primary" ||
        event.reason === "user-closed-secondary" ||
        event.reason === "manual-reconnect";

      if (userClosedTerminal) {
        debugLog(
          `[AblyCLITerminal] User closed terminal: ${event.reason} - not reconnecting`,
        );
        return; // Don't try to reconnect if user closed the terminal intentionally
      }

      // Close codes that should *not* trigger automatic reconnection because
      // they represent explicit server-side rejections or client-initiated
      // terminations.  Codes such as 1005 (No Status) or 1006 (Abnormal
      // Closure) can legitimately occur when the server is temporarily
      // unreachable – for example when the terminal server is still
      // starting up.  Those cases should be treated as recoverable so they
      // are intentionally **excluded** from this list.
      const NON_RECOVERABLE_CLOSE_CODES = new Set<number>([
        4001, // Policy violation (e.g. invalid credentials)
        4008, // Token expired
        1013, // Try again later – the server is telling us not to retry
        4002, // Session resume rejected
        4000, // Generic server error
        4003, // Rate limit exceeded
        4004, // Unsupported protocol version
        4009, // Server at capacity
        // Note: 1005 removed - it's used for both graceful exit AND network disconnections
        // We should handle exit commands differently, not by close code
      ]);

      const inactivityRegex = /inactiv|timed out/i;
      if (event.code === 1000 && inactivityRegex.test(event.reason)) {
        NON_RECOVERABLE_CLOSE_CODES.add(1000);
      }

      if (NON_RECOVERABLE_CLOSE_CODES.has(event.code)) {
        grCancelReconnect();
        grResetState();
        updateConnectionStatusAndExpose("disconnected");
        if (term.current) {
          let message;
          if (
            event.code === 4009 ||
            event.reason?.toLowerCase().includes("capacity")
          ) {
            message = getConnectionMessage("capacityReached");
          } else if (
            event.code === 4003 ||
            event.reason?.toLowerCase().includes("rate limit")
          ) {
            message = {
              title: "RATE LIMIT EXCEEDED",
              lines: [
                "Too many connection attempts from your IP address.",
                event.reason || "Please wait before trying again.",
                "",
                "This limit helps ensure service availability for all users.",
              ],
            };
          } else {
            message = getConnectionMessage("serverDisconnect");
          }

          // Prepend the specific error code/reason to the first line if not already included
          const lines = [...message.lines];
          lines[0] = `Connection closed by server (${event.code})${event.reason ? `: ${event.reason}` : ""}.`;

          statusBoxReference.current = drawBox(
            term.current,
            boxColour.red,
            message.title,
            lines,
            60,
          );
          setOverlay({
            variant: "error",
            title: message.title,
            lines: lines,
            drawer: CLI_INSTALL_TIP,
          });
        }
        setShowManualReconnectPrompt(true);
        if (resumeOnReload && globalThis.window !== undefined) {
          const urlDomain = new URL(websocketUrl).host;
          globalThis.sessionStorage.removeItem(
            `ably.cli.sessionId.${urlDomain}`,
          );
          globalThis.sessionStorage.removeItem(
            `ably.cli.credentialHash.${urlDomain}`,
          );
          setSessionId(null);
        }
        debugLog(
          "[AblyCLITerminal] Purging sessionId due to non-recoverable close. code:",
          event.code,
          "sessionId:",
          sessionId,
        );
        return;
      }

      if (grIsCancelledState() || grIsMaxAttemptsReached()) {
        updateConnectionStatusAndExpose("disconnected");
        if (term.current) {
          let message: ReturnType<typeof getConnectionMessage>;

          if (grIsMaxAttemptsReached()) {
            message = getConnectionMessage("maxReconnects");
          } else if (grIsCancelledState()) {
            message = getConnectionMessage("reconnectCancelled");
          } else {
            message = getConnectionMessage("connectionFailed");
            // Override first line with specific error details
            const lines = [...message.lines];
            lines[0] = `Connection failed (Code: ${event.code}, Reason: ${event.reason || "N/A"}).`;
            message = { ...message, lines };
          }

          // Clear the terminal to remove any old content
          if (term.current) {
            term.current.clear();
          }
          statusBoxReference.current = drawBox(
            term.current,
            boxColour.yellow,
            message.title,
            message.lines,
            60,
          );
          setOverlay({
            variant: "error",
            title: message.title,
            lines: message.lines,
            drawer: CLI_INSTALL_TIP,
          });
        }
        setShowManualReconnectPrompt(true);
        return;
      } else if (!reconnectScheduledThisCycleReference.current) {
        debugLog(
          "[AblyCLITerminal handleWebSocketClose] Scheduling reconnect. Current grAttempts (before increment):",
          grGetAttempts(),
        );
        updateConnectionStatusAndExpose("reconnecting");
        startConnectingAnimation(true);

        grIncrement();
        debugLog(
          "[AblyCLITerminal handleWebSocketClose] grIncrement called. Current grAttempts (after increment):",
          grGetAttempts(),
        );

        if (connectWebSocketReference.current) {
          grScheduleReconnect(connectWebSocketReference.current!, websocketUrl);
        } else {
          console.error(
            "[AblyCLITerminal handleWebSocketClose] connectWebSocketRef.current is null, cannot schedule reconnect!",
          );
        }

        // Prevent any (unlikely) duplicate scheduling from other late events
        reconnectScheduledThisCycleReference.current = true;
      }
    },
    [
      startConnectingAnimation,
      updateConnectionStatusAndExpose,
      updateSessionActive,
      clearTerminalBoxOnly,
      websocketUrl,
      resumeOnReload,
      sessionId,
      clearConnectionTimeout,
    ],
  );

  useEffect(() => {
    // Setup terminal
    if (!term.current && rootReference.current) {
      // initializing terminal instance
      debugLog("[AblyCLITerminal] Initializing Terminal instance.");
      debugLog("⚠️ DIAGNOSTIC: Creating new Terminal instance");
      term.current = createTerminal();
      fitAddon.current = createFitAddon();
      term.current.loadAddon(fitAddon.current);

      // Track current input line for autocomplete
      let currentInputLine = "";
      let cursorPosition = 0;

      // Attach custom key handler for special keys
      debugLog("⚠️ DIAGNOSTIC: Setting up custom key handler for special keys");
      if (typeof term.current.attachCustomKeyEventHandler === "function") {
        term.current.attachCustomKeyEventHandler(
          (event: KeyboardEvent): boolean => {
            // Only handle special keys when connected and session is active
            if (
              !isSessionActive ||
              !socketReference.current ||
              socketReference.current.readyState !== WebSocket.OPEN
            ) {
              return true; // Let xterm handle it normally
            }

            debugLog(
              `⚠️ DIAGNOSTIC: KeyboardEvent - key: "${event.key}", code: "${event.code}", ctrl: ${event.ctrlKey}, shift: ${event.shiftKey}`,
            );

            // Handle TAB for autocomplete
            if (event.key === "Tab" && !event.ctrlKey && !event.altKey) {
              event.preventDefault();
              debugLog(
                `⚠️ DIAGNOSTIC: TAB intercepted, sending special message for autocomplete`,
              );

              // Send special message for autocomplete
              socketReference.current.send(
                JSON.stringify({
                  type: "readline-control",
                  action: "complete",
                  line: currentInputLine,
                  cursor: cursorPosition,
                }),
              );

              return false; // Prevent default handling
            }

            // Handle UP arrow for history
            if (event.key === "ArrowUp" && !event.ctrlKey && !event.altKey) {
              event.preventDefault();
              debugLog(
                `⚠️ DIAGNOSTIC: UP arrow intercepted, sending special message for history`,
              );

              // Send special message for history navigation
              socketReference.current.send(
                JSON.stringify({
                  type: "readline-control",
                  action: "history-up",
                }),
              );

              return false; // Prevent default handling
            }

            // Handle DOWN arrow for history
            if (event.key === "ArrowDown" && !event.ctrlKey && !event.altKey) {
              event.preventDefault();
              debugLog(
                `⚠️ DIAGNOSTIC: DOWN arrow intercepted, sending special message for history`,
              );

              // Send special message for history navigation
              socketReference.current.send(
                JSON.stringify({
                  type: "readline-control",
                  action: "history-down",
                }),
              );

              return false; // Prevent default handling
            }

            // Handle Ctrl+R for history search
            if (
              event.key === "r" &&
              event.ctrlKey &&
              !event.altKey &&
              !event.shiftKey
            ) {
              event.preventDefault();
              debugLog(
                `⚠️ DIAGNOSTIC: Ctrl+R intercepted, sending special message for history search`,
              );

              // Send special message for history search
              socketReference.current.send(
                JSON.stringify({
                  type: "readline-control",
                  action: "history-search",
                }),
              );

              return false; // Prevent default handling
            }

            return true; // Let other keys pass through normally
          },
        );
      }

      debugLog("⚠️ DIAGNOSTIC: Setting up onData handler");
      term.current.onData((data: string) => {
        // Enhanced logging for special keys
        const bytes = [...data]
          .map((char) => {
            const code = char.charCodeAt(0);
            if (code < 32 || code > 126) {
              return `\\x${code.toString(16).padStart(2, "0")}`;
            }
            return char;
          })
          .join("");

        // Identify common special keys
        let keyName = "unknown";
        switch (data) {
          case "\t":
          case "\u0009": {
            keyName = "TAB";
            break;
          }
          case "\u001B[A": {
            keyName = "UP_ARROW";
            break;
          }
          case "\u001B[B": {
            keyName = "DOWN_ARROW";
            break;
          }
          case "\u001B[C": {
            keyName = "RIGHT_ARROW";
            break;
          }
          case "\u001B[D": {
            keyName = "LEFT_ARROW";
            break;
          }
          case "\r": {
            keyName = "ENTER";
            break;
          }
          case "\u007F": {
            keyName = "BACKSPACE";
            break;
          }
          case "\u0012": {
            keyName = "CTRL+R";
            break;
          }
          default: {
            if (data.startsWith("\u001B")) keyName = "ESC_SEQUENCE";
          }
        }

        debugLog(
          `⚠️ DIAGNOSTIC: Terminal onData - Key: ${keyName}, Bytes: "${bytes}", Length: ${data.length}`,
        );

        // Special handling for Enter key
        if (data === "\r") {
          const latestStatus = connectionStatusReference.current;
          debugLog(
            `⚠️ DIAGNOSTIC: Enter key pressed, status: ${latestStatus}, reconnectPrompt: ${showManualReconnectPromptReference.current}`,
          );

          // Manual prompt visible: attempt manual reconnect even if an old socket is open
          if (showManualReconnectPromptReference.current) {
            // manual reconnect
            debugLog("[AblyCLITerminal] Enter pressed for manual reconnect.");
            // Clear overlay and prompt before initiating new connection
            clearAnimationMessages(); // removes spinner/box & overlay
            showManualReconnectPromptReference.current = false;
            setShowManualReconnectPrompt(false);

            // Forget previous session completely so no resume is attempted
            if (resumeOnReload && globalThis.window !== undefined) {
              const urlDomain = new URL(websocketUrl).host;
              globalThis.sessionStorage.removeItem(
                `ably.cli.sessionId.${urlDomain}`,
              );
              globalThis.sessionStorage.removeItem(
                `ably.cli.credentialHash.${urlDomain}`,
              );
            }
            setSessionId(null);

            // Ensure any lingering socket is fully closed before opening a new one
            if (
              socketReference.current &&
              socketReference.current.readyState !== WebSocket.CLOSED
            ) {
              try {
                socketReference.current.close(1000, "manual-reconnect");
              } catch {
                /* ignore */
              }
              socketReference.current = null; // Make sure the reference is cleared
            }

            // Give the browser a micro-task to mark socket CLOSED before reconnect
            setTimeout(() => {
              debugLog(
                "[AblyCLITerminal] [setTimeout] Starting fresh reconnect sequence",
              );
              grResetState();
              // Reset the attempt counter for manual reconnect
              grSuccessfulConnectionReset();
              clearPtyBuffer();

              // Reset connection tracking for fresh attempt
              setConnectionStartTime(null);
              setShowInstallInstructions(false);
              clearInstallInstructionsTimer();

              debugLog(
                "[AblyCLITerminal] [setTimeout] Invoking latest connectWebSocket",
              );
              connectWebSocketReference.current?.();
              debugLog(
                "[AblyCLITerminal] [setTimeout] connectWebSocket invoked",
              );

              // We reset attempts to 0 – explicitly show a fresh CONNECTING overlay
              startConnectingAnimation(false);
            }, 20);
            debugLog(
              "[AblyCLITerminal] Enter pressed for manual reconnect. sessionId:",
              sessionId,
            );
            return;
          }

          // Cancel ongoing auto-reconnect
          if (latestStatus === "reconnecting" && !grIsCancelledState()) {
            // user cancelled reconnect
            debugLog(
              "[AblyCLITerminal] Enter pressed during auto-reconnect: Cancelling.",
            );
            grCancelReconnect();
            grResetState();
            clearAnimationMessages();

            // Reset connection tracking
            setConnectionStartTime(null);
            setShowInstallInstructions(false);
            clearInstallInstructionsTimer();

            if (term.current) {
              const message = getConnectionMessage("reconnectCancelled");
              const terminal = term.current;
              terminal.writeln(`\r\n`);
              // Display the reconnect cancelled message in the terminal
              message.lines.forEach((line) => {
                if (line) terminal.writeln(line);
              });
            }
            showManualReconnectPromptReference.current = true;
            setShowManualReconnectPrompt(true);
            updateConnectionStatusAndExpose("disconnected");
            return;
          }
        }

        // Track input line for autocomplete (simple tracking - reset on Enter)
        if (data === "\r") {
          currentInputLine = "";
          cursorPosition = 0;
        } else if (data === "\u007F") {
          // Backspace
          if (cursorPosition > 0) {
            currentInputLine =
              currentInputLine.slice(0, cursorPosition - 1) +
              currentInputLine.slice(cursorPosition);
            cursorPosition--;
          }
        } else if (
          data.length === 1 &&
          data.charCodeAt(0) >= 32 &&
          data.charCodeAt(0) <= 126
        ) {
          // Regular printable character
          currentInputLine =
            currentInputLine.slice(0, cursorPosition) +
            data +
            currentInputLine.slice(cursorPosition);
          cursorPosition++;
        }

        // Default: forward data to server if socket open
        if (
          socketReference.current &&
          socketReference.current.readyState === WebSocket.OPEN
        ) {
          debugLog(
            `⚠️ DIAGNOSTIC: Sending to WebSocket - Key: ${keyName}, Bytes: "${bytes}"`,
          );
          socketReference.current.send(data);
        } else if (data === "\r") {
          debugLog(
            `⚠️ DIAGNOSTIC: Socket not open, not sending carriage return`,
          );
          // If the connection is not open and none of the above special cases matched,
          // do nothing (prevent accidental writes to closed socket).
        } else {
          debugLog(
            `⚠️ DIAGNOSTIC: Socket not open, and not a carriage return, ignoring input`,
          );
        }
      });

      debugLog("⚠️ DIAGNOSTIC: Opening terminal in DOM element");
      term.current.open(rootReference.current);
      try {
        // Do the initial fit only
        debugLog("⚠️ DIAGNOSTIC: Performing initial terminal fit");
        fitAddon.current.fit();

        // Initial timeout fit for edge cases
        setTimeout(() => {
          try {
            debugLog("⚠️ DIAGNOSTIC: Performing delayed terminal fit");
            fitAddon.current?.fit();
          } catch (error) {
            console.warn("Error fitting addon initial timeout:", error);
          }
        }, 100);
      } catch (error) {
        console.error("Error during initial terminal fit:", error);
      }

      grSetCountdownCallback((remainingMs) => {
        // Only show countdown while we are actually waiting to reconnect
        if (connectionStatusReference.current !== "reconnecting") return;

        const seconds = Math.ceil(remainingMs / 1000);
        const messagePlain = `Next attempt in ${seconds}s...`;
        const messageWithCancel = `${messagePlain}  (Press ⏎ to cancel)`;
        setCountdownMessage(messagePlain);

        if (
          term.current &&
          statusBoxReference.current &&
          statusBoxReference.current.content.length > 1
        ) {
          // For terminal box, show colored version
          updateLine(
            statusBoxReference.current,
            1,
            messageWithCancel,
            boxColour.magenta,
          );
        }

        // Update overlay - preserve the drawer if present
        setOverlay((previous) => {
          if (!previous) return previous;
          const newLines = [...previous.lines];

          // Simply update line 1 with the countdown - the structure is already set up correctly
          if (newLines.length === 1) {
            newLines.push(messageWithCancel);
          } else {
            newLines[1] = messageWithCancel;
          }

          // Preserve drawer or add it if showInstallInstructions is true
          return {
            ...previous,
            lines: newLines,
            ...(showInstallInstructions
              ? {
                  drawer: CLI_INSTALL_TIP,
                }
              : { drawer: previous.drawer }),
          };
        });
      });
    }

    // Set max reconnect attempts if provided
    if (maxReconnectAttempts && maxReconnectAttempts !== grGetMaxAttempts()) {
      debugLog(
        "[AblyCLITerminal] Setting max reconnect attempts to",
        maxReconnectAttempts,
      );
      grSetMaxAttempts(maxReconnectAttempts);
    }

    // Initial connection on mount - do NOT connect here, let the dedicated connection effects handle it
    // This prevents duplicate connections from multiple effects running in the same render cycle

    // Cleanup terminal on unmount
    return () => {
      // Execute resize listener cleanup if it exists
      if (termCleanupReference.current) {
        termCleanupReference.current();
      }

      if (term.current) {
        // dispose terminal
        debugLog("[AblyCLITerminal] Disposing Terminal on unmount");
        term.current.dispose();
        term.current = null;
      }
      if (
        socketReference.current &&
        socketReference.current.readyState < WebSocket.CLOSING
      ) {
        // close websocket with code 4001 to signal intentional close
        // This tells the server to cleanup immediately (no grace period)
        debugLog("[AblyCLITerminal] Closing WebSocket on unmount.");
        socketReference.current.close(4001, "user-closed-panel");
      }
      grResetState(); // Ensure global state is clean
      clearConnectionTimeout(); // Clear any pending connection timeout
    };
  }, []); // Empty deps - this effect only runs once on mount to initialize the terminal

  // Single unified effect for initial connection (handles both mount and visibility changes)
  // When resumeOnReload is enabled, waits for credentialsInitialized to ensure sessionId restoration completes first
  useEffect(() => {
    if (componentConnectionStatus !== "initial") return; // already attempted
    if (!isVisible) return; // not visible yet

    // If resumeOnReload is enabled, wait for credentials to be initialized first
    if (resumeOnReload && !credentialsInitialized) return;

    if (maxReconnectAttempts && maxReconnectAttempts !== grGetMaxAttempts()) {
      grSetMaxAttempts(maxReconnectAttempts);
    }

    grResetState();
    clearPtyBuffer();
    connectWebSocket();
  }, [
    isVisible,
    credentialsInitialized,
    maxReconnectAttempts,
    componentConnectionStatus,
    clearPtyBuffer,
    connectWebSocket,
    // resumeOnReload is intentionally omitted - it's a prop that doesn't change during component lifecycle
  ]);

  useEffect(() => {
    // Expose a debug function to get current component state for Playwright
    (globalThis as any).getAblyCliTerminalReactState = () => ({
      componentConnectionStatus,
      isSessionActive,
      connectionHelpMessage,
      reconnectAttemptMessage,
      countdownMessage,
      showManualReconnectPrompt,
      grCurrentAttempts: grGetAttempts(),
      grIsCancelled: grIsCancelledState(),
      grIsMaxReached: grIsMaxAttemptsReached(),
    });

    // Expose a function to get terminal buffer content for testing
    (globalThis as any).getTerminalBufferText = () => {
      if (!term.current) return "";
      const buffer = term.current.buffer.active;
      let text = "";
      for (let index = 0; index < buffer.length; index++) {
        const line = buffer.getLine(index);
        if (line) {
          text += line.translateToString(true) + "\n";
        }
      }
      return text.trimEnd();
    };

    // Expose terminal buffer info for debugging
    (globalThis as any).getTerminalBufferInfo = () => {
      if (!term.current) return { exists: false };
      const buffer = term.current.buffer.active;
      return {
        exists: true,
        length: buffer.length,
        cursorY: buffer.cursorY,
        cursorX: buffer.cursorX,
        baseY: buffer.baseY,
        trimmedLength: buffer.length - buffer.baseY,
      };
    };

    return () => {
      delete (globalThis as any).getAblyCliTerminalReactState;
      delete (globalThis as any).getTerminalBufferText;
      delete (globalThis as any).getTerminalBufferInfo;
    };
  }, [
    componentConnectionStatus,
    isSessionActive,
    connectionHelpMessage,
    reconnectAttemptMessage,
    countdownMessage,
    showManualReconnectPrompt,
  ]); // Update whenever these state variables change

  useEffect(() => {
    // Effect for managing WebSocket event listeners
    if (socket) {
      // attach socket listeners
      debugLog(
        "[AblyCLITerminal] New socket detected, attaching event listeners.",
      );
      socket.addEventListener("open", handleWebSocketOpen);
      socket.addEventListener("message", handleWebSocketMessage);
      socket.addEventListener("close", handleWebSocketClose);
      socket.addEventListener("error", handleWebSocketError);

      return () => {
        // cleanup old socket listeners
        debugLog(
          "[AblyCLITerminal] Cleaning up WebSocket event listeners for old socket.",
        );
        socket.removeEventListener("open", handleWebSocketOpen);
        socket.removeEventListener("message", handleWebSocketMessage);
        socket.removeEventListener("close", handleWebSocketClose);
        socket.removeEventListener("error", handleWebSocketError);
      };
    }
  }, [
    socket,
    handleWebSocketOpen,
    handleWebSocketMessage,
    handleWebSocketClose,
    handleWebSocketError,
  ]);

  // Persist sessionId to sessionStorage whenever it changes (if enabled)
  useEffect(() => {
    if (!resumeOnReload || globalThis.window === undefined) return;
    // Only persist if we have validated credentials
    if (!credentialsInitialized) return;

    const urlDomain = new URL(websocketUrl).host;
    if (sessionId) {
      globalThis.sessionStorage.setItem(
        `ably.cli.sessionId.${urlDomain}`,
        sessionId,
      );
      // Also store credential hash if available
      if (credentialHash) {
        globalThis.sessionStorage.setItem(
          `ably.cli.credentialHash.${urlDomain}`,
          credentialHash,
        );
      }
    } else {
      globalThis.sessionStorage.removeItem(`ably.cli.sessionId.${urlDomain}`);
      globalThis.sessionStorage.removeItem(
        `ably.cli.credentialHash.${urlDomain}`,
      );
    }
  }, [
    sessionId,
    resumeOnReload,
    credentialsInitialized,
    websocketUrl,
    credentialHash,
  ]);

  // Debug: log layout metrics when an overlay is rendered
  useEffect(() => {
    if (overlay && rootReference.current) {
      // Wait till next tick to ensure DOM rendered
      requestAnimationFrame(() => {
        try {
          const _rootRect = rootReference.current?.getBoundingClientRect();
          const _parentRect =
            rootReference.current?.parentElement?.getBoundingClientRect();
          const overlayElement = rootReference.current?.querySelector(
            ".ably-overlay",
          ) as HTMLElement | null;
          const _overlayRect = overlayElement?.getBoundingClientRect();

          // layout diagnostics removed
        } catch (error) {
          // Swallow errors silently in production but log in dev
          console.error("Overlay diagnostics error", error);
        }
      });
    }
  }, [overlay]);

  // -----------------------------------------------------------------------------------
  // Visibility & inactivity timer logic
  // -----------------------------------------------------------------------------------

  const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
  const inactivityTimerReference = useRef<ReturnType<typeof setTimeout> | null>(
    null,
  );

  const clearInactivityTimer = useCallback(() => {
    if (inactivityTimerReference.current) {
      clearTimeout(inactivityTimerReference.current);
      inactivityTimerReference.current = null;
    }
  }, []);

  const startInactivityTimer = useCallback(() => {
    clearInactivityTimer();
    inactivityTimerReference.current = setTimeout(() => {
      // Auto-terminate session due to prolonged invisibility
      if (
        socketReference.current &&
        socketReference.current.readyState === WebSocket.OPEN
      ) {
        socketReference.current.close(4002, "inactivity-timeout");
      }
      // Inform the user inside the terminal UI
      if (term.current) {
        term.current.writeln(
          `\r\nSession terminated after ${INACTIVITY_TIMEOUT_MS / 60_000} minutes of inactivity.`,
        );
        term.current.writeln("Press ⏎ to start a new session.");
      }
      grCancelReconnect();
      grResetState();
      setShowManualReconnectPrompt(true);
      showManualReconnectPromptReference.current = true;
      updateConnectionStatusAndExpose("disconnected");
    }, INACTIVITY_TIMEOUT_MS);
  }, [
    INACTIVITY_TIMEOUT_MS,
    grCancelReconnect,
    grResetState,
    updateConnectionStatusAndExpose,
  ]);

  // Manage the timer whenever visibility changes
  useEffect(() => {
    if (isVisible) {
      clearInactivityTimer();
      return;
    }
    // If not visible start countdown only if there is an active/open socket
    if (
      socketReference.current &&
      socketReference.current.readyState === WebSocket.OPEN
    ) {
      startInactivityTimer();
    }
  }, [isVisible, startInactivityTimer, clearInactivityTimer]);

  useEffect(() => () => clearInactivityTimer(), [clearInactivityTimer]);

  // Cleanup install instructions timer on unmount
  useEffect(
    () => () => clearInstallInstructionsTimer(),
    [clearInstallInstructionsTimer],
  );

  // Initialize session and validate credentials
  useEffect(() => {
    const initializeSession = async () => {
      // Calculate current credential hash
      const currentHash = await hashCredentials(ablyApiKey, ablyAccessToken);
      setCredentialHash(currentHash);

      if (!resumeOnReload || globalThis.window === undefined) {
        setCredentialsInitialized(true);
        return;
      }

      // Extract domain from websocketUrl for scoping
      const urlDomain = new URL(websocketUrl).host;

      // Check if we have a stored session for this specific domain
      const storedSessionId = globalThis.sessionStorage.getItem(
        `ably.cli.sessionId.${urlDomain}`,
      );
      const storedHash = globalThis.sessionStorage.getItem(
        `ably.cli.credentialHash.${urlDomain}`,
      );

      console.log("[AblyCLITerminal] Credential validation:", {
        urlDomain,
        storedSessionId,
        storedHash,
        currentHash,
        match: storedHash === currentHash,
      });

      // Only restore session if credentials match AND it's for the same domain
      if (storedSessionId && storedHash === currentHash) {
        debugLog(
          `⚠️ DIAGNOSTIC: Restoring sessionId ${storedSessionId} from sessionStorage`,
        );
        setSessionId(storedSessionId);
        console.log(
          "[AblyCLITerminal] Restored session with matching credentials for domain:",
          urlDomain,
        );
      } else if (
        (storedSessionId || storedHash) &&
        storedHash !== currentHash
      ) {
        // Clear invalid session - either if we have a sessionId with mismatched hash
        // or if we have a stored hash that doesn't match current credentials
        globalThis.sessionStorage.removeItem(`ably.cli.sessionId.${urlDomain}`);
        globalThis.sessionStorage.removeItem(
          `ably.cli.credentialHash.${urlDomain}`,
        );
        console.log(
          "[AblyCLITerminal] Cleared session due to credential mismatch for domain:",
          urlDomain,
        );
      }

      setCredentialsInitialized(true);
      setSessionIdInitialized(true);
      debugLog(
        `⚠️ DIAGNOSTIC: Credentials initialized, restored sessionId: ${storedSessionId || "none"}`,
      );
    };

    initializeSession();
  }, [ablyApiKey, ablyAccessToken, resumeOnReload, websocketUrl]);

  // Store credential hash when it becomes available if we already have a sessionId
  useEffect(() => {
    if (
      resumeOnReload &&
      globalThis.window !== undefined &&
      sessionId &&
      credentialHash
    ) {
      const urlDomain = new URL(websocketUrl).host;
      const storedHash = globalThis.sessionStorage.getItem(
        `ably.cli.credentialHash.${urlDomain}`,
      );

      // Only store if we don't already have it stored
      if (!storedHash) {
        globalThis.sessionStorage.setItem(
          `ably.cli.credentialHash.${urlDomain}`,
          credentialHash,
        );
        debugLog("Stored credential hash for existing session");
      }
    }
  }, [resumeOnReload, sessionId, credentialHash, websocketUrl]);

  // Keep latest instance of connectWebSocket for async callbacks
  const connectWebSocketReference = useRef(connectWebSocket);
  useEffect(() => {
    connectWebSocketReference.current = connectWebSocket;
  }, [connectWebSocket]);

  // -------------------------------------------------------------
  // Resizable panes logic
  // -------------------------------------------------------------

  // Start dragging the divider
  const handleDragStart = useCallback((e: React.MouseEvent) => {
    e.preventDefault();
    setIsDragging(true);
  }, []);

  // Handle mouse movement while dragging
  const handleDrag = useCallback(
    (e: MouseEvent) => {
      if (!isDragging || !outerContainerReference.current) return;

      const containerRect =
        outerContainerReference.current.getBoundingClientRect();
      const containerWidth = containerRect.width;
      const mouseX = e.clientX - containerRect.left;

      // Calculate percentage position (0-100)
      let newPosition = (mouseX / containerWidth) * 100;

      // Constrain to reasonable limits (10%-90%)
      newPosition = Math.max(10, Math.min(90, newPosition));

      setSplitPosition(newPosition);

      // Trigger resize event for terminals to adapt
      globalThis.dispatchEvent(new Event("resize"));
    },
    [isDragging],
  );

  // End dragging
  const handleDragEnd = useCallback(() => {
    if (!isDragging) return;

    setIsDragging(false);

    // Save split position to session storage if resume enabled
    if (resumeOnReload && globalThis.window !== undefined) {
      globalThis.sessionStorage.setItem(
        "ably.cli.splitPosition",
        splitPosition.toString(),
      );
    }

    // Ensure terminals resize properly after drag ends
    setTimeout(() => {
      globalThis.dispatchEvent(new Event("resize"));
    }, 50);
  }, [isDragging, resumeOnReload, splitPosition]);

  // Add/remove global mouse event listeners for drag
  useEffect(() => {
    if (isDragging) {
      globalThis.addEventListener("mousemove", handleDrag);
      globalThis.addEventListener("mouseup", handleDragEnd);
    }

    return () => {
      globalThis.removeEventListener("mousemove", handleDrag);
      globalThis.removeEventListener("mouseup", handleDragEnd);
    };
  }, [isDragging, handleDrag, handleDragEnd]);

  // Single resize handler for both terminals
  useEffect(() => {
    const handleGlobalResize = debounce(() => {
      try {
        if (term.current && fitAddon.current) {
          fitAddon.current.fit();
        }
        if (isSplit && secondaryTerm.current && secondaryFitAddon.current) {
          secondaryFitAddon.current.fit();
        }
      } catch (error) {
        console.warn("Error in global resize handler:", error);
      }
    }, 200);

    // Add resize listener
    window.addEventListener("resize", handleGlobalResize);

    // Initial resize
    setTimeout(() => {
      handleGlobalResize();
    }, 50);

    return () => {
      window.removeEventListener("resize", handleGlobalResize);
    };
  }, [isSplit]);

  // Handle storage of split state when it changes
  useEffect(() => {
    // Ensure the split state in sessionStorage always matches the component state
    if (resumeOnReload && globalThis.window !== undefined) {
      if (isSplit) {
        globalThis.sessionStorage.setItem("ably.cli.isSplit", "true");
        debugLog("[AblyCLITerminal] Setting isSplit=true in sessionStorage");
      } else {
        globalThis.sessionStorage.removeItem("ably.cli.isSplit");
        debugLog("[AblyCLITerminal] Removed isSplit from sessionStorage");

        // When exiting split mode, also clean up secondary session ID
        if (!secondarySessionId) {
          globalThis.sessionStorage.removeItem("ably.cli.secondarySessionId");
          debugLog(
            "[AblyCLITerminal] Removed secondarySessionId from sessionStorage",
          );
        }
      }
    }
  }, [isSplit, resumeOnReload, secondarySessionId]);

  // -------------------------------------------------------------
  // Split-screen Terminal Logic (Step 6.2 - Secondary session)
  // -------------------------------------------------------------

  // Store the latest connectSecondaryWebSocket in a ref to avoid effect re-runs
  const connectSecondaryWebSocketReference = useRef<(() => void) | null>(null);

  // Connect secondary terminal WebSocket
  const connectSecondaryWebSocket = useCallback(() => {
    // Skip if secondary terminal is not available
    if (!secondaryTerm.current || !secondaryRootReference.current) {
      return;
    }

    // Close existing socket if open
    if (
      secondarySocketReference.current &&
      secondarySocketReference.current.readyState < WebSocket.CLOSING
    ) {
      secondarySocketReference.current.close();
    }

    debugLog("[AblyCLITerminal] Creating secondary WebSocket instance");
    console.log(
      "[AblyCLITerminal] Secondary WebSocket connecting to:",
      websocketUrl,
    );

    // Update connection status
    updateSecondaryConnectionStatus("connecting");

    // Show connecting animation in secondary terminal
    if (
      secondaryTerm.current && // Only clear terminal if this is a new session (not resuming)
      !secondarySessionId
    ) {
      secondaryTerm.current.clear();
      // Store the current line position so we can clear it later
      showConnectingMessage(secondaryTerm.current);
    }

    // Reset handshake filter for new connection
    secondaryHandshakeFilterState.current = createHandshakeFilterState();
    debugLog(
      "[AblyCLITerminal] [Secondary] Reset handshake filter for new connection",
    );

    // Create new WebSocket
    const newSocket = new WebSocket(websocketUrl);
    secondarySocketReference.current = newSocket;
    setSecondarySocket(newSocket);

    // Set up event handlers - using inline functions since we can't easily reuse
    // the handlers from the primary terminal without significant refactoring

    // WebSocket open handler
    newSocket.addEventListener("open", () => {
      debugLog("[AblyCLITerminal] Secondary WebSocket opened");

      // Clear any reconnect prompt
      setSecondaryShowManualReconnectPrompt(false);
      secondaryShowManualReconnectPromptReference.current = false;

      if (secondaryTerm.current) {
        secondaryTerm.current.focus();
      }

      // Send auth payload - only include necessary data
      const payload = createAuthPayload(
        ablyApiKey,
        ablyAccessToken,
        secondarySessionId,
        additionalEnvironmentVariables,
      );

      if (newSocket.readyState === WebSocket.OPEN) {
        newSocket.send(JSON.stringify(payload));
      }

      // Set up initial command to be sent when prompt is detected
      // Skip initial command if we're resuming an existing session
      if (initialCommand && !secondarySessionId) {
        debugLog(
          `[AblyCLITerminal] [Secondary] Initial command present: "${initialCommand}" - will be sent when prompt is detected`,
        );
        pendingSecondaryInitialCommandReference.current = initialCommand;
      } else if (initialCommand && secondarySessionId) {
        debugLog(
          `[AblyCLITerminal] [Secondary] Skipping initial command for resumed session ${secondarySessionId}`,
        );
      }
    });

    // WebSocket message handler with binary framing support
    newSocket.addEventListener("message", async (event) => {
      try {
        const data = await messageDataToUint8Array(event.data);

        const message = parseControlMessage(data);
        if (message) {
          // Handle control messages
          if (
            message.type === "hello" &&
            typeof message.sessionId === "string"
          ) {
            debugLog(
              `[Secondary] Received hello. sessionId=${message.sessionId}`,
            );
            const previousSessionId = secondarySessionId;
            setSecondarySessionId(message.sessionId);

            // Persist to session storage if enabled
            if (resumeOnReload && globalThis.window !== undefined) {
              globalThis.sessionStorage.setItem(
                "ably.cli.secondarySessionId",
                message.sessionId,
              );
            }

            // Clear the "Connecting..." message and status box
            if (secondaryTerm.current) {
              clearConnectingMessage(secondaryTerm.current);
              secondaryTerm.current.focus();
            }
            clearSecondaryStatusDisplay();

            // Check if this is a resumed session
            const isResumedSession =
              previousSessionId !== null &&
              previousSessionId === message.sessionId;

            if (isResumedSession) {
              // For resumed sessions, activate immediately without waiting for prompt
              debugLog(
                `[Secondary] Resumed existing session ${message.sessionId} - activating immediately`,
              );
              updateSecondaryConnectionStatus("connected");

              if (!isSecondarySessionActive) {
                activateSecondarySessionAndSendCommand();
              }
            } else {
              // For new sessions, wait for prompt detection
              debugLog(
                `[Secondary] New session ${message.sessionId} - waiting for prompt before activating`,
              );
              updateSecondaryConnectionStatus("connected");
            }

            return;
          }
          if (message.type === "status") {
            debugLog(
              `[Secondary] Received server status message: ${message.payload}`,
            );

            if (message.payload === "connected") {
              // Clear any overlay when connected
              clearSecondaryStatusDisplay();

              // Clear the "Connecting..." message
              if (secondaryTerm.current) {
                clearConnectingMessage(secondaryTerm.current);
                secondaryTerm.current.focus();
              }

              // Check if we're resuming an existing session
              const isResuming = secondarySessionId !== null;

              if (isResuming) {
                // For resumed sessions, activate immediately
                debugLog(
                  `[Secondary] Resuming session ${secondarySessionId} - activating immediately`,
                );
                updateSecondaryConnectionStatus("connected");

                if (!isSecondarySessionActive) {
                  activateSecondarySessionAndSendCommand();
                }
              } else {
                // For new sessions, wait for prompt detection
                debugLog(
                  `[Secondary] New session - waiting for prompt before activating`,
                );
                updateSecondaryConnectionStatus("connected");

                // Start timeout fallback in case prompt is never detected
                clearSecondaryPromptDetectionTimeout();
                secondaryPromptDetectionTimeoutReference.current = setTimeout(
                  () => {
                    debugLog(
                      `[Secondary] Prompt detection timeout - activating session anyway after ${PROMPT_DETECTION_TIMEOUT_MS}ms`,
                    );
                    if (!isSecondarySessionActive) {
                      activateSecondarySessionAndSendCommand();
                    }
                  },
                  PROMPT_DETECTION_TIMEOUT_MS,
                );
              }

              return;
            }

            // Handle error & disconnected
            if (
              message.payload === "error" ||
              message.payload === "disconnected"
            ) {
              const reason =
                message.reason ||
                (message.payload === "error"
                  ? "Server error"
                  : "Server disconnected");
              if (secondaryTerm.current)
                secondaryTerm.current.writeln(
                  `\r\n--- ${message.payload === "error" ? "Error" : "Session Ended (from server)"}: ${reason} ---`,
                );
              updateSecondaryConnectionStatus(
                message.payload as ConnectionStatus,
              );

              if (secondaryTerm.current && message.payload === "disconnected") {
                const title = "ERROR: SERVER DISCONNECT";
                const message1 = `Connection closed by server (${message.code})${message.reason ? `: ${message.reason}` : ""}.`;
                const message2 = "";
                const message3 = `Press ⏎ to try reconnecting manually.`;

                if (secondaryTerm.current) {
                  secondaryStatusBoxReference.current = drawBox(
                    secondaryTerm.current,
                    boxColour.red,
                    title,
                    [message1, message2, message3],
                    60,
                  );
                  setSecondaryOverlay({
                    variant: "error",
                    title,
                    lines: [message1, message2, message3],
                  });
                }

                secondaryShowManualReconnectPromptReference.current = true;
                setSecondaryShowManualReconnectPrompt(true);
              }
              return;
            }
            return;
          }

          // Check for PTY stream/hijack meta-message
          if (message.stream === true && typeof message.hijack === "boolean") {
            debugLog(
              "[AblyCLITerminal] [Secondary] Received PTY meta-message. Ignoring.",
            );
            return;
          }

          // Control message was handled, return
          return;
        }

        // Not a control message - process as PTY data
        const dataString = new TextDecoder().decode(data);

        // Filter Docker handshake JSON using the shared buffering logic
        const filteredData = filterDockerHandshake(
          dataString,
          secondaryHandshakeFilterState.current,
        );

        // Only write if we have data after filtering
        if (filteredData.length > 0) {
          // Always write PTY data to terminal for the secondary terminal
          // This ensures character echo works properly
          if (secondaryTerm.current) {
            secondaryTerm.current.write(filteredData);
          }

          // Call handleSecondaryPtyData for prompt detection
          handleSecondaryPtyData(filteredData);
        }
      } catch (error) {
        console.error(
          "[AblyCLITerminal] [Secondary] Error processing message:",
          error,
        );
      }
    });

    // WebSocket error handler
    newSocket.addEventListener("error", (event) => {
      console.error("[AblyCLITerminal] [Secondary] WebSocket error:", event);
      console.error(
        "[AblyCLITerminal] [Secondary] WebSocket URL was:",
        websocketUrl,
      );
      console.error(
        "[AblyCLITerminal] [Secondary] WebSocket state:",
        newSocket.readyState,
      );
      updateSecondaryConnectionStatus("error");
    });

    // WebSocket close handler
    newSocket.addEventListener("close", (event) => {
      debugLog(
        `[AblyCLITerminal] [Secondary] WebSocket closed. Code: ${event.code}, Reason: ${event.reason}`,
      );
      setIsSecondarySessionActive(false);
      updateSecondaryConnectionStatus("disconnected");

      // Check if this is a non-recoverable error
      const NON_RECOVERABLE_CLOSE_CODES = new Set<number>([
        4001, // Policy violation (e.g. invalid credentials)
        4008, // Token expired
        1013, // Try again later
        4002, // Session resume rejected
        4000, // Generic server error
        4003, // Rate limit exceeded
        4004, // Unsupported protocol version
        4009, // Server at capacity
      ]);

      if (NON_RECOVERABLE_CLOSE_CODES.has(event.code)) {
        // Clear the secondary session ID as it's no longer valid
        setSecondarySessionId(null);
        if (resumeOnReload && globalThis.window !== undefined) {
          globalThis.sessionStorage.removeItem("ably.cli.secondarySessionId");
          debugLog(
            "[AblyCLITerminal] [Secondary] Cleared invalid session ID due to non-recoverable error",
          );
        }
      }

      // Check if this was a user-initiated close
      const userClosedTerminal =
        event.reason === "user-closed-secondary" ||
        event.reason === "manual-reconnect";

      if (!userClosedTerminal && secondaryTerm.current) {
        let title = "DISCONNECTED";
        let message1 = `Connection closed (Code: ${event.code})${event.reason ? `: ${event.reason}` : ""}.`;
        let message2 = "";
        let message3 = `Press ⏎ to reconnect.`;

        // Provide more helpful message for common error codes
        if (event.code === 1006) {
          title = "CONNECTION FAILED";
          message1 = `Unable to connect to server.`;
          message2 = `This may be due to network issues or server availability.`;
          message3 = `Press ⏎ to try again.`;
        } else if (
          event.code === 4003 ||
          event.reason?.toLowerCase().includes("rate limit")
        ) {
          title = "RATE LIMIT EXCEEDED";
          message1 = `Too many connection attempts.`;
          message2 = event.reason || `Please wait before trying again.`;
          message3 = ``;
        }

        secondaryStatusBoxReference.current = drawBox(
          secondaryTerm.current,
          boxColour.yellow,
          title,
          [message1, message2, message3],
          60,
        );
        setSecondaryOverlay({
          variant: "error",
          title,
          lines: [message1, message2, message3],
        });

        secondaryShowManualReconnectPromptReference.current = true;
        setSecondaryShowManualReconnectPrompt(true);
      }
    });

    return newSocket;
  }, [
    websocketUrl,
    ablyAccessToken,
    ablyApiKey,
    resumeOnReload,
    secondarySessionId,
  ]);

  // Keep the ref updated with the latest callback
  connectSecondaryWebSocketReference.current = connectSecondaryWebSocket;

  // Initialize the secondary terminal when split mode is enabled
  useEffect(() => {
    // Force a resize event on split mode change to ensure terminals resize correctly
    if (isSplit) {
      globalThis.dispatchEvent(new Event("resize"));
      // Also trigger a delayed fit for both terminals after split
      setTimeout(() => {
        if (fitAddon.current) {
          try {
            fitAddon.current.fit();
          } catch (error) {
            console.warn("Error fitting primary terminal after split:", error);
          }
        }
        if (secondaryFitAddon.current) {
          try {
            secondaryFitAddon.current.fit();
          } catch (error) {
            console.warn(
              "Error fitting secondary terminal after split:",
              error,
            );
          }
        }
      }, 100);
    }

    if (!isSplit || !secondaryRootReference.current || secondaryTerm.current) {
      return; // Only initialize once when splitting and element is available
    }

    // Initialize secondary terminal
    debugLog("[AblyCLITerminal] Initializing secondary Terminal instance.");
    secondaryTerm.current = createTerminal();
    secondaryFitAddon.current = createFitAddon();
    secondaryTerm.current.loadAddon(secondaryFitAddon.current);

    // Track current input line for autocomplete (secondary)
    let secondaryCurrentInputLine = "";
    let secondaryCursorPosition = 0;

    // Attach custom key handler for special keys (secondary)
    debugLog(
      "[AblyCLITerminal] Setting up custom key handler for secondary terminal",
    );
    secondaryTerm.current.attachCustomKeyEventHandler(
      (event: KeyboardEvent): boolean => {
        // Only handle special keys when connected and session is active
        if (
          !isSecondarySessionActive ||
          !secondarySocketReference.current ||
          secondarySocketReference.current.readyState !== WebSocket.OPEN
        ) {
          return true; // Let xterm handle it normally
        }

        debugLog(
          `[AblyCLITerminal] [Secondary] KeyboardEvent - key: "${event.key}", code: "${event.code}", ctrl: ${event.ctrlKey}`,
        );

        // Handle TAB for autocomplete
        if (event.key === "Tab" && !event.ctrlKey && !event.altKey) {
          event.preventDefault();
          debugLog(
            `[AblyCLITerminal] [Secondary] TAB intercepted, sending special message for autocomplete`,
          );

          secondarySocketReference.current.send(
            JSON.stringify({
              type: "readline-control",
              action: "complete",
              line: secondaryCurrentInputLine,
              cursor: secondaryCursorPosition,
            }),
          );

          return false; // Prevent default handling
        }

        // Handle UP arrow for history
        if (event.key === "ArrowUp" && !event.ctrlKey && !event.altKey) {
          event.preventDefault();
          debugLog(
            `[AblyCLITerminal] [Secondary] UP arrow intercepted, sending special message for history`,
          );

          secondarySocketReference.current.send(
            JSON.stringify({
              type: "readline-control",
              action: "history-up",
            }),
          );

          return false; // Prevent default handling
        }

        // Handle DOWN arrow for history
        if (event.key === "ArrowDown" && !event.ctrlKey && !event.altKey) {
          event.preventDefault();
          debugLog(
            `[AblyCLITerminal] [Secondary] DOWN arrow intercepted, sending special message for history`,
          );

          secondarySocketReference.current.send(
            JSON.stringify({
              type: "readline-control",
              action: "history-down",
            }),
          );

          return false; // Prevent default handling
        }

        // Handle Ctrl+R for history search
        if (
          event.key === "r" &&
          event.ctrlKey &&
          !event.altKey &&
          !event.shiftKey
        ) {
          event.preventDefault();
          debugLog(
            `[AblyCLITerminal] [Secondary] Ctrl+R intercepted, sending special message for history search`,
          );

          secondarySocketReference.current.send(
            JSON.stringify({
              type: "readline-control",
              action: "history-search",
            }),
          );

          return false; // Prevent default handling
        }

        return true; // Let other keys pass through normally
      },
    );

    // Handle data input in secondary terminal
    secondaryTerm.current.onData((data: string) => {
      // Special handling for Enter key
      if (data === "\r") {
        const latestStatus = secondaryConnectionStatusReference.current;

        // Manual prompt visible: attempt manual reconnect even if an old socket is open
        if (secondaryShowManualReconnectPromptReference.current) {
          debugLog(
            "[AblyCLITerminal] Secondary terminal: Enter pressed for manual reconnect.",
          );

          // Clear overlay and status displays
          clearSecondaryStatusDisplay();
          secondaryShowManualReconnectPromptReference.current = false;
          setSecondaryShowManualReconnectPrompt(false);

          // Forget previous session completely so no resume is attempted
          if (!resumeOnReload) {
            setSecondarySessionId(null);
          }

          // Ensure any lingering socket is fully closed before opening a new one
          if (
            secondarySocketReference.current &&
            secondarySocketReference.current.readyState !== WebSocket.CLOSED
          ) {
            try {
              secondarySocketReference.current.close(1000, "manual-reconnect");
            } catch {
              /* ignore */
            }
            secondarySocketReference.current = null; // Make sure the reference is cleared
          }

          // Give the browser a micro-task to mark socket CLOSED before reconnect
          setTimeout(() => {
            debugLog(
              "[AblyCLITerminal] [Secondary] Starting fresh reconnect sequence",
            );
            secondaryPtyBuffer.current = ""; // Clear buffer
            secondaryHandshakeFilterState.current =
              createHandshakeFilterState(); // Reset handshake filter
            connectSecondaryWebSocketReference.current?.();
          }, 20);

          return;
        }

        // Handle other special cases like primary terminal if needed
      }

      // Track input line for autocomplete (simple tracking - reset on Enter)
      if (data === "\r") {
        secondaryCurrentInputLine = "";
        secondaryCursorPosition = 0;
      } else if (data === "\u007F") {
        // Backspace
        if (secondaryCursorPosition > 0) {
          secondaryCurrentInputLine =
            secondaryCurrentInputLine.slice(0, secondaryCursorPosition - 1) +
            secondaryCurrentInputLine.slice(secondaryCursorPosition);
          secondaryCursorPosition--;
        }
      } else if (
        data.length === 1 &&
        data.charCodeAt(0) >= 32 &&
        data.charCodeAt(0) <= 126
      ) {
        // Regular printable character
        secondaryCurrentInputLine =
          secondaryCurrentInputLine.slice(0, secondaryCursorPosition) +
          data +
          secondaryCurrentInputLine.slice(secondaryCursorPosition);
        secondaryCursorPosition++;
      }

      // Default: forward data to server if socket open
      if (
        secondarySocketReference.current &&
        secondarySocketReference.current.readyState === WebSocket.OPEN
      ) {
        secondarySocketReference.current.send(data);
      }
    });

    // Open terminal in the DOM
    secondaryTerm.current.open(secondaryRootReference.current);

    // Delay initial fit to ensure DOM is ready
    setTimeout(() => {
      try {
        // Do the initial fit after DOM is ready
        secondaryFitAddon.current?.fit();

        // Additional fit after a longer delay for edge cases
        setTimeout(() => {
          try {
            secondaryFitAddon.current?.fit();
          } catch (error) {
            console.warn("Error fitting secondary addon delayed fit:", error);
          }
        }, 200);
      } catch (error) {
        console.error("Error during initial secondary terminal fit:", error);
      }
    }, 50); // Small delay to ensure terminal is attached to DOM

    // Setup resize handler for secondary terminal
    const handleResize = () => {
      if (secondaryFitAddon.current) {
        try {
          secondaryFitAddon.current.fit();
        } catch (error) {
          console.warn("Error fitting secondary terminal on resize:", error);
        }
      }
    };

    window.addEventListener("resize", handleResize);
    secondaryTermCleanupReference.current = () => {
      window.removeEventListener("resize", handleResize);
    };

    // Connect to WebSocket after terminal is initialized with a delay to avoid rate limits
    const connectTimer = setTimeout(() => {
      connectSecondaryWebSocketReference.current?.();
    }, 1000); // 1 second delay to ensure primary connection is established first

    // Cleanup function to properly dispose
    return () => {
      // Clear connect timer if still pending
      clearTimeout(connectTimer);

      // Execute cleanup for resize listener
      if (secondaryTermCleanupReference.current) {
        secondaryTermCleanupReference.current();
      }

      // Close WebSocket if open
      if (
        secondarySocketReference.current &&
        secondarySocketReference.current.readyState < WebSocket.CLOSING
      ) {
        debugLog(
          "[AblyCLITerminal] Closing secondary WebSocket on terminal cleanup.",
        );
        secondarySocketReference.current.close(4001, "user-closed-panel");
        secondarySocketReference.current = null;
      }

      // Dispose terminal
      if (secondaryTerm.current) {
        debugLog("[AblyCLITerminal] Disposing secondary Terminal.");
        secondaryTerm.current.dispose();
        secondaryTerm.current = null;
      }

      // Reset state
      updateSecondaryConnectionStatus("initial");
      setIsSecondarySessionActive(false);
      setSecondaryShowManualReconnectPrompt(false);
      setSecondarySessionId(null);
      setSecondaryOverlay(null);
    };
  }, [isSplit]); // Only re-run when split mode changes, not when connectSecondaryWebSocket changes

  // Persist secondary sessionId to localStorage whenever it changes (if enabled)
  useEffect(() => {
    if (!resumeOnReload || globalThis.window === undefined) return;
    if (secondarySessionId) {
      globalThis.sessionStorage.setItem(
        "ably.cli.secondarySessionId",
        secondarySessionId,
      );
    } else if (isSplit === false) {
      // Only remove if split mode is disabled
      globalThis.sessionStorage.removeItem("ably.cli.secondarySessionId");
    }
  }, [secondarySessionId, resumeOnReload, isSplit]);

  // New function to handle secondary terminal status changes without external reporting
  const updateSecondaryConnectionStatus = useCallback(
    (status: ConnectionStatus) => {
      // Update internal state for the secondary terminal
      setSecondaryConnectionStatus(status);
      secondaryConnectionStatusReference.current = status;

      // We intentionally don't call onConnectionStatusChange here
      // as per requirements - only the primary terminal status should be reported
    },
    [],
  );

  return (
    <div
      data-testid="terminal-outer-container"
      className="flex flex-col w-full h-full bg-gray-800 text-white overflow-hidden relative"
      style={{ position: "relative" }}
    >
      <style>{`
        .Terminal-container .xterm {
          padding: 10px;
          height: 100%;
          box-sizing: border-box;
        }
        .Terminal-container .xterm-viewport {
          background-color: transparent !important;
        }
        .Terminal-container .xterm-screen {
          height: 100% !important;
        }
      `}</style>
      {/* Panes with explicit widths to prevent resize issues */}
      <div
        ref={outerContainerReference}
        className="flex-grow flex w-full h-full relative overflow-hidden"
        style={{
          display: "flex",
          flexDirection: "row",
          width: "100%",
          height: "100%",
        }}
      >
        {/* Primary terminal column with dynamic width */}
        <div
          style={{
            width: isSplit ? `${splitPosition}%` : "100%",
            height: "100%",
            display: "flex",
            flexDirection: "column",
            overflow: "hidden",
            position: "relative",
          }}
        >
          {/* Terminal 1 tab - only visible in split mode */}
          {isSplit && (
            <div
              data-testid="tab-1"
              className="flex items-center bg-gray-900 text-sm select-none border-b border-gray-700"
              style={{ width: "100%", flexShrink: 0, height: "28px" }}
            >
              <div className="flex items-center justify-between w-full px-3 py-1">
                <span>Terminal 1</span>
                <button
                  onClick={handleClosePrimary}
                  data-testid="close-terminal-1-button"
                  aria-label="Close Terminal 1"
                  className="bg-transparent border-0 text-gray-400 hover:text-white cursor-pointer"
                  style={{
                    padding: "4px",
                    marginLeft: "4px",
                    marginBottom: "2px",
                    borderRadius: "4px",
                    transition: "background-color 0.2s ease",
                    background: "transparent",
                  }}
                  onMouseEnter={(e) =>
                    (e.currentTarget.style.backgroundColor =
                      "rgba(75, 85, 99, 0.4)")
                  }
                  onMouseLeave={(e) =>
                    (e.currentTarget.style.backgroundColor = "transparent")
                  }
                >
                  <X size={14} />
                </button>
              </div>
            </div>
          )}

          {/* Primary terminal container */}
          <div
            ref={rootReference}
            data-testid="terminal-container"
            className="Terminal-container bg-black relative overflow-hidden"
            style={{
              flex: "1",
              padding: "0",
              margin: "0",
              boxSizing: "border-box",
              minHeight: "0", // Important to allow flex container to shrink
              width: "100%",
              position: "relative",
              display: "flex",
              flexDirection: "column",
            }}
          >
            {/* Split button – only when not already split and controls are enabled */}
            {!isSplit && enableSplitScreen && showSplitControl && (
              <button
                onClick={handleSplitScreen}
                aria-label="Split terminal"
                title="Split terminal"
                data-testid="split-terminal-button"
                style={{
                  position: "absolute",
                  top: "8px",
                  right: "8px",
                  zIndex: 9999,
                  backgroundColor: "#374151",
                  borderRadius: "0.25rem",
                  padding: "0.4em",
                  border: "none",
                  display: "flex",
                  alignItems: "center",
                  justifyContent: "center",
                  cursor: "pointer",
                }}
              >
                <SplitSquareHorizontal size={16} />
              </button>
            )}

            {overlay && <TerminalOverlay {...overlay} />}
          </div>
        </div>

        {/* Draggable vertical divider - only visible in split mode */}
        {isSplit && (
          <div
            data-testid="terminal-divider"
            style={{
              width: "5px",
              height: "100%",
              backgroundColor: "#6B7280",
              flexShrink: 0,
              flexGrow: 0,
              cursor: "col-resize",
              position: "relative",
              zIndex: 10,
            }}
            onMouseDown={handleDragStart}
          >
            {/* Visible handle indicator in the middle of the divider */}
            <div
              style={{
                position: "absolute",
                top: "50%",
                left: "50%",
                transform: "translate(-50%, -50%)",
                width: "3px",
                height: "30px",
                backgroundColor: "#D1D5DB",
                borderRadius: "1.5px",
              }}
            />
          </div>
        )}

        {/* Secondary terminal column - only rendered when split is active */}
        {isSplit && (
          <div
            style={{
              width: `${100 - splitPosition}%`,
              height: "100%",
              display: "flex",
              flexDirection: "column",
              overflow: "hidden",
              position: "relative",
            }}
          >
            {/* Terminal 2 tab */}
            <div
              data-testid="tab-2"
              className="flex items-center bg-gray-900 text-sm select-none border-b border-gray-700"
              style={{ width: "100%", flexShrink: 0, height: "28px" }}
            >
              <div className="flex items-center justify-between w-full px-3 py-1">
                <span>Terminal 2</span>
                <button
                  onClick={handleCloseSecondary}
                  data-testid="close-terminal-2-button"
                  aria-label="Close Terminal 2"
                  className="bg-transparent border-0 text-gray-400 hover:text-white cursor-pointer"
                  style={{
                    padding: "4px",
                    marginLeft: "4px",
                    marginBottom: "2px",
                    borderRadius: "4px",
                    transition: "background-color 0.2s ease",
                    background: "transparent",
                  }}
                  onMouseEnter={(e) =>
                    (e.currentTarget.style.backgroundColor =
                      "rgba(75, 85, 99, 0.4)")
                  }
                  onMouseLeave={(e) =>
                    (e.currentTarget.style.backgroundColor = "transparent")
                  }
                >
                  <X size={14} />
                </button>
              </div>
            </div>

            {/* Secondary terminal container */}
            <div
              ref={secondaryRootReference}
              data-testid="terminal-container-secondary"
              className="Terminal-container bg-black relative overflow-hidden"
              style={{
                flex: "1",
                padding: "0",
                margin: "0",
                boxSizing: "border-box",
                minHeight: "0", // Important to allow flex container to shrink
                width: "100%",
                position: "relative",
                display: "flex",
                flexDirection: "column",
              }}
            >
              {secondaryOverlay && <TerminalOverlay {...secondaryOverlay} />}
            </div>
          </div>
        )}
      </div>
    </div>
  );
};

export const AblyCliTerminal = forwardRef<
  AblyCliTerminalHandle,
  AblyCliTerminalProperties
>(AblyCliTerminalInner);

export default AblyCliTerminal;