@particle-academy/fancy-term 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -2,6 +2,69 @@ import * as react from 'react';
 import { HTMLAttributes, CSSProperties, RefObject } from 'react';
 import { ITheme, Terminal as Terminal$1 } 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;
+
+/** 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;
 type CursorStyle = "block" | "underline" | "bar";
@@ -49,6 +112,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 +159,22 @@ interface TerminalOptions {
         cols: number;
         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?: boolean;
+    /**
+     * 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 +197,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 +261,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 +365,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 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 };

package/dist/index.js

@@ -1,7 +1,7 @@
-import { forwardRef, useRef, useState, useCallback, useImperativeHandle, useEffect, useId } from 'react';
+import { forwardRef, useRef, useState, useCallback, useImperativeHandle, useEffect, useLayoutEffect, useId } from 'react';
 import { Terminal as Terminal$1 } from '@xterm/xterm';
 import { FitAddon } from '@xterm/addon-fit';
-import { jsx, jsxs } from 'react/jsx-runtime';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/components/Terminal.tsx
 
@@ -50,6 +50,77 @@ function useTerminalFit(ref, fit, enabled = true) {
   }, [ref, enabled]);
 }
 
+// src/clipboard.ts
+function isImageFile(f) {
+  return typeof f.type === "string" && f.type.startsWith("image/");
+}
+function readDataTransfer(dt) {
+  const files = [];
+  let text = "";
+  if (dt) {
+    try {
+      text = dt.getData("text/plain") ?? "";
+    } catch {
+    }
+    const items = dt.items;
+    if (items) {
+      for (let i = 0; i < items.length; i++) {
+        const it = items[i];
+        if (it && it.kind === "file") {
+          const f = it.getAsFile();
+          if (f) files.push(f);
+        }
+      }
+    }
+    if (files.length === 0 && dt.files) {
+      for (let i = 0; i < dt.files.length; i++) files.push(dt.files[i]);
+    }
+  }
+  return { text, files, images: files.filter(isImageFile) };
+}
+async function writeClipboardText(text) {
+  try {
+    const nav = typeof navigator !== "undefined" ? navigator : void 0;
+    if (nav?.clipboard?.writeText) {
+      await nav.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+  }
+  try {
+    if (typeof document === "undefined") return false;
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.left = "-9999px";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    const ok = document.execCommand("copy");
+    document.body.removeChild(ta);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+async function readClipboardText() {
+  try {
+    const nav = typeof navigator !== "undefined" ? navigator : void 0;
+    if (nav?.clipboard?.readText) return await nav.clipboard.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/hooks/use-terminal.ts
 var DEFAULT_FONT = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
 function readBuffer(term) {
@@ -92,6 +163,17 @@ function useTerminal(containerRef, options = {}) {
       focus: () => xtermRef.current?.focus(),
       getBuffer: () => readBuffer(xtermRef.current),
       getSelection: () => xtermRef.current?.getSelection() ?? "",
+      copySelection: async () => {
+        const sel = xtermRef.current?.getSelection() ?? "";
+        if (!sel) return false;
+        return writeClipboardText(sel);
+      },
+      paste: async (text) => {
+        const data = text ?? await readClipboardText();
+        if (data) xtermRef.current?.paste(data);
+      },
+      selectAll: () => xtermRef.current?.selectAll(),
+      clearSelection: () => xtermRef.current?.clearSelection(),
       // Shell selection is owned by the <Terminal> component layer (it needs the
       // `shells` list + onShellChange). The headless engine is shell-agnostic, so
       // these are no-ops here and get overridden when <Terminal> composes them.
@@ -107,8 +189,11 @@ function useTerminal(containerRef, options = {}) {
     const o = optsRef.current;
     const term = new Terminal$1({
       theme: o.theme ?? fancyDarkTheme,
-      rows: o.rows,
-      cols: o.cols,
+      // Only pass rows/cols when explicitly set. xterm validates these and
+      // console-errors "rows/cols must be numeric" if handed `undefined`, rather
+      // than falling back to its 80×24 default. Omit the keys instead.
+      ...typeof o.rows === "number" ? { rows: o.rows } : {},
+      ...typeof o.cols === "number" ? { cols: o.cols } : {},
       disableStdin: o.readOnly ?? false,
       cursorBlink: o.cursorBlink ?? true,
       cursorStyle: o.cursorStyle ?? "block",
@@ -126,9 +211,29 @@ function useTerminal(containerRef, options = {}) {
     const resizeSub = term.onResize(
       ({ cols, rows }) => optsRef.current.onResize?.({ cols, rows })
     );
+    term.attachCustomKeyEventHandler((e) => {
+      if (optsRef.current.clipboard === false) return true;
+      if (shouldCopyEvent(e, term.hasSelection())) {
+        void writeClipboardText(term.getSelection());
+        return false;
+      }
+      return true;
+    });
+    const onPasteEvent = (e) => {
+      const o2 = optsRef.current;
+      if (o2.clipboard === false) return;
+      if (o2.readOnly) {
+        e.preventDefault();
+        return;
+      }
+      const payload = readDataTransfer(e.clipboardData);
+      if (o2.onPaste?.(payload) === false) e.preventDefault();
+    };
+    el.addEventListener("paste", onPasteEvent, true);
     if (o.initialOutput) term.write(o.initialOutput);
     if (o.fit ?? true) handle.fit();
     return () => {
+      el.removeEventListener("paste", onPasteEvent, true);
       dataSub.dispose();
       resizeSub.dispose();
       term.dispose();
@@ -359,6 +464,122 @@ function ShellSwitcher({
   );
 }
 
+// src/menu-position.ts
+function clampMenuPosition(at, menu, viewport, margin = 8) {
+  const maxX = Math.max(margin, viewport.width - menu.width - margin);
+  const maxY = Math.max(margin, viewport.height - menu.height - margin);
+  return {
+    x: Math.min(Math.max(margin, at.x), maxX),
+    y: Math.min(Math.max(margin, at.y), maxY)
+  };
+}
+function TerminalContextMenu({
+  at,
+  items,
+  ctx,
+  onClose
+}) {
+  const ref = useRef(null);
+  const [pos, setPos] = useState(at);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || typeof window === "undefined") return;
+    const r = el.getBoundingClientRect();
+    setPos(
+      clampMenuPosition(
+        at,
+        { width: r.width, height: r.height },
+        { width: window.innerWidth, height: window.innerHeight }
+      )
+    );
+  }, [at]);
+  useEffect(() => {
+    const onDown = (e) => {
+      if (ref.current && !ref.current.contains(e.target)) onClose();
+    };
+    const onKey = (e) => {
+      if (e.key === "Escape") onClose();
+    };
+    document.addEventListener("mousedown", onDown, true);
+    document.addEventListener("keydown", onKey, true);
+    return () => {
+      document.removeEventListener("mousedown", onDown, true);
+      document.removeEventListener("keydown", onKey, true);
+    };
+  }, [onClose]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref,
+      "data-fancy-terminal-menu": "",
+      role: "menu",
+      style: {
+        position: "fixed",
+        left: pos.x,
+        top: pos.y,
+        zIndex: 2147483e3,
+        minWidth: 176,
+        padding: 4,
+        background: "#18181b",
+        border: "1px solid #3f3f46",
+        borderRadius: 8,
+        boxShadow: "0 10px 32px -8px rgba(0,0,0,.6)",
+        color: "#e4e4e7",
+        font: '13px/1.4 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+        userSelect: "none"
+      },
+      children: items.map(
+        (it) => it.separator ? /* @__PURE__ */ jsx(
+          "div",
+          {
+            role: "separator",
+            style: { height: 1, margin: "4px 6px", background: "#3f3f46" }
+          },
+          it.id
+        ) : /* @__PURE__ */ jsxs(
+          "button",
+          {
+            type: "button",
+            role: "menuitem",
+            "data-menu-item": it.id,
+            disabled: it.disabled,
+            onClick: () => {
+              if (it.disabled) return;
+              it.onSelect?.(ctx);
+              onClose();
+            },
+            onMouseEnter: (e) => {
+              if (!it.disabled) e.currentTarget.style.background = "#27272a";
+            },
+            onMouseLeave: (e) => {
+              e.currentTarget.style.background = "transparent";
+            },
+            style: {
+              display: "flex",
+              alignItems: "center",
+              gap: 9,
+              width: "100%",
+              textAlign: "left",
+              padding: "6px 9px",
+              border: "none",
+              borderRadius: 5,
+              background: "transparent",
+              color: it.disabled ? "#52525b" : "inherit",
+              cursor: it.disabled ? "default" : "pointer",
+              font: "inherit"
+            },
+            children: [
+              /* @__PURE__ */ jsx("span", { style: { width: 16, textAlign: "center", opacity: 0.8 }, children: it.icon ?? "" }),
+              /* @__PURE__ */ jsx("span", { style: { flex: 1 }, children: it.label })
+            ]
+          },
+          it.id
+        )
+      )
+    }
+  );
+}
+
 // src/output-diff.ts
 function diffOutput(written, next) {
   if (next === written) return null;
@@ -375,6 +596,28 @@ function decideShellSelect(shells, current, id) {
 function decideShellSwitch(current, next) {
   return { changed: current !== next };
 }
+
+// src/context-menu.ts
+function defaultMenuItems(ctx, actions) {
+  const items = [
+    { id: "copy", label: "Copy", icon: "\u29C9", disabled: !ctx.hasSelection, onSelect: actions.copy }
+  ];
+  if (!ctx.readOnly) {
+    items.push({ id: "paste", label: "Paste", icon: "\u2398", onSelect: actions.paste });
+  }
+  items.push({ id: "select-all", label: "Select all", onSelect: actions.selectAll });
+  if (!ctx.readOnly) {
+    items.push({ id: "sep-default", separator: true });
+    items.push({ id: "clear", label: "Clear", onSelect: actions.clear });
+  }
+  return items;
+}
+function resolveMenuItems(config, ctx, actions) {
+  if (config === false) return null;
+  const defaults = defaultMenuItems(ctx, actions);
+  const items = config === void 0 || config === true ? defaults : Array.isArray(config) ? config : config(ctx, defaults);
+  return items.length > 0 ? items : null;
+}
 var Terminal = forwardRef(function Terminal2({
   output,
   theme,
@@ -394,6 +637,9 @@ var Terminal = forwardRef(function Terminal2({
   activeShell,
   onShellChange,
   showShellBar = false,
+  clipboard,
+  onPaste,
+  contextMenu,
   className,
   style,
   ...rest
@@ -426,7 +672,9 @@ var Terminal = forwardRef(function Terminal2({
     // diffing effect below owns the buffer, so don't double-write.
     initialOutput: output === void 0 ? initialOutput : void 0,
     onData,
-    onResize
+    onResize,
+    clipboard,
+    onPaste
   });
   useImperativeHandle(
     ref,
@@ -446,18 +694,46 @@ var Terminal = forwardRef(function Terminal2({
     handle.write(change.write);
     written.current = output;
   }, [output, handle]);
+  const [menu, setMenu] = useState(null);
+  const openMenu = useCallback(
+    (e) => {
+      if (contextMenu === false) return;
+      e.preventDefault();
+      const selection = handle.getSelection();
+      const ctx = {
+        hasSelection: selection.length > 0,
+        selection,
+        readOnly: !!readOnly
+      };
+      const items = resolveMenuItems(contextMenu, ctx, {
+        copy: () => void handle.copySelection(),
+        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]
+  );
+  const menuNode = menu ? /* @__PURE__ */ jsx(TerminalContextMenu, { at: menu.at, items: menu.items, ctx: menu.ctx, onClose: () => setMenu(null) }) : null;
   const surface = /* @__PURE__ */ jsx(
     "div",
     {
       ref: containerRef,
       "data-fancy-terminal": "",
+      onContextMenu: openMenu,
       "data-readonly": readOnly ? "" : void 0,
       "data-fancy-terminal-shell": shellId ?? void 0,
       style: showShellBar && shells ? { width: "100%", flex: 1, minHeight: 0 } : { width: "100%", height: "100%", ...style },
       ...showShellBar && shells ? {} : rest
     }
   );
-  if (!showShellBar || !shells) return surface;
+  if (!showShellBar || !shells) {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      surface,
+      menuNode
+    ] });
+  }
   return /* @__PURE__ */ jsxs(
     "div",
     {
@@ -488,7 +764,8 @@ var Terminal = forwardRef(function Terminal2({
             )
           }
         ),
-        surface
+        surface,
+        menuNode
       ]
     }
   );
@@ -537,6 +814,6 @@ function useTerminalSession(options) {
   return { output, sendData, append, clear, shell, switchShell };
 }
 
-export { BUILTIN_SHELLS, ShellSwitcher, Terminal, fancyDarkTheme, resolveShell, useTerminal, useTerminalFit, useTerminalSession };
+export { BUILTIN_SHELLS, ShellSwitcher, Terminal, TerminalContextMenu, clampMenuPosition, defaultMenuItems, fancyDarkTheme, isImageFile, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map