@particle-academy/fancy-term 0.2.2 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,170 @@
 import * as react from 'react';
 import { HTMLAttributes, CSSProperties, RefObject } from 'react';
-import { ITheme, Terminal as Terminal$1 } from '@xterm/xterm';
+import { Terminal as Terminal$1, IDisposable, ITheme } from '@xterm/xterm';
+
+/** What a paste / drop carried: plain text plus any files (e.g. pasted images). */
+interface ClipboardPayload {
+    /** Plain text from the clipboard (or pasted selection). May be "". */
+    text: string;
+    /** Files present on the clipboard / drop — typically pasted/dropped images. */
+    files: File[];
+    /** Convenience: the subset of `files` whose MIME type is `image/*`. */
+    images: File[];
+}
+/** True when a file looks like an image (by MIME type). */
+declare function isImageFile(f: {
+    type?: string;
+}): boolean;
+/**
+ * A host-supplied clipboard. Every copy/paste path in fancy-term — the copy
+ * chord, the context menu, OSC 52, `handle.copySelection` / `handle.paste` —
+ * routes through this, so an Electron host (where `navigator.clipboard` silently
+ * no-ops in a sandboxed renderer) can bridge to its main-process clipboard over
+ * IPC. `writeText` may return anything (a `Promise<void>` from IPC is fine);
+ * `readText` returns the clipboard text.
+ */
+interface ClipboardProvider {
+    writeText: (text: string) => void | Promise<unknown>;
+    readText: () => string | Promise<string>;
+}
+/** The default provider — `navigator.clipboard` with the legacy `execCommand` fallback. */
+declare const navigatorClipboard: ClipboardProvider;
+/** The `clipboard` prop: `false` disables clipboard wiring; a provider object injects a host clipboard; `true`/omitted uses {@link navigatorClipboard}. */
+type ClipboardOption = boolean | ClipboardProvider;
+/** Normalize the `clipboard` prop into `{ enabled, provider }`, read live per call. */
+declare function resolveClipboard(clipboard: ClipboardOption | undefined): {
+    enabled: boolean;
+    provider: ClipboardProvider;
+};
+
+/**
+ * The copy/paste convention the terminal follows:
+ * - `contextmenu` — copy/paste via the right-click menu only (plus the always-on
+ *   Ctrl+Shift+C copy chord).
+ * - `linux` — highlight-to-copy (X11 primary-selection style) + middle-click
+ *   paste. Right-click still opens the context menu.
+ * - `winmac` — Ctrl/Cmd+C copies the selection (falling back to SIGINT when
+ *   nothing is selected), Ctrl/Cmd+V pastes.
+ *
+ * Omitting the prop keeps the historical default: the Ctrl+Shift+C chord and
+ * Cmd+C-with-selection, no auto-copy, no mouse paste.
+ */
+type CopyPasteMode = "contextmenu" | "linux" | "winmac";
+/** The resolved, event-agnostic behavior flags a {@link CopyPasteMode} implies. */
+interface CopyPasteBehavior {
+    /** Auto-copy the selection to the clipboard as soon as it changes (linux). */
+    selectToCopy: boolean;
+    /** Paste on middle-mouse-button (linux). */
+    middleClickPaste: boolean;
+    /** (Ctrl|Cmd)+C copies the selection when one exists (winmac). */
+    keyCopy: boolean;
+    /** (Ctrl|Cmd)+V — and Ctrl+Shift+V — paste (winmac). */
+    keyPaste: boolean;
+}
+declare function copyPasteBehavior(mode: CopyPasteMode | undefined): CopyPasteBehavior;
+/** The subset of a KeyboardEvent the copy/paste decision reads. */
+interface KeyEventLike {
+    type: string;
+    key: string;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    metaKey: boolean;
+}
+/**
+ * Resolve a key event to a clipboard action, given the current selection state
+ * and the active behavior. Returns `"copy"`, `"paste"`, or `null` (do nothing —
+ * let the byte reach the shell). Only fires on `keydown`.
+ *
+ * Copy is honored across every mode for the terminal-safe **Ctrl+Shift+C** chord
+ * and macOS **Cmd+C-with-selection**; `keyCopy` adds plain (Ctrl|Cmd)+C. Plain
+ * Ctrl+C with no selection is never a copy — it stays SIGINT.
+ */
+declare function resolveKeyAction(e: KeyEventLike, hasSelection: boolean, behavior: CopyPasteBehavior): "copy" | "paste" | null;
+
+/**
+ * OSC 52 policy: `copy` allows programs to WRITE the clipboard (the common TUI
+ * case), `read` allows a program to READ it back (a `?` request), `both` allows
+ * either, `false` disables OSC 52 entirely. Read is the real exfiltration risk
+ * (arbitrary terminal output could siphon your clipboard), so it must be opted
+ * into explicitly.
+ */
+type Osc52Mode = "copy" | "read" | "both" | false;
+/** A parsed OSC 52 request: which selection buffer, and write-a-payload vs read-request. */
+interface Osc52Request {
+    /** The `Pc` field — clipboard selection(s), e.g. `"c"` (clipboard), `"p"` (primary). */
+    selection: string;
+    kind: "write" | "read";
+    /** Decoded text for a write; `""` for a read request. */
+    data: string;
+}
+/** UTF-8-safe base64 encode (browser `btoa` operates on binary strings). */
+declare function encodeBase64(text: string): string;
+/** UTF-8-safe base64 decode; returns `""` on malformed input. */
+declare function decodeBase64(b64: string): string;
+/**
+ * Parse an OSC 52 payload (the part after `ESC ] 52 ;`, i.e. `<Pc> ; <Pd>`).
+ * `Pd === "?"` is a read request; otherwise `Pd` is base64 to write. Returns
+ * `null` for a malformed payload (no `;`).
+ */
+declare function parseOsc52(payload: string): Osc52Request | null;
+/** Build the OSC 52 response a `read` request expects: `ESC ] 52 ; <Pc> ; <base64> BEL`. */
+declare function osc52Response(selection: string, text: string): string;
+/**
+ * Register an OSC 52 handler on an xterm instance, routing writes/reads through
+ * `provider` per `mode`. Returns the {@link IDisposable} (or `null` when
+ * `mode === false`). The handler always returns `true` (consumed) so a
+ * disallowed direction is swallowed rather than echoed as garbage.
+ */
+declare function registerOsc52(term: Terminal$1, provider: () => ClipboardProvider, mode: () => Osc52Mode): IDisposable | null;
+
+/** Context handed to the menu at right-click time + to custom item builders. */
+interface TerminalContextMenuContext {
+    /** Whether there is a non-empty text selection. */
+    hasSelection: boolean;
+    /** The selected text (or ""). */
+    selection: string;
+    /** Whether the terminal is read-only (paste / clear are dropped by default). */
+    readOnly: boolean;
+}
+/** A single menu entry. `onSelect` runs on click; set `separator` for a divider. */
+interface TerminalContextMenuItem {
+    /** Stable id (used as the React key + a `data-menu-item` handle). */
+    id: string;
+    /** Visible label. Ignored for separators. */
+    label?: string;
+    /** Optional leading glyph / emoji / short string (JSON-friendly — no ReactNode). */
+    icon?: string;
+    /** Greyed-out + non-interactive. */
+    disabled?: boolean;
+    /** Render a divider instead of a clickable item. */
+    separator?: boolean;
+    /** Invoked on click with the menu context. */
+    onSelect?: (ctx: TerminalContextMenuContext) => void;
+}
+/** The actions the built-in items dispatch to (wired by the component). */
+interface TerminalMenuActions {
+    copy: () => void;
+    paste: () => void;
+    selectAll: () => void;
+    clear: () => void;
+}
+/**
+ * The `contextMenu` prop shape:
+ * - `false` — disable the menu entirely.
+ * - `true` / omitted — the default Copy / Paste / Select all / Clear menu.
+ * - an array — replace the default items wholesale.
+ * - a function — receives the context **and the default items** so you can
+ *   add/remove/reorder (e.g. append a "Send to agent" item).
+ */
+type TerminalContextMenuConfig = boolean | TerminalContextMenuItem[] | ((ctx: TerminalContextMenuContext, defaults: TerminalContextMenuItem[]) => TerminalContextMenuItem[]);
+/** The built-in Copy / Paste / Select all / Clear items, contextual to selection + readOnly. */
+declare function defaultMenuItems(ctx: TerminalContextMenuContext, actions: TerminalMenuActions): TerminalContextMenuItem[];
+/**
+ * Resolve the configured menu into the final item list, or `null` when disabled.
+ * Empty results (e.g. a function that filtered everything out) also resolve to
+ * `null` so the caller can skip opening an empty menu.
+ */
+declare function resolveMenuItems(config: TerminalContextMenuConfig | undefined, ctx: TerminalContextMenuContext, actions: TerminalMenuActions): TerminalContextMenuItem[] | null;
 
 /** xterm.js color theme (re-exported for ergonomic typing). */
 type TerminalTheme = ITheme;
