@particle-academy/fancy-term 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 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 {
@@ -15,6 +15,107 @@ interface ClipboardPayload {
 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 {
@@ -96,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. */
@@ -160,11 +268,39 @@ interface TerminalOptions {
         rows: number;
     }) => void;
     /**
-     * Enable clipboard wiring — the Ctrl+Shift+C / Cmd+C copy chord and the paste
-     * interceptor (which surfaces pasted images via {@link onPaste}). Default true.
-     * Text paste works regardless; this gates the *enhanced* clipboard behavior.
+     * 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).
      */
-    clipboard?: boolean;
+    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
@@ -401,4 +537,4 @@ interface MenuSize {
  */
 declare function clampMenuPosition(at: MenuPoint, menu: MenuSize, viewport: MenuSize, margin?: number): MenuPoint;
 
-export { BUILTIN_SHELLS, type ClipboardPayload, type CopyKeyEvent, type CursorStyle, 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, defaultMenuItems, fancyDarkTheme, isImageFile, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };
+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,6 @@
 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 {
@@ -15,6 +15,107 @@ interface ClipboardPayload {
 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 {
@@ -96,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. */
@@ -160,11 +268,39 @@ interface TerminalOptions {
         rows: number;
     }) => void;
     /**
-     * Enable clipboard wiring — the Ctrl+Shift+C / Cmd+C copy chord and the paste
-     * interceptor (which surfaces pasted images via {@link onPaste}). Default true.
-     * Text paste works regardless; this gates the *enhanced* clipboard behavior.
+     * 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).
      */
-    clipboard?: boolean;
+    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
@@ -401,4 +537,4 @@ interface MenuSize {
  */
 declare function clampMenuPosition(at: MenuPoint, menu: MenuSize, viewport: MenuSize, margin?: number): MenuPoint;
 
-export { BUILTIN_SHELLS, type ClipboardPayload, type CopyKeyEvent, type CursorStyle, 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, defaultMenuItems, fancyDarkTheme, isImageFile, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };
+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.js

@@ -111,18 +111,120 @@ async function readClipboardText() {
   }
   return "";
 }
+var navigatorClipboard = {
+  writeText: (text) => writeClipboardText(text),
+  readText: () => readClipboardText()
+};
+function resolveClipboard(clipboard) {
+  if (clipboard === false) return { enabled: false, provider: navigatorClipboard };
+  if (clipboard && typeof clipboard === "object") return { enabled: true, provider: clipboard };
+  return { enabled: true, provider: navigatorClipboard };
+}
+async function providerWrite(provider, text) {
+  try {
+    await provider.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function providerRead(provider) {
+  try {
+    return await provider.readText() ?? "";
+  } catch {
+    return "";
+  }
+}
 
-// src/copy-keybinding.ts
-function shouldCopyEvent(e, hasSelection) {
-  if (e.type !== "keydown") return false;
-  if (e.key !== "c" && e.key !== "C") return false;
-  if (e.ctrlKey && e.shiftKey && !e.metaKey) return true;
-  if (e.metaKey && !e.ctrlKey && hasSelection) return true;
-  return false;
+// src/copy-paste-mode.ts
+function copyPasteBehavior(mode) {
+  switch (mode) {
+    case "linux":
+      return { selectToCopy: true, middleClickPaste: true, keyCopy: false, keyPaste: false };
+    case "winmac":
+      return { selectToCopy: false, middleClickPaste: false, keyCopy: true, keyPaste: true };
+    case "contextmenu":
+    default:
+      return { selectToCopy: false, middleClickPaste: false, keyCopy: false, keyPaste: false };
+  }
+}
+function resolveKeyAction(e, hasSelection, behavior) {
+  if (e.type !== "keydown") return null;
+  const key = e.key.toLowerCase();
+  if (key === "c") {
+    if (e.ctrlKey && e.shiftKey && !e.metaKey) return "copy";
+    if (e.metaKey && !e.ctrlKey && hasSelection) return "copy";
+    if (behavior.keyCopy && (e.ctrlKey || e.metaKey) && !e.shiftKey && hasSelection) return "copy";
+    return null;
+  }
+  if (key === "v" && behavior.keyPaste) {
+    if ((e.ctrlKey || e.metaKey) && !e.shiftKey) return "paste";
+    if (e.ctrlKey && e.shiftKey) return "paste";
+    return null;
+  }
+  return null;
+}
+
+// src/osc52.ts
+function encodeBase64(text) {
+  const bytes = new TextEncoder().encode(text);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return typeof btoa === "function" ? btoa(binary) : binary;
+}
+function decodeBase64(b64) {
+  try {
+    const binary = typeof atob === "function" ? atob(b64) : b64;
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return "";
+  }
+}
+function parseOsc52(payload) {
+  const semi = payload.indexOf(";");
+  if (semi < 0) return null;
+  const selection = payload.slice(0, semi);
+  const pd = payload.slice(semi + 1);
+  if (pd === "?") return { selection, kind: "read", data: "" };
+  return { selection, kind: "write", data: decodeBase64(pd) };
+}
+function osc52Response(selection, text) {
+  return `\x1B]52;${selection};${encodeBase64(text)}\x07`;
+}
+function registerOsc52(term, provider, mode) {
+  if (mode() === false) return null;
+  return term.parser.registerOscHandler(52, (payload) => {
+    const m = mode();
+    if (m === false) return true;
+    const req = parseOsc52(payload);
+    if (!req) return false;
+    if (req.kind === "write") {
+      if (m === "copy" || m === "both") {
+        void Promise.resolve(provider().writeText(req.data)).catch(() => {
+        });
+      }
+      return true;
+    }
+    if (m === "read" || m === "both") {
+      void providerRead(provider()).then((text) => {
+        term.write(osc52Response(req.selection, text));
+      });
+    }
+    return true;
+  });
 }
 
 // src/hooks/use-terminal.ts
 var DEFAULT_FONT = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
+function makeDeferred() {
+  let resolve;
+  const promise = new Promise((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
 function readBuffer(term) {
   if (!term) return "";
   const buf = term.buffer.active;
@@ -138,12 +240,16 @@ function useTerminal(containerRef, options = {}) {
   const fitRef = useRef(null);
   const optsRef = useRef(options);
   optsRef.current = options;
+  const readyRef = useRef(makeDeferred());
   const handleRef = useRef(null);
   if (handleRef.current === null) {
     handleRef.current = {
       get xterm() {
         return xtermRef.current;
       },
+      get ready() {
+        return readyRef.current.promise;
+      },
       write: (d) => xtermRef.current?.write(d),
       writeln: (d) => xtermRef.current?.writeln(d),
       clear: () => xtermRef.current?.clear(),
@@ -166,10 +272,10 @@ function useTerminal(containerRef, options = {}) {
       copySelection: async () => {
         const sel = xtermRef.current?.getSelection() ?? "";
         if (!sel) return false;
-        return writeClipboardText(sel);
+        return providerWrite(resolveClipboard(optsRef.current.clipboard).provider, sel);
       },
       paste: async (text) => {
-        const data = text ?? await readClipboardText();
+        const data = text ?? await providerRead(resolveClipboard(optsRef.current.clipboard).provider);
         if (data) xtermRef.current?.paste(data);
       },
       selectAll: () => xtermRef.current?.selectAll(),
@@ -211,17 +317,54 @@ function useTerminal(containerRef, options = {}) {
     const resizeSub = term.onResize(
       ({ cols, rows }) => optsRef.current.onResize?.({ cols, rows })
     );
+    const pasteFromClipboard = async () => {
+      const oo = optsRef.current;
+      if (oo.readOnly) return;
+      const text = await providerRead(resolveClipboard(oo.clipboard).provider);
+      if (text) xtermRef.current?.paste(text);
+    };
     term.attachCustomKeyEventHandler((e) => {
-      if (optsRef.current.clipboard === false) return true;
-      if (shouldCopyEvent(e, term.hasSelection())) {
-        void writeClipboardText(term.getSelection());
+      const oo = optsRef.current;
+      const clip = resolveClipboard(oo.clipboard);
+      if (!clip.enabled) return true;
+      const action = resolveKeyAction(e, term.hasSelection(), copyPasteBehavior(oo.copyPaste));
+      if (action === "copy") {
+        void providerWrite(clip.provider, term.getSelection());
+        return false;
+      }
+      if (action === "paste") {
+        void pasteFromClipboard();
         return false;
       }
       return true;
     });
+    const oscDisposable = registerOsc52(
+      term,
+      () => resolveClipboard(optsRef.current.clipboard).provider,
+      () => {
+        const oo = optsRef.current;
+        return resolveClipboard(oo.clipboard).enabled ? oo.osc52 ?? "copy" : false;
+      }
+    );
+    const selectionSub = term.onSelectionChange(() => {
+      const oo = optsRef.current;
+      const clip = resolveClipboard(oo.clipboard);
+      if (clip.enabled && copyPasteBehavior(oo.copyPaste).selectToCopy && term.hasSelection()) {
+        void providerWrite(clip.provider, term.getSelection());
+      }
+    });
+    const onMouseDown = (ev) => {
+      const oo = optsRef.current;
+      if (ev.button !== 1) return;
+      if (!resolveClipboard(oo.clipboard).enabled) return;
+      if (!copyPasteBehavior(oo.copyPaste).middleClickPaste) return;
+      ev.preventDefault();
+      void pasteFromClipboard();
+    };
+    el.addEventListener("mousedown", onMouseDown);
     const onPasteEvent = (e) => {
       const o2 = optsRef.current;
-      if (o2.clipboard === false) return;
+      if (resolveClipboard(o2.clipboard).enabled === false) return;
       if (o2.readOnly) {
         e.preventDefault();
         return;
@@ -232,13 +375,19 @@ function useTerminal(containerRef, options = {}) {
     el.addEventListener("paste", onPasteEvent, true);
     if (o.initialOutput) term.write(o.initialOutput);
     if (o.fit ?? true) handle.fit();
+    optsRef.current.onReady?.(term);
+    readyRef.current.resolve(term);
     return () => {
       el.removeEventListener("paste", onPasteEvent, true);
+      el.removeEventListener("mousedown", onMouseDown);
+      oscDisposable?.dispose();
+      selectionSub.dispose();
       dataSub.dispose();
       resizeSub.dispose();
       term.dispose();
       xtermRef.current = null;
       fitRef.current = null;
+      readyRef.current = makeDeferred();
     };
   }, [containerRef]);
   useEffect(() => {
@@ -638,6 +787,9 @@ var Terminal = forwardRef(function Terminal2({
   onShellChange,
   showShellBar = false,
   clipboard,
+  osc52,
+  copyPaste,
+  onReady,
   onPaste,
   contextMenu,
   className,
@@ -674,12 +826,32 @@ var Terminal = forwardRef(function Terminal2({
     onData,
     onResize,
     clipboard,
+    osc52,
+    copyPaste,
+    onReady,
     onPaste
   });
   useImperativeHandle(
     ref,
     () => ({
-      ...handle,
+      get xterm() {
+        return handle.xterm;
+      },
+      get ready() {
+        return handle.ready;
+      },
+      write: handle.write,
+      writeln: handle.writeln,
+      clear: handle.clear,
+      reset: handle.reset,
+      fit: handle.fit,
+      focus: handle.focus,
+      getBuffer: handle.getBuffer,
+      getSelection: handle.getSelection,
+      copySelection: handle.copySelection,
+      paste: handle.paste,
+      selectAll: handle.selectAll,
+      clearSelection: handle.clearSelection,
       setShell: selectShell,
       getShell: () => shellStateRef.current.shellId
     }),
@@ -814,6 +986,15 @@ function useTerminalSession(options) {
   return { output, sendData, append, clear, shell, switchShell };
 }
 
-export { BUILTIN_SHELLS, ShellSwitcher, Terminal, TerminalContextMenu, clampMenuPosition, defaultMenuItems, fancyDarkTheme, isImageFile, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };
+// src/copy-keybinding.ts
+function shouldCopyEvent(e, hasSelection) {
+  if (e.type !== "keydown") return false;
+  if (e.key !== "c" && e.key !== "C") return false;
+  if (e.ctrlKey && e.shiftKey && !e.metaKey) return true;
+  if (e.metaKey && !e.ctrlKey && hasSelection) return true;
+  return false;
+}
+
+export { BUILTIN_SHELLS, ShellSwitcher, Terminal, TerminalContextMenu, clampMenuPosition, copyPasteBehavior, decodeBase64, defaultMenuItems, encodeBase64, fancyDarkTheme, isImageFile, navigatorClipboard, osc52Response, parseOsc52, registerOsc52, resolveClipboard, resolveKeyAction, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map