@particle-academy/fancy-term 0.3.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -2
- package/dist/index.cjs +233 -17
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +169 -7
- package/dist/index.d.ts +169 -7
- package/dist/index.js +224 -18
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as react from 'react';
|
|
2
2
|
import { HTMLAttributes, CSSProperties, RefObject } from 'react';
|
|
3
|
-
import {
|
|
3
|
+
import { Terminal as Terminal$1, IDisposable, ITheme } from '@xterm/xterm';
|
|
4
4
|
|
|
5
5
|
/** What a paste / drop carried: plain text plus any files (e.g. pasted images). */
|
|
6
6
|
interface ClipboardPayload {
|
|
@@ -15,6 +15,107 @@ interface ClipboardPayload {
|
|
|
15
15
|
declare function isImageFile(f: {
|
|
16
16
|
type?: string;
|
|
17
17
|
}): boolean;
|
|
18
|
+
/**
|
|
19
|
+
* A host-supplied clipboard. Every copy/paste path in fancy-term — the copy
|
|
20
|
+
* chord, the context menu, OSC 52, `handle.copySelection` / `handle.paste` —
|
|
21
|
+
* routes through this, so an Electron host (where `navigator.clipboard` silently
|
|
22
|
+
* no-ops in a sandboxed renderer) can bridge to its main-process clipboard over
|
|
23
|
+
* IPC. `writeText` may return anything (a `Promise<void>` from IPC is fine);
|
|
24
|
+
* `readText` returns the clipboard text.
|
|
25
|
+
*/
|
|
26
|
+
interface ClipboardProvider {
|
|
27
|
+
writeText: (text: string) => void | Promise<unknown>;
|
|
28
|
+
readText: () => string | Promise<string>;
|
|
29
|
+
}
|
|
30
|
+
/** The default provider — `navigator.clipboard` with the legacy `execCommand` fallback. */
|
|
31
|
+
declare const navigatorClipboard: ClipboardProvider;
|
|
32
|
+
/** The `clipboard` prop: `false` disables clipboard wiring; a provider object injects a host clipboard; `true`/omitted uses {@link navigatorClipboard}. */
|
|
33
|
+
type ClipboardOption = boolean | ClipboardProvider;
|
|
34
|
+
/** Normalize the `clipboard` prop into `{ enabled, provider }`, read live per call. */
|
|
35
|
+
declare function resolveClipboard(clipboard: ClipboardOption | undefined): {
|
|
36
|
+
enabled: boolean;
|
|
37
|
+
provider: ClipboardProvider;
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* The copy/paste convention the terminal follows:
|
|
42
|
+
* - `contextmenu` — copy/paste via the right-click menu only (plus the always-on
|
|
43
|
+
* Ctrl+Shift+C copy chord).
|
|
44
|
+
* - `linux` — highlight-to-copy (X11 primary-selection style) + middle-click
|
|
45
|
+
* paste. Right-click still opens the context menu.
|
|
46
|
+
* - `winmac` — Ctrl/Cmd+C copies the selection (falling back to SIGINT when
|
|
47
|
+
* nothing is selected), Ctrl/Cmd+V pastes.
|
|
48
|
+
*
|
|
49
|
+
* Omitting the prop keeps the historical default: the Ctrl+Shift+C chord and
|
|
50
|
+
* Cmd+C-with-selection, no auto-copy, no mouse paste.
|
|
51
|
+
*/
|
|
52
|
+
type CopyPasteMode = "contextmenu" | "linux" | "winmac";
|
|
53
|
+
/** The resolved, event-agnostic behavior flags a {@link CopyPasteMode} implies. */
|
|
54
|
+
interface CopyPasteBehavior {
|
|
55
|
+
/** Auto-copy the selection to the clipboard as soon as it changes (linux). */
|
|
56
|
+
selectToCopy: boolean;
|
|
57
|
+
/** Paste on middle-mouse-button (linux). */
|
|
58
|
+
middleClickPaste: boolean;
|
|
59
|
+
/** (Ctrl|Cmd)+C copies the selection when one exists (winmac). */
|
|
60
|
+
keyCopy: boolean;
|
|
61
|
+
/** (Ctrl|Cmd)+V — and Ctrl+Shift+V — paste (winmac). */
|
|
62
|
+
keyPaste: boolean;
|
|
63
|
+
}
|
|
64
|
+
declare function copyPasteBehavior(mode: CopyPasteMode | undefined): CopyPasteBehavior;
|
|
65
|
+
/** The subset of a KeyboardEvent the copy/paste decision reads. */
|
|
66
|
+
interface KeyEventLike {
|
|
67
|
+
type: string;
|
|
68
|
+
key: string;
|
|
69
|
+
ctrlKey: boolean;
|
|
70
|
+
shiftKey: boolean;
|
|
71
|
+
metaKey: boolean;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Resolve a key event to a clipboard action, given the current selection state
|
|
75
|
+
* and the active behavior. Returns `"copy"`, `"paste"`, or `null` (do nothing —
|
|
76
|
+
* let the byte reach the shell). Only fires on `keydown`.
|
|
77
|
+
*
|
|
78
|
+
* Copy is honored across every mode for the terminal-safe **Ctrl+Shift+C** chord
|
|
79
|
+
* and macOS **Cmd+C-with-selection**; `keyCopy` adds plain (Ctrl|Cmd)+C. Plain
|
|
80
|
+
* Ctrl+C with no selection is never a copy — it stays SIGINT.
|
|
81
|
+
*/
|
|
82
|
+
declare function resolveKeyAction(e: KeyEventLike, hasSelection: boolean, behavior: CopyPasteBehavior): "copy" | "paste" | null;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* OSC 52 policy: `copy` allows programs to WRITE the clipboard (the common TUI
|
|
86
|
+
* case), `read` allows a program to READ it back (a `?` request), `both` allows
|
|
87
|
+
* either, `false` disables OSC 52 entirely. Read is the real exfiltration risk
|
|
88
|
+
* (arbitrary terminal output could siphon your clipboard), so it must be opted
|
|
89
|
+
* into explicitly.
|
|
90
|
+
*/
|
|
91
|
+
type Osc52Mode = "copy" | "read" | "both" | false;
|
|
92
|
+
/** A parsed OSC 52 request: which selection buffer, and write-a-payload vs read-request. */
|
|
93
|
+
interface Osc52Request {
|
|
94
|
+
/** The `Pc` field — clipboard selection(s), e.g. `"c"` (clipboard), `"p"` (primary). */
|
|
95
|
+
selection: string;
|
|
96
|
+
kind: "write" | "read";
|
|
97
|
+
/** Decoded text for a write; `""` for a read request. */
|
|
98
|
+
data: string;
|
|
99
|
+
}
|
|
100
|
+
/** UTF-8-safe base64 encode (browser `btoa` operates on binary strings). */
|
|
101
|
+
declare function encodeBase64(text: string): string;
|
|
102
|
+
/** UTF-8-safe base64 decode; returns `""` on malformed input. */
|
|
103
|
+
declare function decodeBase64(b64: string): string;
|
|
104
|
+
/**
|
|
105
|
+
* Parse an OSC 52 payload (the part after `ESC ] 52 ;`, i.e. `<Pc> ; <Pd>`).
|
|
106
|
+
* `Pd === "?"` is a read request; otherwise `Pd` is base64 to write. Returns
|
|
107
|
+
* `null` for a malformed payload (no `;`).
|
|
108
|
+
*/
|
|
109
|
+
declare function parseOsc52(payload: string): Osc52Request | null;
|
|
110
|
+
/** Build the OSC 52 response a `read` request expects: `ESC ] 52 ; <Pc> ; <base64> BEL`. */
|
|
111
|
+
declare function osc52Response(selection: string, text: string): string;
|
|
112
|
+
/**
|
|
113
|
+
* Register an OSC 52 handler on an xterm instance, routing writes/reads through
|
|
114
|
+
* `provider` per `mode`. Returns the {@link IDisposable} (or `null` when
|
|
115
|
+
* `mode === false`). The handler always returns `true` (consumed) so a
|
|
116
|
+
* disallowed direction is swallowed rather than echoed as garbage.
|
|
117
|
+
*/
|
|
118
|
+
declare function registerOsc52(term: Terminal$1, provider: () => ClipboardProvider, mode: () => Osc52Mode): IDisposable | null;
|
|
18
119
|
|
|
19
120
|
/** Context handed to the menu at right-click time + to custom item builders. */
|
|
20
121
|
interface TerminalContextMenuContext {
|
|
@@ -42,7 +143,13 @@ interface TerminalContextMenuItem {
|
|
|
42
143
|
}
|
|
43
144
|
/** The actions the built-in items dispatch to (wired by the component). */
|
|
44
145
|
interface TerminalMenuActions {
|
|
45
|
-
|
|
146
|
+
/**
|
|
147
|
+
* Receives the menu's {@link TerminalContextMenuContext} so it can copy the
|
|
148
|
+
* selection **snapshotted when the menu opened** — by click time the live
|
|
149
|
+
* xterm selection is often already cleared (a mouse-reporting TUI's redraw
|
|
150
|
+
* clears it right after the right-click), so re-reading it copies nothing.
|
|
151
|
+
*/
|
|
152
|
+
copy: (ctx: TerminalContextMenuContext) => void;
|
|
46
153
|
paste: () => void;
|
|
47
154
|
selectAll: () => void;
|
|
48
155
|
clear: () => void;
|
|
@@ -96,6 +203,13 @@ interface ShellProfile {
|
|
|
96
203
|
interface TerminalHandle {
|
|
97
204
|
/** The underlying xterm.js instance — escape hatch for addons / advanced use. Null before mount. */
|
|
98
205
|
readonly xterm: Terminal$1 | null;
|
|
206
|
+
/**
|
|
207
|
+
* Resolves with the xterm instance once it's opened + measured. Because
|
|
208
|
+
* `xterm` is null until the container lays out, a consumer that must wire an
|
|
209
|
+
* addon can `await handle.ready` instead of polling. Re-armed if the terminal
|
|
210
|
+
* is torn down + recreated (e.g. a container change).
|
|
211
|
+
*/
|
|
212
|
+
readonly ready: Promise<Terminal$1>;
|
|
99
213
|
/** Write raw data (ANSI escape sequences honored) to the terminal. */
|
|
100
214
|
write: (data: string) => void;
|
|
101
215
|
/** Write data followed by CRLF. */
|
|
@@ -160,11 +274,39 @@ interface TerminalOptions {
|
|
|
160
274
|
rows: number;
|
|
161
275
|
}) => void;
|
|
162
276
|
/**
|
|
163
|
-
*
|
|
164
|
-
* interceptor (
|
|
165
|
-
*
|
|
277
|
+
* Clipboard wiring — gates the Ctrl+Shift+C / Cmd+C copy chord, the paste
|
|
278
|
+
* interceptor ({@link onPaste}), the context-menu copy/paste, and OSC 52.
|
|
279
|
+
*
|
|
280
|
+
* - `true` / omitted — enabled, backed by `navigator.clipboard`.
|
|
281
|
+
* - `false` — disabled (no copy chord / OSC 52; native text paste still works).
|
|
282
|
+
* - a `{ writeText, readText }` **provider** — every copy/paste path routes
|
|
283
|
+
* through it. Supply this in a sandboxed Electron renderer, where
|
|
284
|
+
* `navigator.clipboard` silently no-ops, to bridge to the main-process
|
|
285
|
+
* clipboard over IPC.
|
|
286
|
+
*/
|
|
287
|
+
clipboard?: ClipboardOption;
|
|
288
|
+
/**
|
|
289
|
+
* OSC 52 clipboard policy — lets terminal programs (Claude Code, tmux, vim)
|
|
290
|
+
* set/read the system clipboard via `ESC ] 52`. `"copy"` (default) allows
|
|
291
|
+
* writes only; `"read"` / `"both"` also answer read requests (an exfiltration
|
|
292
|
+
* risk — opt in deliberately); `false` disables it. Routed through the same
|
|
293
|
+
* clipboard provider as {@link clipboard}; a no-op when clipboard is `false`.
|
|
294
|
+
* Default `"copy"`.
|
|
295
|
+
*/
|
|
296
|
+
osc52?: Osc52Mode;
|
|
297
|
+
/**
|
|
298
|
+
* Copy/paste UX convention: `"contextmenu"` (menu + Ctrl+Shift+C),
|
|
299
|
+
* `"linux"` (highlight-to-copy + middle-click paste), or `"winmac"`
|
|
300
|
+
* (Ctrl/Cmd+C copies the selection, Ctrl/Cmd+V pastes). Omit for the historical
|
|
301
|
+
* default (Ctrl+Shift+C + Cmd+C-with-selection). Ctrl+Shift+C always copies.
|
|
302
|
+
*/
|
|
303
|
+
copyPaste?: CopyPasteMode;
|
|
304
|
+
/**
|
|
305
|
+
* Called once the xterm instance is opened + attached — the imperative twin of
|
|
306
|
+
* {@link TerminalHandle.ready}. Use it to load an addon without racing the
|
|
307
|
+
* container layout (where `handle.xterm` is still null).
|
|
166
308
|
*/
|
|
167
|
-
|
|
309
|
+
onReady?: (xterm: Terminal$1) => void;
|
|
168
310
|
/**
|
|
169
311
|
* Fired on every paste with the clipboard payload — `{ text, files, images }`.
|
|
170
312
|
* Plain text still pastes into the terminal natively; this is where a host
|
|
@@ -401,4 +543,24 @@ interface MenuSize {
|
|
|
401
543
|
*/
|
|
402
544
|
declare function clampMenuPosition(at: MenuPoint, menu: MenuSize, viewport: MenuSize, margin?: number): MenuPoint;
|
|
403
545
|
|
|
404
|
-
|
|
546
|
+
/** The bits of a pointer event the snapshot decision needs. */
|
|
547
|
+
interface SnapshotPointerEvent {
|
|
548
|
+
type: "mousedown" | "mouseup";
|
|
549
|
+
/** 0 = left, 1 = middle, 2 = right. */
|
|
550
|
+
button: number;
|
|
551
|
+
}
|
|
552
|
+
/**
|
|
553
|
+
* Compute the next selection snapshot after a pointer event on the terminal
|
|
554
|
+
* surface.
|
|
555
|
+
*
|
|
556
|
+
* - A fresh **left press** starts a new gesture — drop the snapshot (the live
|
|
557
|
+
* selection still reads the *old* text at capture time, so it must not win).
|
|
558
|
+
* - Otherwise a **non-empty live selection** always refreshes the snapshot
|
|
559
|
+
* (drag-select completes on left mouseup; a right press re-captures while
|
|
560
|
+
* the selection is still alive).
|
|
561
|
+
* - An **empty** live selection keeps the previous snapshot — that's exactly
|
|
562
|
+
* the TUI-cleared-it-under-us case the snapshot exists for.
|
|
563
|
+
*/
|
|
564
|
+
declare function nextSelectionSnapshot(prev: string, event: SnapshotPointerEvent, liveSelection: string): string;
|
|
565
|
+
|
|
566
|
+
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, type SnapshotPointerEvent, 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, nextSelectionSnapshot, osc52Response, parseOsc52, registerOsc52, resolveClipboard, resolveKeyAction, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as react from 'react';
|
|
2
2
|
import { HTMLAttributes, CSSProperties, RefObject } from 'react';
|
|
3
|
-
import {
|
|
3
|
+
import { Terminal as Terminal$1, IDisposable, ITheme } from '@xterm/xterm';
|
|
4
4
|
|
|
5
5
|
/** What a paste / drop carried: plain text plus any files (e.g. pasted images). */
|
|
6
6
|
interface ClipboardPayload {
|
|
@@ -15,6 +15,107 @@ interface ClipboardPayload {
|
|
|
15
15
|
declare function isImageFile(f: {
|
|
16
16
|
type?: string;
|
|
17
17
|
}): boolean;
|
|
18
|
+
/**
|
|
19
|
+
* A host-supplied clipboard. Every copy/paste path in fancy-term — the copy
|
|
20
|
+
* chord, the context menu, OSC 52, `handle.copySelection` / `handle.paste` —
|
|
21
|
+
* routes through this, so an Electron host (where `navigator.clipboard` silently
|
|
22
|
+
* no-ops in a sandboxed renderer) can bridge to its main-process clipboard over
|
|
23
|
+
* IPC. `writeText` may return anything (a `Promise<void>` from IPC is fine);
|
|
24
|
+
* `readText` returns the clipboard text.
|
|
25
|
+
*/
|
|
26
|
+
interface ClipboardProvider {
|
|
27
|
+
writeText: (text: string) => void | Promise<unknown>;
|
|
28
|
+
readText: () => string | Promise<string>;
|
|
29
|
+
}
|
|
30
|
+
/** The default provider — `navigator.clipboard` with the legacy `execCommand` fallback. */
|
|
31
|
+
declare const navigatorClipboard: ClipboardProvider;
|
|
32
|
+
/** The `clipboard` prop: `false` disables clipboard wiring; a provider object injects a host clipboard; `true`/omitted uses {@link navigatorClipboard}. */
|
|
33
|
+
type ClipboardOption = boolean | ClipboardProvider;
|
|
34
|
+
/** Normalize the `clipboard` prop into `{ enabled, provider }`, read live per call. */
|
|
35
|
+
declare function resolveClipboard(clipboard: ClipboardOption | undefined): {
|
|
36
|
+
enabled: boolean;
|
|
37
|
+
provider: ClipboardProvider;
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* The copy/paste convention the terminal follows:
|
|
42
|
+
* - `contextmenu` — copy/paste via the right-click menu only (plus the always-on
|
|
43
|
+
* Ctrl+Shift+C copy chord).
|
|
44
|
+
* - `linux` — highlight-to-copy (X11 primary-selection style) + middle-click
|
|
45
|
+
* paste. Right-click still opens the context menu.
|
|
46
|
+
* - `winmac` — Ctrl/Cmd+C copies the selection (falling back to SIGINT when
|
|
47
|
+
* nothing is selected), Ctrl/Cmd+V pastes.
|
|
48
|
+
*
|
|
49
|
+
* Omitting the prop keeps the historical default: the Ctrl+Shift+C chord and
|
|
50
|
+
* Cmd+C-with-selection, no auto-copy, no mouse paste.
|
|
51
|
+
*/
|
|
52
|
+
type CopyPasteMode = "contextmenu" | "linux" | "winmac";
|
|
53
|
+
/** The resolved, event-agnostic behavior flags a {@link CopyPasteMode} implies. */
|
|
54
|
+
interface CopyPasteBehavior {
|
|
55
|
+
/** Auto-copy the selection to the clipboard as soon as it changes (linux). */
|
|
56
|
+
selectToCopy: boolean;
|
|
57
|
+
/** Paste on middle-mouse-button (linux). */
|
|
58
|
+
middleClickPaste: boolean;
|
|
59
|
+
/** (Ctrl|Cmd)+C copies the selection when one exists (winmac). */
|
|
60
|
+
keyCopy: boolean;
|
|
61
|
+
/** (Ctrl|Cmd)+V — and Ctrl+Shift+V — paste (winmac). */
|
|
62
|
+
keyPaste: boolean;
|
|
63
|
+
}
|
|
64
|
+
declare function copyPasteBehavior(mode: CopyPasteMode | undefined): CopyPasteBehavior;
|
|
65
|
+
/** The subset of a KeyboardEvent the copy/paste decision reads. */
|
|
66
|
+
interface KeyEventLike {
|
|
67
|
+
type: string;
|
|
68
|
+
key: string;
|
|
69
|
+
ctrlKey: boolean;
|
|
70
|
+
shiftKey: boolean;
|
|
71
|
+
metaKey: boolean;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Resolve a key event to a clipboard action, given the current selection state
|
|
75
|
+
* and the active behavior. Returns `"copy"`, `"paste"`, or `null` (do nothing —
|
|
76
|
+
* let the byte reach the shell). Only fires on `keydown`.
|
|
77
|
+
*
|
|
78
|
+
* Copy is honored across every mode for the terminal-safe **Ctrl+Shift+C** chord
|
|
79
|
+
* and macOS **Cmd+C-with-selection**; `keyCopy` adds plain (Ctrl|Cmd)+C. Plain
|
|
80
|
+
* Ctrl+C with no selection is never a copy — it stays SIGINT.
|
|
81
|
+
*/
|
|
82
|
+
declare function resolveKeyAction(e: KeyEventLike, hasSelection: boolean, behavior: CopyPasteBehavior): "copy" | "paste" | null;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* OSC 52 policy: `copy` allows programs to WRITE the clipboard (the common TUI
|
|
86
|
+
* case), `read` allows a program to READ it back (a `?` request), `both` allows
|
|
87
|
+
* either, `false` disables OSC 52 entirely. Read is the real exfiltration risk
|
|
88
|
+
* (arbitrary terminal output could siphon your clipboard), so it must be opted
|
|
89
|
+
* into explicitly.
|
|
90
|
+
*/
|
|
91
|
+
type Osc52Mode = "copy" | "read" | "both" | false;
|
|
92
|
+
/** A parsed OSC 52 request: which selection buffer, and write-a-payload vs read-request. */
|
|
93
|
+
interface Osc52Request {
|
|
94
|
+
/** The `Pc` field — clipboard selection(s), e.g. `"c"` (clipboard), `"p"` (primary). */
|
|
95
|
+
selection: string;
|
|
96
|
+
kind: "write" | "read";
|
|
97
|
+
/** Decoded text for a write; `""` for a read request. */
|
|
98
|
+
data: string;
|
|
99
|
+
}
|
|
100
|
+
/** UTF-8-safe base64 encode (browser `btoa` operates on binary strings). */
|
|
101
|
+
declare function encodeBase64(text: string): string;
|
|
102
|
+
/** UTF-8-safe base64 decode; returns `""` on malformed input. */
|
|
103
|
+
declare function decodeBase64(b64: string): string;
|
|
104
|
+
/**
|
|
105
|
+
* Parse an OSC 52 payload (the part after `ESC ] 52 ;`, i.e. `<Pc> ; <Pd>`).
|
|
106
|
+
* `Pd === "?"` is a read request; otherwise `Pd` is base64 to write. Returns
|
|
107
|
+
* `null` for a malformed payload (no `;`).
|
|
108
|
+
*/
|
|
109
|
+
declare function parseOsc52(payload: string): Osc52Request | null;
|
|
110
|
+
/** Build the OSC 52 response a `read` request expects: `ESC ] 52 ; <Pc> ; <base64> BEL`. */
|
|
111
|
+
declare function osc52Response(selection: string, text: string): string;
|
|
112
|
+
/**
|
|
113
|
+
* Register an OSC 52 handler on an xterm instance, routing writes/reads through
|
|
114
|
+
* `provider` per `mode`. Returns the {@link IDisposable} (or `null` when
|
|
115
|
+
* `mode === false`). The handler always returns `true` (consumed) so a
|
|
116
|
+
* disallowed direction is swallowed rather than echoed as garbage.
|
|
117
|
+
*/
|
|
118
|
+
declare function registerOsc52(term: Terminal$1, provider: () => ClipboardProvider, mode: () => Osc52Mode): IDisposable | null;
|
|
18
119
|
|
|
19
120
|
/** Context handed to the menu at right-click time + to custom item builders. */
|
|
20
121
|
interface TerminalContextMenuContext {
|
|
@@ -42,7 +143,13 @@ interface TerminalContextMenuItem {
|
|
|
42
143
|
}
|
|
43
144
|
/** The actions the built-in items dispatch to (wired by the component). */
|
|
44
145
|
interface TerminalMenuActions {
|
|
45
|
-
|
|
146
|
+
/**
|
|
147
|
+
* Receives the menu's {@link TerminalContextMenuContext} so it can copy the
|
|
148
|
+
* selection **snapshotted when the menu opened** — by click time the live
|
|
149
|
+
* xterm selection is often already cleared (a mouse-reporting TUI's redraw
|
|
150
|
+
* clears it right after the right-click), so re-reading it copies nothing.
|
|
151
|
+
*/
|
|
152
|
+
copy: (ctx: TerminalContextMenuContext) => void;
|
|
46
153
|
paste: () => void;
|
|
47
154
|
selectAll: () => void;
|
|
48
155
|
clear: () => void;
|
|
@@ -96,6 +203,13 @@ interface ShellProfile {
|
|
|
96
203
|
interface TerminalHandle {
|
|
97
204
|
/** The underlying xterm.js instance — escape hatch for addons / advanced use. Null before mount. */
|
|
98
205
|
readonly xterm: Terminal$1 | null;
|
|
206
|
+
/**
|
|
207
|
+
* Resolves with the xterm instance once it's opened + measured. Because
|
|
208
|
+
* `xterm` is null until the container lays out, a consumer that must wire an
|
|
209
|
+
* addon can `await handle.ready` instead of polling. Re-armed if the terminal
|
|
210
|
+
* is torn down + recreated (e.g. a container change).
|
|
211
|
+
*/
|
|
212
|
+
readonly ready: Promise<Terminal$1>;
|
|
99
213
|
/** Write raw data (ANSI escape sequences honored) to the terminal. */
|
|
100
214
|
write: (data: string) => void;
|
|
101
215
|
/** Write data followed by CRLF. */
|
|
@@ -160,11 +274,39 @@ interface TerminalOptions {
|
|
|
160
274
|
rows: number;
|
|
161
275
|
}) => void;
|
|
162
276
|
/**
|
|
163
|
-
*
|
|
164
|
-
* interceptor (
|
|
165
|
-
*
|
|
277
|
+
* Clipboard wiring — gates the Ctrl+Shift+C / Cmd+C copy chord, the paste
|
|
278
|
+
* interceptor ({@link onPaste}), the context-menu copy/paste, and OSC 52.
|
|
279
|
+
*
|
|
280
|
+
* - `true` / omitted — enabled, backed by `navigator.clipboard`.
|
|
281
|
+
* - `false` — disabled (no copy chord / OSC 52; native text paste still works).
|
|
282
|
+
* - a `{ writeText, readText }` **provider** — every copy/paste path routes
|
|
283
|
+
* through it. Supply this in a sandboxed Electron renderer, where
|
|
284
|
+
* `navigator.clipboard` silently no-ops, to bridge to the main-process
|
|
285
|
+
* clipboard over IPC.
|
|
286
|
+
*/
|
|
287
|
+
clipboard?: ClipboardOption;
|
|
288
|
+
/**
|
|
289
|
+
* OSC 52 clipboard policy — lets terminal programs (Claude Code, tmux, vim)
|
|
290
|
+
* set/read the system clipboard via `ESC ] 52`. `"copy"` (default) allows
|
|
291
|
+
* writes only; `"read"` / `"both"` also answer read requests (an exfiltration
|
|
292
|
+
* risk — opt in deliberately); `false` disables it. Routed through the same
|
|
293
|
+
* clipboard provider as {@link clipboard}; a no-op when clipboard is `false`.
|
|
294
|
+
* Default `"copy"`.
|
|
295
|
+
*/
|
|
296
|
+
osc52?: Osc52Mode;
|
|
297
|
+
/**
|
|
298
|
+
* Copy/paste UX convention: `"contextmenu"` (menu + Ctrl+Shift+C),
|
|
299
|
+
* `"linux"` (highlight-to-copy + middle-click paste), or `"winmac"`
|
|
300
|
+
* (Ctrl/Cmd+C copies the selection, Ctrl/Cmd+V pastes). Omit for the historical
|
|
301
|
+
* default (Ctrl+Shift+C + Cmd+C-with-selection). Ctrl+Shift+C always copies.
|
|
302
|
+
*/
|
|
303
|
+
copyPaste?: CopyPasteMode;
|
|
304
|
+
/**
|
|
305
|
+
* Called once the xterm instance is opened + attached — the imperative twin of
|
|
306
|
+
* {@link TerminalHandle.ready}. Use it to load an addon without racing the
|
|
307
|
+
* container layout (where `handle.xterm` is still null).
|
|
166
308
|
*/
|
|
167
|
-
|
|
309
|
+
onReady?: (xterm: Terminal$1) => void;
|
|
168
310
|
/**
|
|
169
311
|
* Fired on every paste with the clipboard payload — `{ text, files, images }`.
|
|
170
312
|
* Plain text still pastes into the terminal natively; this is where a host
|
|
@@ -401,4 +543,24 @@ interface MenuSize {
|
|
|
401
543
|
*/
|
|
402
544
|
declare function clampMenuPosition(at: MenuPoint, menu: MenuSize, viewport: MenuSize, margin?: number): MenuPoint;
|
|
403
545
|
|
|
404
|
-
|
|
546
|
+
/** The bits of a pointer event the snapshot decision needs. */
|
|
547
|
+
interface SnapshotPointerEvent {
|
|
548
|
+
type: "mousedown" | "mouseup";
|
|
549
|
+
/** 0 = left, 1 = middle, 2 = right. */
|
|
550
|
+
button: number;
|
|
551
|
+
}
|
|
552
|
+
/**
|
|
553
|
+
* Compute the next selection snapshot after a pointer event on the terminal
|
|
554
|
+
* surface.
|
|
555
|
+
*
|
|
556
|
+
* - A fresh **left press** starts a new gesture — drop the snapshot (the live
|
|
557
|
+
* selection still reads the *old* text at capture time, so it must not win).
|
|
558
|
+
* - Otherwise a **non-empty live selection** always refreshes the snapshot
|
|
559
|
+
* (drag-select completes on left mouseup; a right press re-captures while
|
|
560
|
+
* the selection is still alive).
|
|
561
|
+
* - An **empty** live selection keeps the previous snapshot — that's exactly
|
|
562
|
+
* the TUI-cleared-it-under-us case the snapshot exists for.
|
|
563
|
+
*/
|
|
564
|
+
declare function nextSelectionSnapshot(prev: string, event: SnapshotPointerEvent, liveSelection: string): string;
|
|
565
|
+
|
|
566
|
+
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, type SnapshotPointerEvent, 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, nextSelectionSnapshot, osc52Response, parseOsc52, registerOsc52, resolveClipboard, resolveKeyAction, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };
|