@@ -33,6 +197,13 @@ interface ShellProfile {
 interface TerminalHandle {
     /** The underlying xterm.js instance — escape hatch for addons / advanced use. Null before mount. */
     readonly xterm: Terminal$1 | null;
+    /**
+     * Resolves with the xterm instance once it's opened + measured. Because
+     * `xterm` is null until the container lays out, a consumer that must wire an
+     * addon can `await handle.ready` instead of polling. Re-armed if the terminal
+     * is torn down + recreated (e.g. a container change).
+     */
+    readonly ready: Promise<Terminal$1>;
     /** Write raw data (ANSI escape sequences honored) to the terminal. */
     write: (data: string) => void;
     /** Write data followed by CRLF. */
@@ -49,6 +220,14 @@ interface TerminalHandle {
     getBuffer: () => string;
     /** The current text selection, or "" when nothing is selected. */
     getSelection: () => string;
+    /** Copy the current selection to the system clipboard. Resolves false when there's nothing selected or the clipboard is unavailable. */
+    copySelection: () => Promise<boolean>;
+    /** Paste text into the terminal. With no argument, reads the system clipboard. Honors xterm's bracketed-paste mode. */
+    paste: (text?: string) => Promise<void>;
+    /** Select the entire buffer. */
+    selectAll: () => void;
+    /** Clear the current selection. */
+    clearSelection: () => void;
     /**
      * Switch the active shell by id. Resolves the matching {@link ShellProfile}
      * from `shells` and fires `onShellChange`; in uncontrolled mode it also updates
@@ -88,8 +267,50 @@ interface TerminalOptions {
         cols: number;
         rows: number;
     }) => void;
+    /**
+     * Clipboard wiring — gates the Ctrl+Shift+C / Cmd+C copy chord, the paste
+     * interceptor ({@link onPaste}), the context-menu copy/paste, and OSC 52.
+     *
+     * - `true` / omitted — enabled, backed by `navigator.clipboard`.
+     * - `false` — disabled (no copy chord / OSC 52; native text paste still works).
+     * - a `{ writeText, readText }` **provider** — every copy/paste path routes
+     *   through it. Supply this in a sandboxed Electron renderer, where
+     *   `navigator.clipboard` silently no-ops, to bridge to the main-process
+     *   clipboard over IPC.
+     */
+    clipboard?: ClipboardOption;
+    /**
+     * OSC 52 clipboard policy — lets terminal programs (Claude Code, tmux, vim)
+     * set/read the system clipboard via `ESC ] 52`. `"copy"` (default) allows
+     * writes only; `"read"` / `"both"` also answer read requests (an exfiltration
+     * risk — opt in deliberately); `false` disables it. Routed through the same
+     * clipboard provider as {@link clipboard}; a no-op when clipboard is `false`.
+     * Default `"copy"`.
+     */
+    osc52?: Osc52Mode;
+    /**
+     * Copy/paste UX convention: `"contextmenu"` (menu + Ctrl+Shift+C),
+     * `"linux"` (highlight-to-copy + middle-click paste), or `"winmac"`
+     * (Ctrl/Cmd+C copies the selection, Ctrl/Cmd+V pastes). Omit for the historical
+     * default (Ctrl+Shift+C + Cmd+C-with-selection). Ctrl+Shift+C always copies.
+     */
+    copyPaste?: CopyPasteMode;
+    /**
+     * Called once the xterm instance is opened + attached — the imperative twin of
+     * {@link TerminalHandle.ready}. Use it to load an addon without racing the
+     * container layout (where `handle.xterm` is still null).
+     */
+    onReady?: (xterm: Terminal$1) => void;
+    /**
+     * Fired on every paste with the clipboard payload — `{ text, files, images }`.
+     * Plain text still pastes into the terminal natively; this is where a host
+     * receives pasted **images** (a shell can't render them) to upload / hand to an
+     * agent / write a path. Return `false` to fully consume the paste (suppress the
+     * default text paste — e.g. to transform it, then call `handle.paste(...)`).
+     */
+    onPaste?: (payload: ClipboardPayload) => void | boolean;
 }
-interface TerminalProps extends TerminalOptions, Omit<HTMLAttributes<HTMLDivElement>, "onInput" | "onResize" | "children"> {
+interface TerminalProps extends TerminalOptions, Omit<HTMLAttributes<HTMLDivElement>, "onInput" | "onResize" | "onPaste" | "contextMenu" | "children"> {
     /**
      * The controlled output buffer. The component diffs against the previous value
      * and writes only the appended delta, so a host can drive the terminal from
@@ -112,6 +333,13 @@ interface TerminalProps extends TerminalOptions, Omit<HTMLAttributes<HTMLDivElem
      * `shells` is provided. Default `false` — opt-in so existing layout is unchanged.
      */
     showShellBar?: boolean;
+    /**
+     * The right-click selection context menu. `false` disables it; `true` / omitted
+     * gives the default Copy / Paste / Select all / Clear menu; an array replaces
+     * the items; a `(ctx, defaults) => items` function lets you add/remove/reorder
+     * (e.g. append a "Send to agent" item). See {@link TerminalContextMenuConfig}.
+     */
+    contextMenu?: TerminalContextMenuConfig;
 }
 /**
  * Resolve a shell id to its {@link ShellProfile} within a list. Pure helper —
@@ -169,6 +397,22 @@ interface ShellSwitcherProps {
  */
 declare function ShellSwitcher({ shells, value, onChange, className, style, disabled, }: ShellSwitcherProps): react.JSX.Element;
 
+/**
+ * The terminal selection context menu. Deliberately plain React + inline styles
+ * (fancy-term has no react-fancy dependency) styled to match the shell bar. It
+ * closes on click-outside + Escape, and clamps itself inside the viewport on
+ * mount so a right-click near an edge never spills off-screen.
+ */
+declare function TerminalContextMenu({ at, items, ctx, onClose, }: {
+    at: {
+        x: number;
+        y: number;
+    };
+    items: TerminalContextMenuItem[];
+    ctx: TerminalContextMenuContext;
+    onClose: () => void;
+}): react.JSX.Element;
+
 /**
  * Create + own an xterm.js instance for a container, returning a stable
  * {@link TerminalHandle}. The headless engine layer behind `<Terminal>` — use it
@@ -257,4 +501,40 @@ declare function useTerminalSession(options: UseTerminalSessionOptions): Termina
  */
 declare const fancyDarkTheme: TerminalTheme;
 
-export { BUILTIN_SHELLS, type CursorStyle, type ShellProfile, ShellSwitcher, type ShellSwitcherProps, Terminal, type TerminalHandle, type TerminalOptions, type TerminalProps, type TerminalSessionApi, type TerminalSessionTransport, type TerminalTheme, type UseTerminalSessionOptions, fancyDarkTheme, resolveShell, useTerminal, useTerminalFit, useTerminalSession };
+/** The subset of a KeyboardEvent the copy decision reads. */
+interface CopyKeyEvent {
+    type: string;
+    key: string;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    metaKey: boolean;
+}
+/**
+ * Whether a key event should copy the current selection to the clipboard.
+ *
+ * - **Ctrl+Shift+C** (Windows / Linux terminal convention) — always.
+ * - **Cmd / Meta+C** (macOS) — only when there is a selection.
+ * - **Plain Ctrl+C is never a copy** — it must stay SIGINT.
+ *
+ * Only fires on `keydown`. When this returns true the caller copies the
+ * selection and consumes the event (returns `false` from xterm's
+ * `attachCustomKeyEventHandler` so no control byte is sent).
+ */
+declare function shouldCopyEvent(e: CopyKeyEvent, hasSelection: boolean): boolean;
+
+interface MenuPoint {
+    x: number;
+    y: number;
+}
+interface MenuSize {
+    width: number;
+    height: number;
+}
+/**
+ * Clamp a menu's top-left so the whole menu stays inside the viewport (minus a
+ * margin). Pushes left/up when it would overflow the right/bottom edge, and never
+ * goes past the top-left margin. Pure.
+ */
+declare function clampMenuPosition(at: MenuPoint, menu: MenuSize, viewport: MenuSize, margin?: number): MenuPoint;
+
+export { BUILTIN_SHELLS, type ClipboardOption, type ClipboardPayload, type ClipboardProvider, type CopyKeyEvent, type CopyPasteBehavior, type CopyPasteMode, type CursorStyle, type KeyEventLike, type Osc52Mode, type Osc52Request, type ShellProfile, ShellSwitcher, type ShellSwitcherProps, Terminal, TerminalContextMenu, type TerminalContextMenuConfig, type TerminalContextMenuContext, type TerminalContextMenuItem, type TerminalHandle, type TerminalMenuActions, type TerminalOptions, type TerminalProps, type TerminalSessionApi, type TerminalSessionTransport, type TerminalTheme, type UseTerminalSessionOptions, clampMenuPosition, copyPasteBehavior, decodeBase64, defaultMenuItems, encodeBase64, fancyDarkTheme, isImageFile, navigatorClipboard, osc52Response, parseOsc52, registerOsc52, resolveClipboard, resolveKeyAction, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };

package/dist/index.d.ts

@@ -1,6 +1,170 @@
 import * as react from 'react';
 import { HTMLAttributes, CSSProperties, RefObject } from 'react';
-import { ITheme, Terminal as Terminal$1 } from '@xterm/xterm';
+import { Terminal as Terminal$1, IDisposable, ITheme } from '@xterm/xterm';
+
+/** What a paste / drop carried: plain text plus any files (e.g. pasted images). */
+interface ClipboardPayload {
+    /** Plain text from the clipboard (or pasted selection). May be "". */
+    text: string;
+    /** Files present on the clipboard / drop — typically pasted/dropped images. */
+    files: File[];
+    /** Convenience: the subset of `files` whose MIME type is `image/*`. */
+    images: File[];
+}
+/** True when a file looks like an image (by MIME type). */
+declare function isImageFile(f: {
+    type?: string;
+}): boolean;
+/**
+ * A host-supplied clipboard. Every copy/paste path in fancy-term — the copy
+ * chord, the context menu, OSC 52, `handle.copySelection` / `handle.paste` —
+ * routes through this, so an Electron host (where `navigator.clipboard` silently
+ * no-ops in a sandboxed renderer) can bridge to its main-process clipboard over
+ * IPC. `writeText` may return anything (a `Promise<void>` from IPC is fine);
+ * `readText` returns the clipboard text.
+ */
+interface ClipboardProvider {
+    writeText: (text: string) => void | Promise<unknown>;
+    readText: () => string | Promise<string>;
+}
+/** The default provider — `navigator.clipboard` with the legacy `execCommand` fallback. */
+declare const navigatorClipboard: ClipboardProvider;
+/** The `clipboard` prop: `false` disables clipboard wiring; a provider object injects a host clipboard; `true`/omitted uses {@link navigatorClipboard}. */
+type ClipboardOption = boolean | ClipboardProvider;
+/** Normalize the `clipboard` prop into `{ enabled, provider }`, read live per call. */
+declare function resolveClipboard(clipboard: ClipboardOption | undefined): {
+    enabled: boolean;
+    provider: ClipboardProvider;
+};
+
+/**
+ * The copy/paste convention the terminal follows:
+ * - `contextmenu` — copy/paste via the right-click menu only (plus the always-on
+ *   Ctrl+Shift+C copy chord).
+ * - `linux` — highlight-to-copy (X11 primary-selection style) + middle-click
+ *   paste. Right-click still opens the context menu.
+ * - `winmac` — Ctrl/Cmd+C copies the selection (falling back to SIGINT when
+ *   nothing is selected), Ctrl/Cmd+V pastes.
+ *
+ * Omitting the prop keeps the historical default: the Ctrl+Shift+C chord and
+ * Cmd+C-with-selection, no auto-copy, no mouse paste.
+ */
+type CopyPasteMode = "contextmenu" | "linux" | "winmac";
+/** The resolved, event-agnostic behavior flags a {@link CopyPasteMode} implies. */
+interface CopyPasteBehavior {
+    /** Auto-copy the selection to the clipboard as soon as it changes (linux). */
+    selectToCopy: boolean;
+    /** Paste on middle-mouse-button (linux). */
+    middleClickPaste: boolean;
+    /** (Ctrl|Cmd)+C copies the selection when one exists (winmac). */
+    keyCopy: boolean;
+    /** (Ctrl|Cmd)+V — and Ctrl+Shift+V — paste (winmac). */
+    keyPaste: boolean;
+}
+declare function copyPasteBehavior(mode: CopyPasteMode | undefined): CopyPasteBehavior;
+/** The subset of a KeyboardEvent the copy/paste decision reads. */
+interface KeyEventLike {
+    type: string;
+    key: string;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    metaKey: boolean;
+}
+/**
+ * Resolve a key event to a clipboard action, given the current selection state
+ * and the active behavior. Returns `"copy"`, `"paste"`, or `null` (do nothing —
+ * let the byte reach the shell). Only fires on `keydown`.
+ *
+ * Copy is honored across every mode for the terminal-safe **Ctrl+Shift+C** chord
+ * and macOS **Cmd+C-with-selection**; `keyCopy` adds plain (Ctrl|Cmd)+C. Plain
+ * Ctrl+C with no selection is never a copy — it stays SIGINT.
+ */
+declare function resolveKeyAction(e: KeyEventLike, hasSelection: boolean, behavior: CopyPasteBehavior): "copy" | "paste" | null;
+
+/**
+ * OSC 52 policy: `copy` allows programs to WRITE the clipboard (the common TUI
+ * case), `read` allows a program to READ it back (a `?` request), `both` allows
+ * either, `false` disables OSC 52 entirely. Read is the real exfiltration risk
+ * (arbitrary terminal output could siphon your clipboard), so it must be opted
+ * into explicitly.
+ */
+type Osc52Mode = "copy" | "read" | "both" | false;
+/** A parsed OSC 52 request: which selection buffer, and write-a-payload vs read-request. */
+interface Osc52Request {
+    /** The `Pc` field — clipboard selection(s), e.g. `"c"` (clipboard), `"p"` (primary). */
+    selection: string;
+    kind: "write" | "read";
+    /** Decoded text for a write; `""` for a read request. */
+    data: string;
+}
+/** UTF-8-safe base64 encode (browser `btoa` operates on binary strings). */
+declare function encodeBase64(text: string): string;
+/** UTF-8-safe base64 decode; returns `""` on malformed input. */
+declare function decodeBase64(b64: string): string;
+/**
+ * Parse an OSC 52 payload (the part after `ESC ] 52 ;`, i.e. `<Pc> ; <Pd>`).
+ * `Pd === "?"` is a read request; otherwise `Pd` is base64 to write. Returns
+ * `null` for a malformed payload (no `;`).
+ */
+declare function parseOsc52(payload: string): Osc52Request | null;
+/** Build the OSC 52 response a `read` request expects: `ESC ] 52 ; <Pc> ; <base64> BEL`. */
+declare function osc52Response(selection: string, text: string): string;
+/**
+ * Register an OSC 52 handler on an xterm instance, routing writes/reads through
+ * `provider` per `mode`. Returns the {@link IDisposable} (or `null` when
+ * `mode === false`). The handler always returns `true` (consumed) so a
+ * disallowed direction is swallowed rather than echoed as garbage.
+ */
+declare function registerOsc52(term: Terminal$1, provider: () => ClipboardProvider, mode: () => Osc52Mode): IDisposable | null;
+
+/** Context handed to the menu at right-click time + to custom item builders. */
+interface TerminalContextMenuContext {
+    /** Whether there is a non-empty text selection. */
+    hasSelection: boolean;
+    /** The selected text (or ""). */
+    selection: string;
+    /** Whether the terminal is read-only (paste / clear are dropped by default). */
+    readOnly: boolean;
+}
+/** A single menu entry. `onSelect` runs on click; set `separator` for a divider. */
+interface TerminalContextMenuItem {
+    /** Stable id (used as the React key + a `data-menu-item` handle). */
+    id: string;
+    /** Visible label. Ignored for separators. */
+    label?: string;
+    /** Optional leading glyph / emoji / short string (JSON-friendly — no ReactNode). */
+    icon?: string;
+    /** Greyed-out + non-interactive. */
+    disabled?: boolean;
+    /** Render a divider instead of a clickable item. */
+    separator?: boolean;
+    /** Invoked on click with the menu context. */
+    onSelect?: (ctx: TerminalContextMenuContext) => void;
+}
+/** The actions the built-in items dispatch to (wired by the component). */
+interface TerminalMenuActions {
+    copy: () => void;
+    paste: () => void;
+    selectAll: () => void;
+    clear: () => void;
+}
+/**
+ * The `contextMenu` prop shape:
+ * - `false` — disable the menu entirely.
+ * - `true` / omitted — the default Copy / Paste / Select all / Clear menu.
+ * - an array — replace the default items wholesale.
+ * - a function — receives the context **and the default items** so you can
+ *   add/remove/reorder (e.g. append a "Send to agent" item).
+ */
+type TerminalContextMenuConfig = boolean | TerminalContextMenuItem[] | ((ctx: TerminalContextMenuContext, defaults: TerminalContextMenuItem[]) => TerminalContextMenuItem[]);
+/** The built-in Copy / Paste / Select all / Clear items, contextual to selection + readOnly. */
+declare function defaultMenuItems(ctx: TerminalContextMenuContext, actions: TerminalMenuActions): TerminalContextMenuItem[];
+/**
+ * Resolve the configured menu into the final item list, or `null` when disabled.
+ * Empty results (e.g. a function that filtered everything out) also resolve to
+ * `null` so the caller can skip opening an empty menu.
+ */
+declare function resolveMenuItems(config: TerminalContextMenuConfig | undefined, ctx: TerminalContextMenuContext, actions: TerminalMenuActions): TerminalContextMenuItem[] | null;
 
 /** xterm.js color theme (re-exported for ergonomic typing). */
 type TerminalTheme = ITheme;
@@ -33,6 +197,13 @@ interface ShellProfile {
 interface TerminalHandle {
     /** The underlying xterm.js instance — escape hatch for addons / advanced use. Null before mount. */
     readonly xterm: Terminal$1 | null;
+    /**
+     * Resolves with the xterm instance once it's opened + measured. Because
+     * `xterm` is null until the container lays out, a consumer that must wire an
+     * addon can `await handle.ready` instead of polling. Re-armed if the terminal
+     * is torn down + recreated (e.g. a container change).
+     */
+    readonly ready: Promise<Terminal$1>;
     /** Write raw data (ANSI escape sequences honored) to the terminal. */
     write: (data: string) => void;
     /** Write data followed by CRLF. */
@@ -49,6 +220,14 @@ interface TerminalHandle {
     getBuffer: () => string;
     /** The current text selection, or "" when nothing is selected. */
     getSelection: () => string;
+    /** Copy the current selection to the system clipboard. Resolves false when there's nothing selected or the clipboard is unavailable. */
+    copySelection: () => Promise<boolean>;
+    /** Paste text into the terminal. With no argument, reads the system clipboard. Honors xterm's bracketed-paste mode. */
+    paste: (text?: string) => Promise<void>;
+    /** Select the entire buffer. */
+    selectAll: () => void;
+    /** Clear the current selection. */
+    clearSelection: () => void;
     /**
      * Switch the active shell by id. Resolves the matching {@link ShellProfile}
      * from `shells` and fires `onShellChange`; in uncontrolled mode it also updates
@@ -88,8 +267,50 @@ interface TerminalOptions {
         cols: number;
         rows: number;
     }) => void;
+    /**
+     * Clipboard wiring — gates the Ctrl+Shift+C / Cmd+C copy chord, the paste
+     * interceptor ({@link onPaste}), the context-menu copy/paste, and OSC 52.
+     *
+     * - `true` / omitted — enabled, backed by `navigator.clipboard`.
+     * - `false` — disabled (no copy chord / OSC 52; native text paste still works).
+     * - a `{ writeText, readText }` **provider** — every copy/paste path routes
+     *   through it. Supply this in a sandboxed Electron renderer, where
+     *   `navigator.clipboard` silently no-ops, to bridge to the main-process
+     *   clipboard over IPC.
+     */
+    clipboard?: ClipboardOption;
+    /**
+     * OSC 52 clipboard policy — lets terminal programs (Claude Code, tmux, vim)
+     * set/read the system clipboard via `ESC ] 52`. `"copy"` (default) allows
+     * writes only; `"read"` / `"both"` also answer read requests (an exfiltration
+     * risk — opt in deliberately); `false` disables it. Routed through the same
+     * clipboard provider as {@link clipboard}; a no-op when clipboard is `false`.
+     * Default `"copy"`.
+     */
+    osc52?: Osc52Mode;
+    /**
+     * Copy/paste UX convention: `"contextmenu"` (menu + Ctrl+Shift+C),
+     * `"linux"` (highlight-to-copy + middle-click paste), or `"winmac"`
+     * (Ctrl/Cmd+C copies the selection, Ctrl/Cmd+V pastes). Omit for the historical
+     * default (Ctrl+Shift+C + Cmd+C-with-selection). Ctrl+Shift+C always copies.
+     */
+    copyPaste?: CopyPasteMode;
+    /**
+     * Called once the xterm instance is opened + attached — the imperative twin of
+     * {@link TerminalHandle.ready}. Use it to load an addon without racing the
+     * container layout (where `handle.xterm` is still null).
+     */
+    onReady?: (xterm: Terminal$1) => void;
+    /**
+     * Fired on every paste with the clipboard payload — `{ text, files, images }`.
+     * Plain text still pastes into the terminal natively; this is where a host
+     * receives pasted **images** (a shell can't render them) to upload / hand to an
+     * agent / write a path. Return `false` to fully consume the paste (suppress the
+     * default text paste — e.g. to transform it, then call `handle.paste(...)`).
+     */
+    onPaste?: (payload: ClipboardPayload) => void | boolean;
 }
-interface TerminalProps extends TerminalOptions, Omit<HTMLAttributes<HTMLDivElement>, "onInput" | "onResize" | "children"> {
+interface TerminalProps extends TerminalOptions, Omit<HTMLAttributes<HTMLDivElement>, "onInput" | "onResize" | "onPaste" | "contextMenu" | "children"> {
     /**
      * The controlled output buffer. The component diffs against the previous value
      * and writes only the appended delta, so a host can drive the terminal from
@@ -112,6 +333,13 @@ interface TerminalProps extends TerminalOptions, Omit<HTMLAttributes<HTMLDivElem
      * `shells` is provided. Default `false` — opt-in so existing layout is unchanged.
      */
     showShellBar?: boolean;
+    /**
+     * The right-click selection context menu. `false` disables it; `true` / omitted
+     * gives the default Copy / Paste / Select all / Clear menu; an array replaces
+     * the items; a `(ctx, defaults) => items` function lets you add/remove/reorder
+     * (e.g. append a "Send to agent" item). See {@link TerminalContextMenuConfig}.
+     */
+    contextMenu?: TerminalContextMenuConfig;
 }
 /**
  * Resolve a shell id to its {@link ShellProfile} within a list. Pure helper —
@@ -169,6 +397,22 @@ interface ShellSwitcherProps {
  */
 declare function ShellSwitcher({ shells, value, onChange, className, style, disabled, }: ShellSwitcherProps): react.JSX.Element;
 
+/**
+ * The terminal selection context menu. Deliberately plain React + inline styles
+ * (fancy-term has no react-fancy dependency) styled to match the shell bar. It
+ * closes on click-outside + Escape, and clamps itself inside the viewport on
+ * mount so a right-click near an edge never spills off-screen.
+ */
+declare function TerminalContextMenu({ at, items, ctx, onClose, }: {
+    at: {
+        x: number;
+        y: number;
+    };
+    items: TerminalContextMenuItem[];
+    ctx: TerminalContextMenuContext;
+    onClose: () => void;
+}): react.JSX.Element;
+
 /**
  * Create + own an xterm.js instance for a container, returning a stable
  * {@link TerminalHandle}. The headless engine layer behind `<Terminal>` — use it
@@ -257,4 +501,40 @@ declare function useTerminalSession(options: UseTerminalSessionOptions): Termina
  */
 declare const fancyDarkTheme: TerminalTheme;
 
-export { BUILTIN_SHELLS, type CursorStyle, type ShellProfile, ShellSwitcher, type ShellSwitcherProps, Terminal, type TerminalHandle, type TerminalOptions, type TerminalProps, type TerminalSessionApi, type TerminalSessionTransport, type TerminalTheme, type UseTerminalSessionOptions, fancyDarkTheme, resolveShell, useTerminal, useTerminalFit, useTerminalSession };
+/** The subset of a KeyboardEvent the copy decision reads. */
+interface CopyKeyEvent {
+    type: string;
+    key: string;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    metaKey: boolean;
+}
+/**
+ * Whether a key event should copy the current selection to the clipboard.
+ *
+ * - **Ctrl+Shift+C** (Windows / Linux terminal convention) — always.
+ * - **Cmd / Meta+C** (macOS) — only when there is a selection.
+ * - **Plain Ctrl+C is never a copy** — it must stay SIGINT.
+ *
+ * Only fires on `keydown`. When this returns true the caller copies the
+ * selection and consumes the event (returns `false` from xterm's
+ * `attachCustomKeyEventHandler` so no control byte is sent).
+ */
+declare function shouldCopyEvent(e: CopyKeyEvent, hasSelection: boolean): boolean;
+
+interface MenuPoint {
+    x: number;
+    y: number;
+}
+interface MenuSize {
+    width: number;
+    height: number;
+}
+/**
+ * Clamp a menu's top-left so the whole menu stays inside the viewport (minus a
+ * margin). Pushes left/up when it would overflow the right/bottom edge, and never
+ * goes past the top-left margin. Pure.
+ */
+declare function clampMenuPosition(at: MenuPoint, menu: MenuSize, viewport: MenuSize, margin?: number): MenuPoint;
+
+export { BUILTIN_SHELLS, type ClipboardOption, type ClipboardPayload, type ClipboardProvider, type CopyKeyEvent, type CopyPasteBehavior, type CopyPasteMode, type CursorStyle, type KeyEventLike, type Osc52Mode, type Osc52Request, type ShellProfile, ShellSwitcher, type ShellSwitcherProps, Terminal, TerminalContextMenu, type TerminalContextMenuConfig, type TerminalContextMenuContext, type TerminalContextMenuItem, type TerminalHandle, type TerminalMenuActions, type TerminalOptions, type TerminalProps, type TerminalSessionApi, type TerminalSessionTransport, type TerminalTheme, type UseTerminalSessionOptions, clampMenuPosition, copyPasteBehavior, decodeBase64, defaultMenuItems, encodeBase64, fancyDarkTheme, isImageFile, navigatorClipboard, osc52Response, parseOsc52, registerOsc52, resolveClipboard, resolveKeyAction, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };