@particle-academy/fancy-term 0.3.0 → 0.4.1

package/README.md

@@ -77,7 +77,10 @@ fancy-query's `useFancyStream`.
 | `activeShell` | `string` | controlled selected shell id (omit for uncontrolled) |
 | `onShellChange` | `(id, profile) => void` | fired when the user / `setShell` switches |
 | `showShellBar` | `boolean` | render the `<ShellSwitcher>` toolbar above the surface (default `false`) |
-| `clipboard` | `boolean` | enable the copy chord + paste interceptor (default `true`) |
+| `clipboard` | `boolean \| { writeText, readText }` | clipboard wiring: `true`/omit (navigator), `false` (off), or an **injectable provider** for sandboxed Electron hosts (default `true`) |
+| `osc52` | `"copy" \| "read" \| "both" \| false` | OSC 52 policy — let terminal programs (Claude Code, tmux, vim) set/read the clipboard (default `"copy"`, write-only) |
+| `copyPaste` | `"contextmenu" \| "linux" \| "winmac"` | copy/paste convention (see below); omit for the default chord |
+| `onReady` | `(xterm) => void` | called once xterm is opened + measured (twin of `handle.ready`) |
 | `onPaste` | `(payload) => void \| boolean` | every paste; receives `{ text, files, images }` — handle pasted **images** here. Return `false` to suppress the native text paste |
 | `contextMenu` | `false \| Item[] \| (ctx, defaults) => Item[]` | the right-click selection menu (see [Clipboard & context menu](#clipboard--context-menu)) |
 
@@ -93,7 +96,8 @@ const term = useRef<TerminalHandle>(null);
 // term.current.selectAll() / clearSelection()
 // term.current.setShell("pwsh") → switch the active shell (fires onShellChange)
 // term.current.getShell()       → the active shell id
-// term.current.xterm            → the raw xterm.js instance (escape hatch)
+// term.current.xterm            → the raw xterm.js instance (escape hatch; null before mount)
+// term.current.ready            → Promise<XTerm>, resolves once opened + measured
 ```
 
 ## Clipboard & context menu
@@ -138,6 +142,54 @@ Customize it with the `contextMenu` prop:
 Each item is `{ id, label?, icon?, disabled?, separator?, onSelect?(ctx) }`. Set
 `clipboard={false}` to turn off the copy chord + image-paste interception entirely.
 
+`ctx.selection` is **snapshotted before the right-click lands** and the built-in
+Copy writes that snapshot (through the active clipboard provider) — so it still
+copies over a mouse-reporting TUI (Claude Code, tmux, vim with mouse mode),
+where the app's redraw clears xterm's live selection before you can click Copy.
+
+### OSC 52 (terminal-program clipboard)
+
+Modern TUIs — Claude Code, tmux, vim/neovim — copy their own selection with an
+**OSC 52** escape (`ESC ] 52`). xterm.js drops these by default, so the app shows
+"copied" but nothing reaches the system clipboard. fancy-term handles OSC 52 out
+of the box (`osc52="copy"`), routing it through the active clipboard provider:
+
+```tsx
+<Terminal osc52="copy" … />   // default — programs may WRITE the clipboard
+<Terminal osc52="both" … />   // also answer read (?) requests — an exfiltration risk, opt in
+<Terminal osc52={false} … />  // disable OSC 52
+```
+
+### Copy/paste conventions
+
+`copyPaste` picks the UX to match your platform expectations:
+
+```tsx
+<Terminal copyPaste="winmac" … />  // Ctrl/Cmd+C copies selection, Ctrl/Cmd+V pastes
+<Terminal copyPaste="linux" … />   // highlight-to-copy + middle-click paste
+<Terminal copyPaste="contextmenu" … /> // menu only (+ Ctrl+Shift+C)
+```
+
+Omit it for the historical default (Ctrl+Shift+C + Cmd+C-with-selection).
+**Ctrl+Shift+C always copies** and plain **Ctrl+C stays SIGINT** (unless `winmac`
++ a selection) in every mode.
+
+### Injectable clipboard (Electron)
+
+In a sandboxed Electron renderer `navigator.clipboard` silently no-ops. Supply a
+**provider** so every copy/paste path — the chord, the menu, OSC 52,
+`handle.copySelection` / `handle.paste` — bridges to your main-process clipboard:
+
+```tsx
+<Terminal
+  clipboard={{
+    writeText: (text) => window.electron.clipboard.write(text), // → IPC
+    readText: () => window.electron.clipboard.read(),
+  }}
+  osc52="copy"
+/>
+```
+
 ## Switching shells
 
 fancy-term is a **frontend wrapper** — it never spawns a shell. It owns the

package/dist/index.cjs

@@ -113,18 +113,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;
@@ -140,12 +242,16 @@ function useTerminal(containerRef, options = {}) {
   const fitRef = react.useRef(null);
   const optsRef = react.useRef(options);
   optsRef.current = options;
+  const readyRef = react.useRef(makeDeferred());
   const handleRef = react.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(),
@@ -168,10 +274,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(),
@@ -213,17 +319,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;
@@ -234,13 +377,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]);
   react.useEffect(() => {
@@ -620,6 +769,12 @@ function resolveMenuItems(config, ctx, actions) {
   const items = config === void 0 || config === true ? defaults : Array.isArray(config) ? config : config(ctx, defaults);
   return items.length > 0 ? items : null;
 }
+
+// src/selection-snapshot.ts
+function nextSelectionSnapshot(prev, event, liveSelection) {
+  if (event.type === "mousedown" && event.button === 0) return "";
+  return liveSelection || prev;
+}
 var Terminal = react.forwardRef(function Terminal2({
   output,
   theme,
@@ -640,6 +795,9 @@ var Terminal = react.forwardRef(function Terminal2({
   onShellChange,
   showShellBar = false,
   clipboard,
+  osc52,
+  copyPaste,
+  onReady,
   onPaste,
   contextMenu,
   className,
@@ -676,12 +834,32 @@ var Terminal = react.forwardRef(function Terminal2({
     onData,
     onResize,
     clipboard,
+    osc52,
+    copyPaste,
+    onReady,
     onPaste
   });
   react.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
     }),
@@ -697,25 +875,42 @@ var Terminal = react.forwardRef(function Terminal2({
     written.current = output;
   }, [output, handle]);
   const [menu, setMenu] = react.useState(null);
+  const selectionSnapshot = react.useRef("");
+  const trackSelection = react.useCallback(
+    (e) => {
+      selectionSnapshot.current = nextSelectionSnapshot(
+        selectionSnapshot.current,
+        { type: e.type, button: e.button },
+        handle.getSelection()
+      );
+    },
+    [handle]
+  );
   const openMenu = react.useCallback(
     (e) => {
       if (contextMenu === false) return;
       e.preventDefault();
-      const selection = handle.getSelection();
+      const selection = handle.getSelection() || selectionSnapshot.current;
       const ctx = {
         hasSelection: selection.length > 0,
         selection,
         readOnly: !!readOnly
       };
       const items = resolveMenuItems(contextMenu, ctx, {
-        copy: () => void handle.copySelection(),
+        // Copy writes the SNAPSHOTTED selection through the active clipboard
+        // provider — never a click-time re-read, which copies "" over a TUI
+        // (falling back to the live selection only when the snapshot is empty).
+        copy: (c) => {
+          const text = c.selection || handle.getSelection();
+          if (text) void providerWrite(resolveClipboard(clipboard).provider, text);
+        },
         paste: () => void handle.paste(),
         selectAll: () => handle.selectAll(),
         clear: () => handle.clear()
       });
       if (items) setMenu({ at: { x: e.clientX, y: e.clientY }, items, ctx });
     },
-    [contextMenu, handle, readOnly]
+    [contextMenu, handle, readOnly, clipboard]
   );
   const menuNode = menu ? /* @__PURE__ */ jsxRuntime.jsx(TerminalContextMenu, { at: menu.at, items: menu.items, ctx: menu.ctx, onClose: () => setMenu(null) }) : null;
   const surface = /* @__PURE__ */ jsxRuntime.jsx(
@@ -723,6 +918,8 @@ var Terminal = react.forwardRef(function Terminal2({
     {
       ref: containerRef,
       "data-fancy-terminal": "",
+      onMouseDownCapture: trackSelection,
+      onMouseUpCapture: trackSelection,
       onContextMenu: openMenu,
       "data-readonly": readOnly ? "" : void 0,
       "data-fancy-terminal-shell": shellId ?? void 0,
@@ -816,14 +1013,33 @@ function useTerminalSession(options) {
   return { output, sendData, append, clear, shell, switchShell };
 }
 
+// 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;
+}
+
 exports.BUILTIN_SHELLS = BUILTIN_SHELLS;
 exports.ShellSwitcher = ShellSwitcher;
 exports.Terminal = Terminal;
 exports.TerminalContextMenu = TerminalContextMenu;
 exports.clampMenuPosition = clampMenuPosition;
+exports.copyPasteBehavior = copyPasteBehavior;
+exports.decodeBase64 = decodeBase64;
 exports.defaultMenuItems = defaultMenuItems;
+exports.encodeBase64 = encodeBase64;
 exports.fancyDarkTheme = fancyDarkTheme;
 exports.isImageFile = isImageFile;
+exports.navigatorClipboard = navigatorClipboard;
+exports.nextSelectionSnapshot = nextSelectionSnapshot;
+exports.osc52Response = osc52Response;
+exports.parseOsc52 = parseOsc52;
+exports.registerOsc52 = registerOsc52;
+exports.resolveClipboard = resolveClipboard;
+exports.resolveKeyAction = resolveKeyAction;
 exports.resolveMenuItems = resolveMenuItems;
 exports.resolveShell = resolveShell;
 exports.shouldCopyEvent = shouldCopyEvent;