// Shared shape a mounted pane connection satisfies, whatever session view is
// behind it — what ConnectionPool needs to mount/park/dispose a pane without
// caring whether it holds an xterm attach (attach.ts) or a structured
// transcript (structured.ts).

import type { Uuid } from "./types.js";
import type { AttachInfo } from "./paneTitle.js";

export interface PaneConnection {
  readonly sessionId: Uuid;
  /** The element to mount into a pane. */
  readonly el: HTMLElement;
  /** Becomes the visible view: fit/focus/sync as the connection needs.
   *  `focus: false` mounts without taking the keyboard (a sidebar preview). */
  onMount(opts?: { focus?: boolean }): void;
  /** Parked into the hidden cache: keep streaming, stop driving focus/sizing. */
  onUnmount(): void;
  /** Put the keyboard into this pane's primary input — the terminal for an
   *  attach connection, the composer for a structured one. */
  focusTerminal(): void;
  /** Raw bytes into a PTY, bypassing normal key handling (the leader's
   *  literal-byte escape hatch, docs/COMMAND-BAR.md). A structured connection
   *  has no PTY, so this is a no-op there. */
  sendInput(data: string): void;
  /** Refresh the pane header after the catalog renames a live session. */
  updateInfo(info: AttachInfo): void;
  /** Fully disconnect and remove the element. */
  dispose(): void;
}