@particle-academy/fancy-term 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @particle-academy/fancy-term
+
+**Human+ Terminal for React** — a controlled, themeable `<Terminal>` wrapping
+[xterm.js](https://xtermjs.org), with hooks and an MCP-bridgeable surface so
+embedded agents read the buffer, write input, and run commands **without
+DOM-scraping**.
+
+Like every Fancy UI component it serves two surfaces at once:
+
+- **Authoring** — terse and controlled (`output` + `onData`), JSON-friendly props
+  (rows/cols, theme tokens, initial buffer), a stable `data-fancy-terminal`
+  handle, and a ref exposing the full `TerminalHandle`.
+- **Inhabited** — that same handle is what an MCP bridge drives, so an agent reads
+  the visible buffer and writes input through stable affordances, never the DOM.
+
+Sexy by default via a Fancy dark theme drawn from the react-fancy Tailwind v4
+tokens.
+
+> **Status:** 0.1.0. `<Terminal>` + `useTerminal` / `useTerminalFit` /
+> `useTerminalSession` are in place. The `registerTerminalBridge` MCP bridge
+> (`terminal_read` / `terminal_write` / `terminal_run`) and the trust‑but‑verify
+> staged-command affordance ship next, in `@particle-academy/agent-integrations`.
+
+## Install
+
+```bash
+npm install @particle-academy/fancy-term @xterm/xterm @xterm/addon-fit
+```
+
+`react`, `xterm`, and the fit addon are **peer dependencies** — the wrapper itself
+is zero-runtime-dep (the same posture as `fancy-echarts` over ECharts). Import the
+xterm stylesheet once in your app:
+
+```ts
+import "@xterm/xterm/css/xterm.css";
+```
+
+## `<Terminal>`
+
+The parent needs a height — the terminal fits its container (like any xterm
+surface); a 0‑height parent collapses it.
+
+```tsx
+import { Terminal } from "@particle-academy/fancy-term";
+
+function Console() {
+  const [out, setOut] = useState("$ ");
+  return (
+    <div style={{ height: 360 }}>
+      <Terminal output={out} onData={(d) => backend.send(d)} />
+    </div>
+  );
+}
+```
+
+`output` is a **controlled buffer**: the component writes only the appended delta
+as it grows (replacing it wholesale resets + rewrites), so you can drive the
+terminal straight from React state — e.g. streaming command output via
+fancy-query's `useFancyStream`.
+
+| prop | type | notes |
+|---|---|---|
+| `output` | `string` | controlled buffer (delta-appended) |
+| `onData` | `(data: string) => void` | user keystrokes / paste → your PTY/command backend |
+| `onResize` | `(size) => void` | cols/rows changed |
+| `theme` | `TerminalTheme` | xterm color theme; omit for the Fancy dark theme |
+| `rows` / `cols` | `number` | fixed grid; omit + keep `fit` to size from the container |
+| `fit` | `boolean` | auto-fit via the fit addon + ResizeObserver (default `true`) |
+| `readOnly` | `boolean` | block stdin (display-only) |
+| `cursorBlink` / `cursorStyle` | | `"block" \| "underline" \| "bar"` |
+| `fontFamily` / `fontSize` / `scrollback` | | |
+| `initialOutput` | `string` | written once on mount (uncontrolled use) |
+
+The ref exposes a `TerminalHandle`:
+
+```tsx
+const term = useRef<TerminalHandle>(null);
+// term.current.write / writeln / clear / reset / fit / focus
+// term.current.getBuffer()      → the visible buffer as text (what an agent "sees")
+// term.current.getSelection()   → current selection
+// term.current.xterm            → the raw xterm.js instance (escape hatch)
+```
+
+## Hooks
+
+```tsx
+// Headless engine — the terminal without the component shell.
+const handle = useTerminal(containerRef, { theme, onData });
+
+// Auto-fit on resize, guarding the hidden-tab / late-mount 0×0 case.
+useTerminalFit(containerRef, () => handle.fit());
+
+// Bind to a streamed backend (PTY / SSH / command runner).
+const session = useTerminalSession({
+  transport: {
+    send: (d) => echo.private(`pty.${id}`).whisper("stdin", { d }),
+    subscribe: (onChunk) => {
+      echo.private(`pty.${id}`).listen(".stdout", (e) => onChunk(e.chunk));
+      return () => echo.leave(`pty.${id}`);
+    },
+  },
+});
+<Terminal output={session.output} onData={session.sendData} />
+```
+
+## Human+ contract
+
+`<Terminal>` is **controlled** (`value`/`onData`), carries a **stable handle**
+(`data-fancy-terminal` + the ref API), takes **JSON-friendly** props, and is
+**bridgeable** — `registerTerminalBridge` (in `agent-integrations`, shipping next)
+maps `terminal_read` / `terminal_write` / `terminal_run` onto the handle, wraps
+mutations so every write broadcasts `AgentActivity`, and supports a staged
+"agent proposes → human confirms" mode for destructive commands.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,237 @@
+'use strict';
+
+var react = require('react');
+var xterm = require('@xterm/xterm');
+var addonFit = require('@xterm/addon-fit');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/components/Terminal.tsx
+
+// src/theme.ts
+var fancyDarkTheme = {
+  background: "#09090b",
+  // zinc-950
+  foreground: "#e4e4e7",
+  // zinc-200
+  cursor: "#8b5cf6",
+  // violet-500
+  cursorAccent: "#09090b",
+  selectionBackground: "#3f3f46",
+  // zinc-700
+  black: "#18181b",
+  red: "#f43f5e",
+  green: "#10b981",
+  yellow: "#f59e0b",
+  blue: "#3b82f6",
+  magenta: "#8b5cf6",
+  cyan: "#22d3ee",
+  white: "#e4e4e7",
+  brightBlack: "#52525b",
+  brightRed: "#fb7185",
+  brightGreen: "#34d399",
+  brightYellow: "#fbbf24",
+  brightBlue: "#60a5fa",
+  brightMagenta: "#a78bfa",
+  brightCyan: "#67e8f9",
+  brightWhite: "#fafafa"
+};
+function useTerminalFit(ref, fit, enabled = true) {
+  const fitRef = react.useRef(fit);
+  fitRef.current = fit;
+  react.useEffect(() => {
+    if (!enabled) return;
+    const el = ref.current;
+    if (!el) return;
+    const run = () => {
+      if (el.clientWidth > 0 && el.clientHeight > 0) fitRef.current();
+    };
+    const observer = new ResizeObserver(run);
+    observer.observe(el);
+    run();
+    return () => observer.disconnect();
+  }, [ref, enabled]);
+}
+
+// src/hooks/use-terminal.ts
+var DEFAULT_FONT = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
+function readBuffer(term) {
+  if (!term) return "";
+  const buf = term.buffer.active;
+  const lines = [];
+  for (let i = 0; i < buf.length; i++) {
+    const line = buf.getLine(i);
+    if (line) lines.push(line.translateToString(true));
+  }
+  return lines.join("\n").replace(/\n+$/, "");
+}
+function useTerminal(containerRef, options = {}) {
+  const xtermRef = react.useRef(null);
+  const fitRef = react.useRef(null);
+  const optsRef = react.useRef(options);
+  optsRef.current = options;
+  const handleRef = react.useRef(null);
+  if (handleRef.current === null) {
+    handleRef.current = {
+      get xterm() {
+        return xtermRef.current;
+      },
+      write: (d) => xtermRef.current?.write(d),
+      writeln: (d) => xtermRef.current?.writeln(d),
+      clear: () => xtermRef.current?.clear(),
+      reset: () => xtermRef.current?.reset(),
+      fit: () => {
+        try {
+          fitRef.current?.fit();
+        } catch {
+        }
+      },
+      focus: () => xtermRef.current?.focus(),
+      getBuffer: () => readBuffer(xtermRef.current),
+      getSelection: () => xtermRef.current?.getSelection() ?? ""
+    };
+  }
+  const handle = handleRef.current;
+  react.useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const o = optsRef.current;
+    const term = new xterm.Terminal({
+      theme: o.theme ?? fancyDarkTheme,
+      rows: o.rows,
+      cols: o.cols,
+      disableStdin: o.readOnly ?? false,
+      cursorBlink: o.cursorBlink ?? true,
+      cursorStyle: o.cursorStyle ?? "block",
+      fontFamily: o.fontFamily ?? DEFAULT_FONT,
+      fontSize: o.fontSize ?? 13,
+      scrollback: o.scrollback ?? 1e3,
+      allowProposedApi: true
+    });
+    const fitAddon = new addonFit.FitAddon();
+    term.loadAddon(fitAddon);
+    term.open(el);
+    xtermRef.current = term;
+    fitRef.current = fitAddon;
+    const dataSub = term.onData((d) => optsRef.current.onData?.(d));
+    const resizeSub = term.onResize(
+      ({ cols, rows }) => optsRef.current.onResize?.({ cols, rows })
+    );
+    if (o.initialOutput) term.write(o.initialOutput);
+    if ((o.fit ?? true) && el.clientWidth > 0 && el.clientHeight > 0) {
+      try {
+        fitAddon.fit();
+      } catch {
+      }
+    }
+    return () => {
+      dataSub.dispose();
+      resizeSub.dispose();
+      term.dispose();
+      xtermRef.current = null;
+      fitRef.current = null;
+    };
+  }, [containerRef]);
+  react.useEffect(() => {
+    const t = xtermRef.current;
+    if (!t) return;
+    if (options.theme) t.options.theme = options.theme;
+    if (options.readOnly !== void 0) t.options.disableStdin = options.readOnly;
+    if (options.cursorBlink !== void 0) t.options.cursorBlink = options.cursorBlink;
+    if (options.cursorStyle) t.options.cursorStyle = options.cursorStyle;
+    if (options.fontSize) t.options.fontSize = options.fontSize;
+    if (options.fontFamily) t.options.fontFamily = options.fontFamily;
+  }, [options.theme, options.readOnly, options.cursorBlink, options.cursorStyle, options.fontSize, options.fontFamily]);
+  useTerminalFit(containerRef, () => handle.fit(), options.fit ?? true);
+  return handle;
+}
+
+// src/output-diff.ts
+function diffOutput(written, next) {
+  if (next === written) return null;
+  if (next.startsWith(written)) return { reset: false, write: next.slice(written.length) };
+  return { reset: true, write: next };
+}
+var Terminal = react.forwardRef(function Terminal2({
+  output,
+  theme,
+  rows,
+  cols,
+  fit = true,
+  readOnly,
+  cursorBlink,
+  cursorStyle,
+  fontFamily,
+  fontSize,
+  scrollback,
+  initialOutput,
+  onData,
+  onResize,
+  className,
+  style,
+  ...rest
+}, ref) {
+  const containerRef = react.useRef(null);
+  const handle = useTerminal(containerRef, {
+    theme,
+    rows,
+    cols,
+    fit,
+    readOnly,
+    cursorBlink,
+    cursorStyle,
+    fontFamily,
+    fontSize,
+    scrollback,
+    // `initialOutput` is for uncontrolled use; with a controlled `output` the
+    // diffing effect below owns the buffer, so don't double-write.
+    initialOutput: output === void 0 ? initialOutput : void 0,
+    onData,
+    onResize
+  });
+  react.useImperativeHandle(ref, () => handle, [handle]);
+  const written = react.useRef("");
+  react.useEffect(() => {
+    if (output === void 0) return;
+    const change = diffOutput(written.current, output);
+    if (!change) return;
+    if (change.reset) handle.reset();
+    handle.write(change.write);
+    written.current = output;
+  }, [output, handle]);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      ref: containerRef,
+      "data-fancy-terminal": "",
+      "data-readonly": readOnly ? "" : void 0,
+      className,
+      style: { width: "100%", height: "100%", ...style },
+      ...rest
+    }
+  );
+});
+function useTerminalSession(options) {
+  const [output, setOutput] = react.useState(options.initial ?? "");
+  const transportRef = react.useRef(options.transport);
+  transportRef.current = options.transport;
+  react.useEffect(() => {
+    const unsub = transportRef.current.subscribe((chunk) => setOutput((o) => o + chunk));
+    return () => {
+      if (typeof unsub === "function") unsub();
+    };
+  }, []);
+  const sendData = react.useCallback((data) => {
+    void transportRef.current.send(data);
+  }, []);
+  const append = react.useCallback((chunk) => setOutput((o) => o + chunk), []);
+  const clear = react.useCallback(() => setOutput(""), []);
+  return { output, sendData, append, clear };
+}
+
+exports.Terminal = Terminal;
+exports.fancyDarkTheme = fancyDarkTheme;
+exports.useTerminal = useTerminal;
+exports.useTerminalFit = useTerminalFit;
+exports.useTerminalSession = useTerminalSession;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theme.ts","../src/hooks/use-terminal-fit.ts","../src/hooks/use-terminal.ts","../src/output-diff.ts","../src/components/Terminal.tsx","../src/hooks/use-terminal-session.ts"],"names":["useRef","useEffect","XTerm","FitAddon","forwardRef","Terminal","useImperativeHandle","jsx","useState","useCallback"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { TerminalTheme } from \"./types\";\n\n/**\n * The default \"sexy\" Fancy dark terminal theme — a zinc surface, violet cursor,\n * and a balanced ANSI palette drawn from the react-fancy Tailwind v4 tokens.\n * Pass a `theme` prop / option to override.\n */\nexport const fancyDarkTheme: TerminalTheme = {\n  background: \"#09090b\", // zinc-950\n  foreground: \"#e4e4e7\", // zinc-200\n  cursor: \"#8b5cf6\", // violet-500\n  cursorAccent: \"#09090b\",\n  selectionBackground: \"#3f3f46\", // zinc-700\n  black: \"#18181b\",\n  red: \"#f43f5e\",\n  green: \"#10b981\",\n  yellow: \"#f59e0b\",\n  blue: \"#3b82f6\",\n  magenta: \"#8b5cf6\",\n  cyan: \"#22d3ee\",\n  white: \"#e4e4e7\",\n  brightBlack: \"#52525b\",\n  brightRed: \"#fb7185\",\n  brightGreen: \"#34d399\",\n  brightYellow: \"#fbbf24\",\n  brightBlue: \"#60a5fa\",\n  brightMagenta: \"#a78bfa\",\n  brightCyan: \"#67e8f9\",\n  brightWhite: \"#fafafa\",\n};\n","import { useEffect, useRef, type RefObject } from \"react\";\n\n/**\n * Run `fit` whenever the container resizes — and once it first has a real,\n * non-zero box. Guards the hidden-tab / late-mount 0×0 case: fitting a collapsed\n * container yields garbage rows/cols (or throws), so we simply skip until there\n * is layout to measure.\n */\nexport function useTerminalFit(\n  ref: RefObject<HTMLElement | null>,\n  fit: () => void,\n  enabled = true,\n): void {\n  const fitRef = useRef(fit);\n  fitRef.current = fit;\n\n  useEffect(() => {\n    if (!enabled) return;\n    const el = ref.current;\n    if (!el) return;\n\n    const run = () => {\n      if (el.clientWidth > 0 && el.clientHeight > 0) fitRef.current();\n    };\n\n    const observer = new ResizeObserver(run);\n    observer.observe(el);\n    run(); // initial — fires once the box has layout\n\n    return () => observer.disconnect();\n  }, [ref, enabled]);\n}\n","import { useEffect, useRef, type RefObject } from \"react\";\nimport { Terminal as XTerm } from \"@xterm/xterm\";\nimport { FitAddon } from \"@xterm/addon-fit\";\nimport { fancyDarkTheme } from \"../theme\";\nimport { useTerminalFit } from \"./use-terminal-fit\";\nimport type { TerminalHandle, TerminalOptions } from \"../types\";\n\nconst DEFAULT_FONT =\n  'ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace';\n\n/** Read the whole xterm buffer as plain text — what an agent \"sees\". */\nfunction readBuffer(term: XTerm | null): string {\n  if (!term) return \"\";\n  const buf = term.buffer.active;\n  const lines: string[] = [];\n  for (let i = 0; i < buf.length; i++) {\n    const line = buf.getLine(i);\n    if (line) lines.push(line.translateToString(true));\n  }\n  return lines.join(\"\\n\").replace(/\\n+$/, \"\");\n}\n\n/**\n * Create + own an xterm.js instance for a container, returning a stable\n * {@link TerminalHandle}. The headless engine layer behind `<Terminal>` — use it\n * directly when you want the terminal without the component shell (custom chrome,\n * an agent bridge host, tests). Options are read live, so changing them re-applies\n * without tearing down the terminal.\n */\nexport function useTerminal(\n  containerRef: RefObject<HTMLElement | null>,\n  options: TerminalOptions = {},\n): TerminalHandle {\n  const xtermRef = useRef<XTerm | null>(null);\n  const fitRef = useRef<FitAddon | null>(null);\n  const optsRef = useRef(options);\n  optsRef.current = options;\n\n  // Stable handle — its methods always operate on the live xterm via the ref.\n  const handleRef = useRef<TerminalHandle | null>(null);\n  if (handleRef.current === null) {\n    handleRef.current = {\n      get xterm() {\n        return xtermRef.current;\n      },\n      write: (d) => xtermRef.current?.write(d),\n      writeln: (d) => xtermRef.current?.writeln(d),\n      clear: () => xtermRef.current?.clear(),\n      reset: () => xtermRef.current?.reset(),\n      fit: () => {\n        try {\n          fitRef.current?.fit();\n        } catch {\n          /* container not measurable yet — ignore */\n        }\n      },\n      focus: () => xtermRef.current?.focus(),\n      getBuffer: () => readBuffer(xtermRef.current),\n      getSelection: () => xtermRef.current?.getSelection() ?? \"\",\n    };\n  }\n  const handle = handleRef.current;\n\n  // Create the engine once for the container.\n  useEffect(() => {\n    const el = containerRef.current;\n    if (!el) return;\n    const o = optsRef.current;\n\n    const term = new XTerm({\n      theme: o.theme ?? fancyDarkTheme,\n      rows: o.rows,\n      cols: o.cols,\n      disableStdin: o.readOnly ?? false,\n      cursorBlink: o.cursorBlink ?? true,\n      cursorStyle: o.cursorStyle ?? \"block\",\n      fontFamily: o.fontFamily ?? DEFAULT_FONT,\n      fontSize: o.fontSize ?? 13,\n      scrollback: o.scrollback ?? 1000,\n      allowProposedApi: true,\n    });\n    const fitAddon = new FitAddon();\n    term.loadAddon(fitAddon);\n    term.open(el);\n    xtermRef.current = term;\n    fitRef.current = fitAddon;\n\n    const dataSub = term.onData((d) => optsRef.current.onData?.(d));\n    const resizeSub = term.onResize(({ cols, rows }) =>\n      optsRef.current.onResize?.({ cols, rows }),\n    );\n\n    if (o.initialOutput) term.write(o.initialOutput);\n    if ((o.fit ?? true) && el.clientWidth > 0 && el.clientHeight > 0) {\n      try {\n        fitAddon.fit();\n      } catch {\n        /* ignore */\n      }\n    }\n\n    return () => {\n      dataSub.dispose();\n      resizeSub.dispose();\n      term.dispose();\n      xtermRef.current = null;\n      fitRef.current = null;\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [containerRef]);\n\n  // Re-apply reactive options without tearing the terminal down.\n  useEffect(() => {\n    const t = xtermRef.current;\n    if (!t) return;\n    if (options.theme) t.options.theme = options.theme;\n    if (options.readOnly !== undefined) t.options.disableStdin = options.readOnly;\n    if (options.cursorBlink !== undefined) t.options.cursorBlink = options.cursorBlink;\n    if (options.cursorStyle) t.options.cursorStyle = options.cursorStyle;\n    if (options.fontSize) t.options.fontSize = options.fontSize;\n    if (options.fontFamily) t.options.fontFamily = options.fontFamily;\n  }, [options.theme, options.readOnly, options.cursorBlink, options.cursorStyle, options.fontSize, options.fontFamily]);\n\n  // Auto-fit on container resize (0×0-guarded).\n  useTerminalFit(containerRef, () => handle.fit(), options.fit ?? true);\n\n  return handle;\n}\n","/**\n * Decide what to push to the terminal when the controlled `output` changes.\n * Terminals are append-only streams, so the common case (output grew) writes\n * only the delta; a value that no longer extends what we've written means a\n * wholesale replace, so reset + rewrite. Returns null when nothing changed.\n */\nexport function diffOutput(\n  written: string,\n  next: string,\n): { reset: boolean; write: string } | null {\n  if (next === written) return null;\n  if (next.startsWith(written)) return { reset: false, write: next.slice(written.length) };\n  return { reset: true, write: next };\n}\n","import { forwardRef, useEffect, useImperativeHandle, useRef } from \"react\";\nimport { useTerminal } from \"../hooks/use-terminal\";\nimport { diffOutput } from \"../output-diff\";\nimport type { TerminalHandle, TerminalProps } from \"../types\";\n\n/**\n * Human+ `<Terminal>` — a controlled, themeable xterm.js terminal.\n *\n * - **Authoring surface:** terse, controlled (`output` + `onData`), JSON-friendly\n *   props (rows/cols, theme tokens, initial buffer), a stable `data-fancy-terminal`\n *   handle, and a ref exposing {@link TerminalHandle} (write/clear/fit/getBuffer/…).\n * - **Inhabited surface:** the same handle is what an MCP bridge drives, so an\n *   embedded agent reads the buffer + writes input without DOM-scraping.\n *\n * The parent must have a height — the terminal fits its container (like any xterm\n * surface); a 0-height parent collapses it.\n *\n * ```tsx\n * const [out, setOut] = useState(\"\");\n * <div style={{ height: 360 }}>\n *   <Terminal output={out} onData={(d) => backend.send(d)} />\n * </div>\n * ```\n */\nexport const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(\n  {\n    output,\n    theme,\n    rows,\n    cols,\n    fit = true,\n    readOnly,\n    cursorBlink,\n    cursorStyle,\n    fontFamily,\n    fontSize,\n    scrollback,\n    initialOutput,\n    onData,\n    onResize,\n    className,\n    style,\n    ...rest\n  },\n  ref,\n) {\n  const containerRef = useRef<HTMLDivElement>(null);\n\n  const handle = useTerminal(containerRef, {\n    theme,\n    rows,\n    cols,\n    fit,\n    readOnly,\n    cursorBlink,\n    cursorStyle,\n    fontFamily,\n    fontSize,\n    scrollback,\n    // `initialOutput` is for uncontrolled use; with a controlled `output` the\n    // diffing effect below owns the buffer, so don't double-write.\n    initialOutput: output === undefined ? initialOutput : undefined,\n    onData,\n    onResize,\n  });\n\n  useImperativeHandle(ref, () => handle, [handle]);\n\n  // Controlled output: write only the appended delta; reset + rewrite if the\n  // value diverges from what we've already written (a wholesale replace).\n  const written = useRef(\"\");\n  useEffect(() => {\n    if (output === undefined) return;\n    const change = diffOutput(written.current, output);\n    if (!change) return;\n    if (change.reset) handle.reset();\n    handle.write(change.write);\n    written.current = output;\n  }, [output, handle]);\n\n  return (\n    <div\n      ref={containerRef}\n      data-fancy-terminal=\"\"\n      data-readonly={readOnly ? \"\" : undefined}\n      className={className}\n      style={{ width: \"100%\", height: \"100%\", ...style }}\n      {...rest}\n    />\n  );\n});\n","import { useCallback, useEffect, useRef, useState } from \"react\";\n\n/**\n * A streamed terminal backend — a PTY, an SSH session, or a command runner.\n * `subscribe` pushes output chunks (wire it to an Echo channel or a fancy-query\n * `useFancyStream` feed); `send` forwards the user's keystrokes upstream.\n */\nexport interface TerminalSessionTransport {\n  /** Forward user input / keystrokes to the backend. */\n  send: (data: string) => void | Promise<void>;\n  /** Subscribe to backend output chunks; return an unsubscribe function. */\n  subscribe: (onChunk: (chunk: string) => void) => (() => void) | void;\n}\n\nexport interface UseTerminalSessionOptions {\n  transport: TerminalSessionTransport;\n  /** Replayed history written before live output starts. */\n  initial?: string;\n}\n\nexport interface TerminalSessionApi {\n  /** Accumulated output — feed to `<Terminal output={output} />`. */\n  output: string;\n  /** Forward keystrokes upstream — wire to `<Terminal onData={sendData} />`. */\n  sendData: (data: string) => void;\n  /** Append a chunk locally (e.g. a client-side echo or banner). */\n  append: (chunk: string) => void;\n  /** Clear the local buffer. */\n  clear: () => void;\n}\n\n/**\n * Bind a `<Terminal>` to a streamed backend: accumulates incoming output into a\n * controlled buffer and forwards keystrokes upstream — the glue between the\n * display surface and a PTY/command channel.\n *\n * ```tsx\n * const session = useTerminalSession({\n *   transport: {\n *     send: (d) => echo.private(`pty.${id}`).whisper(\"stdin\", { d }),\n *     subscribe: (onChunk) => {\n *       const ch = echo.private(`pty.${id}`).listen(\".stdout\", (e) => onChunk(e.chunk));\n *       return () => echo.leave(`pty.${id}`);\n *     },\n *   },\n * });\n * <Terminal output={session.output} onData={session.sendData} />\n * ```\n */\nexport function useTerminalSession(options: UseTerminalSessionOptions): TerminalSessionApi {\n  const [output, setOutput] = useState(options.initial ?? \"\");\n\n  const transportRef = useRef(options.transport);\n  transportRef.current = options.transport;\n\n  useEffect(() => {\n    const unsub = transportRef.current.subscribe((chunk) => setOutput((o) => o + chunk));\n    return () => {\n      if (typeof unsub === \"function\") unsub();\n    };\n    // subscribe once; the transport is read live via the ref.\n  }, []);\n\n  const sendData = useCallback((data: string) => {\n    void transportRef.current.send(data);\n  }, []);\n\n  const append = useCallback((chunk: string) => setOutput((o) => o + chunk), []);\n  const clear = useCallback(() => setOutput(\"\"), []);\n\n  return { output, sendData, append, clear };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,165 @@
+import * as react from 'react';
+import { HTMLAttributes, RefObject } from 'react';
+import { ITheme, Terminal as Terminal$1 } from '@xterm/xterm';
+
+/** xterm.js color theme (re-exported for ergonomic typing). */
+type TerminalTheme = ITheme;
+type CursorStyle = "block" | "underline" | "bar";
+/**
+ * Imperative handle exposed via the `<Terminal>` ref and returned by
+ * {@link useTerminal}. The same surface an MCP bridge drives so an embedded
+ * agent reads the buffer + writes input without DOM-scraping.
+ */
+interface TerminalHandle {
+    /** The underlying xterm.js instance — escape hatch for addons / advanced use. Null before mount. */
+    readonly xterm: Terminal$1 | null;
+    /** Write raw data (ANSI escape sequences honored) to the terminal. */
+    write: (data: string) => void;
+    /** Write data followed by CRLF. */
+    writeln: (data: string) => void;
+    /** Clear the viewport (keeps scrollback). */
+    clear: () => void;
+    /** Full reset — clears scrollback + terminal state. */
+    reset: () => void;
+    /** Re-fit to the container (no-op when the box is 0-size or fit is off). */
+    fit: () => void;
+    /** Focus the terminal input. */
+    focus: () => void;
+    /** The full buffer as plain text — what an agent "sees". */
+    getBuffer: () => string;
+    /** The current text selection, or "" when nothing is selected. */
+    getSelection: () => string;
+}
+/** Engine options shared by `<Terminal>` and {@link useTerminal}. */
+interface TerminalOptions {
+    /** xterm color theme. Omit for the built-in Fancy dark theme. */
+    theme?: TerminalTheme;
+    /** Fixed grid size. Omit + leave `fit` on to size from the container. */
+    rows?: number;
+    cols?: number;
+    /** Auto-fit to the container via the fit addon + ResizeObserver. Default true. */
+    fit?: boolean;
+    /** Block stdin (display-only terminal). Default false. */
+    readOnly?: boolean;
+    /** Blink the cursor. Default true. */
+    cursorBlink?: boolean;
+    /** Cursor shape. Default "block". */
+    cursorStyle?: CursorStyle;
+    /** Monospace font stack. */
+    fontFamily?: string;
+    /** Font size in px. Default 13. */
+    fontSize?: number;
+    /** Scrollback lines. Default 1000. */
+    scrollback?: number;
+    /** Data written once on mount, before any controlled `output`. */
+    initialOutput?: string;
+    /** User keystrokes / paste data (xterm `onData`). Wire to your PTY/command backend. */
+    onData?: (data: string) => void;
+    /** Notified on terminal resize. */
+    onResize?: (size: {
+        cols: number;
+        rows: number;
+    }) => void;
+}
+interface TerminalProps extends TerminalOptions, Omit<HTMLAttributes<HTMLDivElement>, "onInput" | "onResize" | "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
+     * React state — e.g. streaming command output via fancy-query's
+     * `useFancyStream`. Replacing it with a non-extending string resets + rewrites.
+     */
+    output?: string;
+}
+
+/**
+ * Human+ `<Terminal>` — a controlled, themeable xterm.js terminal.
+ *
+ * - **Authoring surface:** terse, controlled (`output` + `onData`), JSON-friendly
+ *   props (rows/cols, theme tokens, initial buffer), a stable `data-fancy-terminal`
+ *   handle, and a ref exposing {@link TerminalHandle} (write/clear/fit/getBuffer/…).
+ * - **Inhabited surface:** the same handle is what an MCP bridge drives, so an
+ *   embedded agent reads the buffer + writes input without DOM-scraping.
+ *
+ * The parent must have a height — the terminal fits its container (like any xterm
+ * surface); a 0-height parent collapses it.
+ *
+ * ```tsx
+ * const [out, setOut] = useState("");
+ * <div style={{ height: 360 }}>
+ *   <Terminal output={out} onData={(d) => backend.send(d)} />
+ * </div>
+ * ```
+ */
+declare const Terminal: react.ForwardRefExoticComponent<TerminalProps & react.RefAttributes<TerminalHandle>>;
+
+/**
+ * Create + own an xterm.js instance for a container, returning a stable
+ * {@link TerminalHandle}. The headless engine layer behind `<Terminal>` — use it
+ * directly when you want the terminal without the component shell (custom chrome,
+ * an agent bridge host, tests). Options are read live, so changing them re-applies
+ * without tearing down the terminal.
+ */
+declare function useTerminal(containerRef: RefObject<HTMLElement | null>, options?: TerminalOptions): TerminalHandle;
+
+/**
+ * Run `fit` whenever the container resizes — and once it first has a real,
+ * non-zero box. Guards the hidden-tab / late-mount 0×0 case: fitting a collapsed
+ * container yields garbage rows/cols (or throws), so we simply skip until there
+ * is layout to measure.
+ */
+declare function useTerminalFit(ref: RefObject<HTMLElement | null>, fit: () => void, enabled?: boolean): void;
+
+/**
+ * A streamed terminal backend — a PTY, an SSH session, or a command runner.
+ * `subscribe` pushes output chunks (wire it to an Echo channel or a fancy-query
+ * `useFancyStream` feed); `send` forwards the user's keystrokes upstream.
+ */
+interface TerminalSessionTransport {
+    /** Forward user input / keystrokes to the backend. */
+    send: (data: string) => void | Promise<void>;
+    /** Subscribe to backend output chunks; return an unsubscribe function. */
+    subscribe: (onChunk: (chunk: string) => void) => (() => void) | void;
+}
+interface UseTerminalSessionOptions {
+    transport: TerminalSessionTransport;
+    /** Replayed history written before live output starts. */
+    initial?: string;
+}
+interface TerminalSessionApi {
+    /** Accumulated output — feed to `<Terminal output={output} />`. */
+    output: string;
+    /** Forward keystrokes upstream — wire to `<Terminal onData={sendData} />`. */
+    sendData: (data: string) => void;
+    /** Append a chunk locally (e.g. a client-side echo or banner). */
+    append: (chunk: string) => void;
+    /** Clear the local buffer. */
+    clear: () => void;
+}
+/**
+ * Bind a `<Terminal>` to a streamed backend: accumulates incoming output into a
+ * controlled buffer and forwards keystrokes upstream — the glue between the
+ * display surface and a PTY/command channel.
+ *
+ * ```tsx
+ * const session = useTerminalSession({
+ *   transport: {
+ *     send: (d) => echo.private(`pty.${id}`).whisper("stdin", { d }),
+ *     subscribe: (onChunk) => {
+ *       const ch = echo.private(`pty.${id}`).listen(".stdout", (e) => onChunk(e.chunk));
+ *       return () => echo.leave(`pty.${id}`);
+ *     },
+ *   },
+ * });
+ * <Terminal output={session.output} onData={session.sendData} />
+ * ```
+ */
+declare function useTerminalSession(options: UseTerminalSessionOptions): TerminalSessionApi;
+
+/**
+ * The default "sexy" Fancy dark terminal theme — a zinc surface, violet cursor,
+ * and a balanced ANSI palette drawn from the react-fancy Tailwind v4 tokens.
+ * Pass a `theme` prop / option to override.
+ */
+declare const fancyDarkTheme: TerminalTheme;
+
+export { type CursorStyle, Terminal, type TerminalHandle, type TerminalOptions, type TerminalProps, type TerminalSessionApi, type TerminalSessionTransport, type TerminalTheme, type UseTerminalSessionOptions, fancyDarkTheme, useTerminal, useTerminalFit, useTerminalSession };

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+import * as react from 'react';
+import { HTMLAttributes, RefObject } from 'react';
+import { ITheme, Terminal as Terminal$1 } from '@xterm/xterm';
+
+/** xterm.js color theme (re-exported for ergonomic typing). */
+type TerminalTheme = ITheme;
+type CursorStyle = "block" | "underline" | "bar";
+/**
+ * Imperative handle exposed via the `<Terminal>` ref and returned by
+ * {@link useTerminal}. The same surface an MCP bridge drives so an embedded
+ * agent reads the buffer + writes input without DOM-scraping.
+ */
+interface TerminalHandle {
+    /** The underlying xterm.js instance — escape hatch for addons / advanced use. Null before mount. */
+    readonly xterm: Terminal$1 | null;
+    /** Write raw data (ANSI escape sequences honored) to the terminal. */
+    write: (data: string) => void;
+    /** Write data followed by CRLF. */
+    writeln: (data: string) => void;
+    /** Clear the viewport (keeps scrollback). */
+    clear: () => void;
+    /** Full reset — clears scrollback + terminal state. */
+    reset: () => void;
+    /** Re-fit to the container (no-op when the box is 0-size or fit is off). */
+    fit: () => void;
+    /** Focus the terminal input. */
+    focus: () => void;
+    /** The full buffer as plain text — what an agent "sees". */
+    getBuffer: () => string;
+    /** The current text selection, or "" when nothing is selected. */
+    getSelection: () => string;
+}
+/** Engine options shared by `<Terminal>` and {@link useTerminal}. */
+interface TerminalOptions {
+    /** xterm color theme. Omit for the built-in Fancy dark theme. */
+    theme?: TerminalTheme;
+    /** Fixed grid size. Omit + leave `fit` on to size from the container. */
+    rows?: number;
+    cols?: number;
+    /** Auto-fit to the container via the fit addon + ResizeObserver. Default true. */
+    fit?: boolean;
+    /** Block stdin (display-only terminal). Default false. */
+    readOnly?: boolean;
+    /** Blink the cursor. Default true. */
+    cursorBlink?: boolean;
+    /** Cursor shape. Default "block". */
+    cursorStyle?: CursorStyle;
+    /** Monospace font stack. */
+    fontFamily?: string;
+    /** Font size in px. Default 13. */
+    fontSize?: number;
+    /** Scrollback lines. Default 1000. */
+    scrollback?: number;
+    /** Data written once on mount, before any controlled `output`. */
+    initialOutput?: string;
+    /** User keystrokes / paste data (xterm `onData`). Wire to your PTY/command backend. */
+    onData?: (data: string) => void;
+    /** Notified on terminal resize. */
+    onResize?: (size: {
+        cols: number;
+        rows: number;
+    }) => void;
+}
+interface TerminalProps extends TerminalOptions, Omit<HTMLAttributes<HTMLDivElement>, "onInput" | "onResize" | "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
+     * React state — e.g. streaming command output via fancy-query's
+     * `useFancyStream`. Replacing it with a non-extending string resets + rewrites.
+     */
+    output?: string;
+}
+
+/**
+ * Human+ `<Terminal>` — a controlled, themeable xterm.js terminal.
+ *
+ * - **Authoring surface:** terse, controlled (`output` + `onData`), JSON-friendly
+ *   props (rows/cols, theme tokens, initial buffer), a stable `data-fancy-terminal`
+ *   handle, and a ref exposing {@link TerminalHandle} (write/clear/fit/getBuffer/…).
+ * - **Inhabited surface:** the same handle is what an MCP bridge drives, so an
+ *   embedded agent reads the buffer + writes input without DOM-scraping.
+ *
+ * The parent must have a height — the terminal fits its container (like any xterm
+ * surface); a 0-height parent collapses it.
+ *
+ * ```tsx
+ * const [out, setOut] = useState("");
+ * <div style={{ height: 360 }}>
+ *   <Terminal output={out} onData={(d) => backend.send(d)} />
+ * </div>
+ * ```
+ */
+declare const Terminal: react.ForwardRefExoticComponent<TerminalProps & react.RefAttributes<TerminalHandle>>;
+
+/**
+ * Create + own an xterm.js instance for a container, returning a stable
+ * {@link TerminalHandle}. The headless engine layer behind `<Terminal>` — use it
+ * directly when you want the terminal without the component shell (custom chrome,
+ * an agent bridge host, tests). Options are read live, so changing them re-applies
+ * without tearing down the terminal.
+ */
+declare function useTerminal(containerRef: RefObject<HTMLElement | null>, options?: TerminalOptions): TerminalHandle;
+
+/**
+ * Run `fit` whenever the container resizes — and once it first has a real,
+ * non-zero box. Guards the hidden-tab / late-mount 0×0 case: fitting a collapsed
+ * container yields garbage rows/cols (or throws), so we simply skip until there
+ * is layout to measure.
+ */
+declare function useTerminalFit(ref: RefObject<HTMLElement | null>, fit: () => void, enabled?: boolean): void;
+
+/**
+ * A streamed terminal backend — a PTY, an SSH session, or a command runner.
+ * `subscribe` pushes output chunks (wire it to an Echo channel or a fancy-query
+ * `useFancyStream` feed); `send` forwards the user's keystrokes upstream.
+ */
+interface TerminalSessionTransport {
+    /** Forward user input / keystrokes to the backend. */
+    send: (data: string) => void | Promise<void>;
+    /** Subscribe to backend output chunks; return an unsubscribe function. */
+    subscribe: (onChunk: (chunk: string) => void) => (() => void) | void;
+}
+interface UseTerminalSessionOptions {
+    transport: TerminalSessionTransport;
+    /** Replayed history written before live output starts. */
+    initial?: string;
+}
+interface TerminalSessionApi {
+    /** Accumulated output — feed to `<Terminal output={output} />`. */
+    output: string;
+    /** Forward keystrokes upstream — wire to `<Terminal onData={sendData} />`. */
+    sendData: (data: string) => void;
+    /** Append a chunk locally (e.g. a client-side echo or banner). */
+    append: (chunk: string) => void;
+    /** Clear the local buffer. */
+    clear: () => void;
+}
+/**
+ * Bind a `<Terminal>` to a streamed backend: accumulates incoming output into a
+ * controlled buffer and forwards keystrokes upstream — the glue between the
+ * display surface and a PTY/command channel.
+ *
+ * ```tsx
+ * const session = useTerminalSession({
+ *   transport: {
+ *     send: (d) => echo.private(`pty.${id}`).whisper("stdin", { d }),
+ *     subscribe: (onChunk) => {
+ *       const ch = echo.private(`pty.${id}`).listen(".stdout", (e) => onChunk(e.chunk));
+ *       return () => echo.leave(`pty.${id}`);
+ *     },
+ *   },
+ * });
+ * <Terminal output={session.output} onData={session.sendData} />
+ * ```
+ */
+declare function useTerminalSession(options: UseTerminalSessionOptions): TerminalSessionApi;
+
+/**
+ * The default "sexy" Fancy dark terminal theme — a zinc surface, violet cursor,
+ * and a balanced ANSI palette drawn from the react-fancy Tailwind v4 tokens.
+ * Pass a `theme` prop / option to override.
+ */
+declare const fancyDarkTheme: TerminalTheme;
+
+export { type CursorStyle, Terminal, type TerminalHandle, type TerminalOptions, type TerminalProps, type TerminalSessionApi, type TerminalSessionTransport, type TerminalTheme, type UseTerminalSessionOptions, fancyDarkTheme, useTerminal, useTerminalFit, useTerminalSession };

package/dist/index.js

@@ -0,0 +1,231 @@
+import { forwardRef, useRef, useImperativeHandle, useEffect, useState, useCallback } from 'react';
+import { Terminal as Terminal$1 } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import { jsx } from 'react/jsx-runtime';
+
+// src/components/Terminal.tsx
+
+// src/theme.ts
+var fancyDarkTheme = {
+  background: "#09090b",
+  // zinc-950
+  foreground: "#e4e4e7",
+  // zinc-200
+  cursor: "#8b5cf6",
+  // violet-500
+  cursorAccent: "#09090b",
+  selectionBackground: "#3f3f46",
+  // zinc-700
+  black: "#18181b",
+  red: "#f43f5e",
+  green: "#10b981",
+  yellow: "#f59e0b",
+  blue: "#3b82f6",
+  magenta: "#8b5cf6",
+  cyan: "#22d3ee",
+  white: "#e4e4e7",
+  brightBlack: "#52525b",
+  brightRed: "#fb7185",
+  brightGreen: "#34d399",
+  brightYellow: "#fbbf24",
+  brightBlue: "#60a5fa",
+  brightMagenta: "#a78bfa",
+  brightCyan: "#67e8f9",
+  brightWhite: "#fafafa"
+};
+function useTerminalFit(ref, fit, enabled = true) {
+  const fitRef = useRef(fit);
+  fitRef.current = fit;
+  useEffect(() => {
+    if (!enabled) return;
+    const el = ref.current;
+    if (!el) return;
+    const run = () => {
+      if (el.clientWidth > 0 && el.clientHeight > 0) fitRef.current();
+    };
+    const observer = new ResizeObserver(run);
+    observer.observe(el);
+    run();
+    return () => observer.disconnect();
+  }, [ref, enabled]);
+}
+
+// src/hooks/use-terminal.ts
+var DEFAULT_FONT = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
+function readBuffer(term) {
+  if (!term) return "";
+  const buf = term.buffer.active;
+  const lines = [];
+  for (let i = 0; i < buf.length; i++) {
+    const line = buf.getLine(i);
+    if (line) lines.push(line.translateToString(true));
+  }
+  return lines.join("\n").replace(/\n+$/, "");
+}
+function useTerminal(containerRef, options = {}) {
+  const xtermRef = useRef(null);
+  const fitRef = useRef(null);
+  const optsRef = useRef(options);
+  optsRef.current = options;
+  const handleRef = useRef(null);
+  if (handleRef.current === null) {
+    handleRef.current = {
+      get xterm() {
+        return xtermRef.current;
+      },
+      write: (d) => xtermRef.current?.write(d),
+      writeln: (d) => xtermRef.current?.writeln(d),
+      clear: () => xtermRef.current?.clear(),
+      reset: () => xtermRef.current?.reset(),
+      fit: () => {
+        try {
+          fitRef.current?.fit();
+        } catch {
+        }
+      },
+      focus: () => xtermRef.current?.focus(),
+      getBuffer: () => readBuffer(xtermRef.current),
+      getSelection: () => xtermRef.current?.getSelection() ?? ""
+    };
+  }
+  const handle = handleRef.current;
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const o = optsRef.current;
+    const term = new Terminal$1({
+      theme: o.theme ?? fancyDarkTheme,
+      rows: o.rows,
+      cols: o.cols,
+      disableStdin: o.readOnly ?? false,
+      cursorBlink: o.cursorBlink ?? true,
+      cursorStyle: o.cursorStyle ?? "block",
+      fontFamily: o.fontFamily ?? DEFAULT_FONT,
+      fontSize: o.fontSize ?? 13,
+      scrollback: o.scrollback ?? 1e3,
+      allowProposedApi: true
+    });
+    const fitAddon = new FitAddon();
+    term.loadAddon(fitAddon);
+    term.open(el);
+    xtermRef.current = term;
+    fitRef.current = fitAddon;
+    const dataSub = term.onData((d) => optsRef.current.onData?.(d));
+    const resizeSub = term.onResize(
+      ({ cols, rows }) => optsRef.current.onResize?.({ cols, rows })
+    );
+    if (o.initialOutput) term.write(o.initialOutput);
+    if ((o.fit ?? true) && el.clientWidth > 0 && el.clientHeight > 0) {
+      try {
+        fitAddon.fit();
+      } catch {
+      }
+    }
+    return () => {
+      dataSub.dispose();
+      resizeSub.dispose();
+      term.dispose();
+      xtermRef.current = null;
+      fitRef.current = null;
+    };
+  }, [containerRef]);
+  useEffect(() => {
+    const t = xtermRef.current;
+    if (!t) return;
+    if (options.theme) t.options.theme = options.theme;
+    if (options.readOnly !== void 0) t.options.disableStdin = options.readOnly;
+    if (options.cursorBlink !== void 0) t.options.cursorBlink = options.cursorBlink;
+    if (options.cursorStyle) t.options.cursorStyle = options.cursorStyle;
+    if (options.fontSize) t.options.fontSize = options.fontSize;
+    if (options.fontFamily) t.options.fontFamily = options.fontFamily;
+  }, [options.theme, options.readOnly, options.cursorBlink, options.cursorStyle, options.fontSize, options.fontFamily]);
+  useTerminalFit(containerRef, () => handle.fit(), options.fit ?? true);
+  return handle;
+}
+
+// src/output-diff.ts
+function diffOutput(written, next) {
+  if (next === written) return null;
+  if (next.startsWith(written)) return { reset: false, write: next.slice(written.length) };
+  return { reset: true, write: next };
+}
+var Terminal = forwardRef(function Terminal2({
+  output,
+  theme,
+  rows,
+  cols,
+  fit = true,
+  readOnly,
+  cursorBlink,
+  cursorStyle,
+  fontFamily,
+  fontSize,
+  scrollback,
+  initialOutput,
+  onData,
+  onResize,
+  className,
+  style,
+  ...rest
+}, ref) {
+  const containerRef = useRef(null);
+  const handle = useTerminal(containerRef, {
+    theme,
+    rows,
+    cols,
+    fit,
+    readOnly,
+    cursorBlink,
+    cursorStyle,
+    fontFamily,
+    fontSize,
+    scrollback,
+    // `initialOutput` is for uncontrolled use; with a controlled `output` the
+    // diffing effect below owns the buffer, so don't double-write.
+    initialOutput: output === void 0 ? initialOutput : void 0,
+    onData,
+    onResize
+  });
+  useImperativeHandle(ref, () => handle, [handle]);
+  const written = useRef("");
+  useEffect(() => {
+    if (output === void 0) return;
+    const change = diffOutput(written.current, output);
+    if (!change) return;
+    if (change.reset) handle.reset();
+    handle.write(change.write);
+    written.current = output;
+  }, [output, handle]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: containerRef,
+      "data-fancy-terminal": "",
+      "data-readonly": readOnly ? "" : void 0,
+      className,
+      style: { width: "100%", height: "100%", ...style },
+      ...rest
+    }
+  );
+});
+function useTerminalSession(options) {
+  const [output, setOutput] = useState(options.initial ?? "");
+  const transportRef = useRef(options.transport);
+  transportRef.current = options.transport;
+  useEffect(() => {
+    const unsub = transportRef.current.subscribe((chunk) => setOutput((o) => o + chunk));
+    return () => {
+      if (typeof unsub === "function") unsub();
+    };
+  }, []);
+  const sendData = useCallback((data) => {
+    void transportRef.current.send(data);
+  }, []);
+  const append = useCallback((chunk) => setOutput((o) => o + chunk), []);
+  const clear = useCallback(() => setOutput(""), []);
+  return { output, sendData, append, clear };
+}
+
+export { Terminal, fancyDarkTheme, useTerminal, useTerminalFit, useTerminalSession };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theme.ts","../src/hooks/use-terminal-fit.ts","../src/hooks/use-terminal.ts","../src/output-diff.ts","../src/components/Terminal.tsx","../src/hooks/use-terminal-session.ts"],"names":["useRef","useEffect","XTerm","Terminal"],"mappings":"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","file":"index.js","sourcesContent":["import type { TerminalTheme } from \"./types\";\n\n/**\n * The default \"sexy\" Fancy dark terminal theme — a zinc surface, violet cursor,\n * and a balanced ANSI palette drawn from the react-fancy Tailwind v4 tokens.\n * Pass a `theme` prop / option to override.\n */\nexport const fancyDarkTheme: TerminalTheme = {\n  background: \"#09090b\", // zinc-950\n  foreground: \"#e4e4e7\", // zinc-200\n  cursor: \"#8b5cf6\", // violet-500\n  cursorAccent: \"#09090b\",\n  selectionBackground: \"#3f3f46\", // zinc-700\n  black: \"#18181b\",\n  red: \"#f43f5e\",\n  green: \"#10b981\",\n  yellow: \"#f59e0b\",\n  blue: \"#3b82f6\",\n  magenta: \"#8b5cf6\",\n  cyan: \"#22d3ee\",\n  white: \"#e4e4e7\",\n  brightBlack: \"#52525b\",\n  brightRed: \"#fb7185\",\n  brightGreen: \"#34d399\",\n  brightYellow: \"#fbbf24\",\n  brightBlue: \"#60a5fa\",\n  brightMagenta: \"#a78bfa\",\n  brightCyan: \"#67e8f9\",\n  brightWhite: \"#fafafa\",\n};\n","import { useEffect, useRef, type RefObject } from \"react\";\n\n/**\n * Run `fit` whenever the container resizes — and once it first has a real,\n * non-zero box. Guards the hidden-tab / late-mount 0×0 case: fitting a collapsed\n * container yields garbage rows/cols (or throws), so we simply skip until there\n * is layout to measure.\n */\nexport function useTerminalFit(\n  ref: RefObject<HTMLElement | null>,\n  fit: () => void,\n  enabled = true,\n): void {\n  const fitRef = useRef(fit);\n  fitRef.current = fit;\n\n  useEffect(() => {\n    if (!enabled) return;\n    const el = ref.current;\n    if (!el) return;\n\n    const run = () => {\n      if (el.clientWidth > 0 && el.clientHeight > 0) fitRef.current();\n    };\n\n    const observer = new ResizeObserver(run);\n    observer.observe(el);\n    run(); // initial — fires once the box has layout\n\n    return () => observer.disconnect();\n  }, [ref, enabled]);\n}\n","import { useEffect, useRef, type RefObject } from \"react\";\nimport { Terminal as XTerm } from \"@xterm/xterm\";\nimport { FitAddon } from \"@xterm/addon-fit\";\nimport { fancyDarkTheme } from \"../theme\";\nimport { useTerminalFit } from \"./use-terminal-fit\";\nimport type { TerminalHandle, TerminalOptions } from \"../types\";\n\nconst DEFAULT_FONT =\n  'ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace';\n\n/** Read the whole xterm buffer as plain text — what an agent \"sees\". */\nfunction readBuffer(term: XTerm | null): string {\n  if (!term) return \"\";\n  const buf = term.buffer.active;\n  const lines: string[] = [];\n  for (let i = 0; i < buf.length; i++) {\n    const line = buf.getLine(i);\n    if (line) lines.push(line.translateToString(true));\n  }\n  return lines.join(\"\\n\").replace(/\\n+$/, \"\");\n}\n\n/**\n * Create + own an xterm.js instance for a container, returning a stable\n * {@link TerminalHandle}. The headless engine layer behind `<Terminal>` — use it\n * directly when you want the terminal without the component shell (custom chrome,\n * an agent bridge host, tests). Options are read live, so changing them re-applies\n * without tearing down the terminal.\n */\nexport function useTerminal(\n  containerRef: RefObject<HTMLElement | null>,\n  options: TerminalOptions = {},\n): TerminalHandle {\n  const xtermRef = useRef<XTerm | null>(null);\n  const fitRef = useRef<FitAddon | null>(null);\n  const optsRef = useRef(options);\n  optsRef.current = options;\n\n  // Stable handle — its methods always operate on the live xterm via the ref.\n  const handleRef = useRef<TerminalHandle | null>(null);\n  if (handleRef.current === null) {\n    handleRef.current = {\n      get xterm() {\n        return xtermRef.current;\n      },\n      write: (d) => xtermRef.current?.write(d),\n      writeln: (d) => xtermRef.current?.writeln(d),\n      clear: () => xtermRef.current?.clear(),\n      reset: () => xtermRef.current?.reset(),\n      fit: () => {\n        try {\n          fitRef.current?.fit();\n        } catch {\n          /* container not measurable yet — ignore */\n        }\n      },\n      focus: () => xtermRef.current?.focus(),\n      getBuffer: () => readBuffer(xtermRef.current),\n      getSelection: () => xtermRef.current?.getSelection() ?? \"\",\n    };\n  }\n  const handle = handleRef.current;\n\n  // Create the engine once for the container.\n  useEffect(() => {\n    const el = containerRef.current;\n    if (!el) return;\n    const o = optsRef.current;\n\n    const term = new XTerm({\n      theme: o.theme ?? fancyDarkTheme,\n      rows: o.rows,\n      cols: o.cols,\n      disableStdin: o.readOnly ?? false,\n      cursorBlink: o.cursorBlink ?? true,\n      cursorStyle: o.cursorStyle ?? \"block\",\n      fontFamily: o.fontFamily ?? DEFAULT_FONT,\n      fontSize: o.fontSize ?? 13,\n      scrollback: o.scrollback ?? 1000,\n      allowProposedApi: true,\n    });\n    const fitAddon = new FitAddon();\n    term.loadAddon(fitAddon);\n    term.open(el);\n    xtermRef.current = term;\n    fitRef.current = fitAddon;\n\n    const dataSub = term.onData((d) => optsRef.current.onData?.(d));\n    const resizeSub = term.onResize(({ cols, rows }) =>\n      optsRef.current.onResize?.({ cols, rows }),\n    );\n\n    if (o.initialOutput) term.write(o.initialOutput);\n    if ((o.fit ?? true) && el.clientWidth > 0 && el.clientHeight > 0) {\n      try {\n        fitAddon.fit();\n      } catch {\n        /* ignore */\n      }\n    }\n\n    return () => {\n      dataSub.dispose();\n      resizeSub.dispose();\n      term.dispose();\n      xtermRef.current = null;\n      fitRef.current = null;\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [containerRef]);\n\n  // Re-apply reactive options without tearing the terminal down.\n  useEffect(() => {\n    const t = xtermRef.current;\n    if (!t) return;\n    if (options.theme) t.options.theme = options.theme;\n    if (options.readOnly !== undefined) t.options.disableStdin = options.readOnly;\n    if (options.cursorBlink !== undefined) t.options.cursorBlink = options.cursorBlink;\n    if (options.cursorStyle) t.options.cursorStyle = options.cursorStyle;\n    if (options.fontSize) t.options.fontSize = options.fontSize;\n    if (options.fontFamily) t.options.fontFamily = options.fontFamily;\n  }, [options.theme, options.readOnly, options.cursorBlink, options.cursorStyle, options.fontSize, options.fontFamily]);\n\n  // Auto-fit on container resize (0×0-guarded).\n  useTerminalFit(containerRef, () => handle.fit(), options.fit ?? true);\n\n  return handle;\n}\n","/**\n * Decide what to push to the terminal when the controlled `output` changes.\n * Terminals are append-only streams, so the common case (output grew) writes\n * only the delta; a value that no longer extends what we've written means a\n * wholesale replace, so reset + rewrite. Returns null when nothing changed.\n */\nexport function diffOutput(\n  written: string,\n  next: string,\n): { reset: boolean; write: string } | null {\n  if (next === written) return null;\n  if (next.startsWith(written)) return { reset: false, write: next.slice(written.length) };\n  return { reset: true, write: next };\n}\n","import { forwardRef, useEffect, useImperativeHandle, useRef } from \"react\";\nimport { useTerminal } from \"../hooks/use-terminal\";\nimport { diffOutput } from \"../output-diff\";\nimport type { TerminalHandle, TerminalProps } from \"../types\";\n\n/**\n * Human+ `<Terminal>` — a controlled, themeable xterm.js terminal.\n *\n * - **Authoring surface:** terse, controlled (`output` + `onData`), JSON-friendly\n *   props (rows/cols, theme tokens, initial buffer), a stable `data-fancy-terminal`\n *   handle, and a ref exposing {@link TerminalHandle} (write/clear/fit/getBuffer/…).\n * - **Inhabited surface:** the same handle is what an MCP bridge drives, so an\n *   embedded agent reads the buffer + writes input without DOM-scraping.\n *\n * The parent must have a height — the terminal fits its container (like any xterm\n * surface); a 0-height parent collapses it.\n *\n * ```tsx\n * const [out, setOut] = useState(\"\");\n * <div style={{ height: 360 }}>\n *   <Terminal output={out} onData={(d) => backend.send(d)} />\n * </div>\n * ```\n */\nexport const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(\n  {\n    output,\n    theme,\n    rows,\n    cols,\n    fit = true,\n    readOnly,\n    cursorBlink,\n    cursorStyle,\n    fontFamily,\n    fontSize,\n    scrollback,\n    initialOutput,\n    onData,\n    onResize,\n    className,\n    style,\n    ...rest\n  },\n  ref,\n) {\n  const containerRef = useRef<HTMLDivElement>(null);\n\n  const handle = useTerminal(containerRef, {\n    theme,\n    rows,\n    cols,\n    fit,\n    readOnly,\n    cursorBlink,\n    cursorStyle,\n    fontFamily,\n    fontSize,\n    scrollback,\n    // `initialOutput` is for uncontrolled use; with a controlled `output` the\n    // diffing effect below owns the buffer, so don't double-write.\n    initialOutput: output === undefined ? initialOutput : undefined,\n    onData,\n    onResize,\n  });\n\n  useImperativeHandle(ref, () => handle, [handle]);\n\n  // Controlled output: write only the appended delta; reset + rewrite if the\n  // value diverges from what we've already written (a wholesale replace).\n  const written = useRef(\"\");\n  useEffect(() => {\n    if (output === undefined) return;\n    const change = diffOutput(written.current, output);\n    if (!change) return;\n    if (change.reset) handle.reset();\n    handle.write(change.write);\n    written.current = output;\n  }, [output, handle]);\n\n  return (\n    <div\n      ref={containerRef}\n      data-fancy-terminal=\"\"\n      data-readonly={readOnly ? \"\" : undefined}\n      className={className}\n      style={{ width: \"100%\", height: \"100%\", ...style }}\n      {...rest}\n    />\n  );\n});\n","import { useCallback, useEffect, useRef, useState } from \"react\";\n\n/**\n * A streamed terminal backend — a PTY, an SSH session, or a command runner.\n * `subscribe` pushes output chunks (wire it to an Echo channel or a fancy-query\n * `useFancyStream` feed); `send` forwards the user's keystrokes upstream.\n */\nexport interface TerminalSessionTransport {\n  /** Forward user input / keystrokes to the backend. */\n  send: (data: string) => void | Promise<void>;\n  /** Subscribe to backend output chunks; return an unsubscribe function. */\n  subscribe: (onChunk: (chunk: string) => void) => (() => void) | void;\n}\n\nexport interface UseTerminalSessionOptions {\n  transport: TerminalSessionTransport;\n  /** Replayed history written before live output starts. */\n  initial?: string;\n}\n\nexport interface TerminalSessionApi {\n  /** Accumulated output — feed to `<Terminal output={output} />`. */\n  output: string;\n  /** Forward keystrokes upstream — wire to `<Terminal onData={sendData} />`. */\n  sendData: (data: string) => void;\n  /** Append a chunk locally (e.g. a client-side echo or banner). */\n  append: (chunk: string) => void;\n  /** Clear the local buffer. */\n  clear: () => void;\n}\n\n/**\n * Bind a `<Terminal>` to a streamed backend: accumulates incoming output into a\n * controlled buffer and forwards keystrokes upstream — the glue between the\n * display surface and a PTY/command channel.\n *\n * ```tsx\n * const session = useTerminalSession({\n *   transport: {\n *     send: (d) => echo.private(`pty.${id}`).whisper(\"stdin\", { d }),\n *     subscribe: (onChunk) => {\n *       const ch = echo.private(`pty.${id}`).listen(\".stdout\", (e) => onChunk(e.chunk));\n *       return () => echo.leave(`pty.${id}`);\n *     },\n *   },\n * });\n * <Terminal output={session.output} onData={session.sendData} />\n * ```\n */\nexport function useTerminalSession(options: UseTerminalSessionOptions): TerminalSessionApi {\n  const [output, setOutput] = useState(options.initial ?? \"\");\n\n  const transportRef = useRef(options.transport);\n  transportRef.current = options.transport;\n\n  useEffect(() => {\n    const unsub = transportRef.current.subscribe((chunk) => setOutput((o) => o + chunk));\n    return () => {\n      if (typeof unsub === \"function\") unsub();\n    };\n    // subscribe once; the transport is read live via the ref.\n  }, []);\n\n  const sendData = useCallback((data: string) => {\n    void transportRef.current.send(data);\n  }, []);\n\n  const append = useCallback((chunk: string) => setOutput((o) => o + chunk), []);\n  const clear = useCallback(() => setOutput(\"\"), []);\n\n  return { output, sendData, append, clear };\n}\n"]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@particle-academy/fancy-term",
+  "version": "0.1.0",
+  "description": "Human+ Terminal for React — a controlled, themeable <Terminal> wrapping xterm.js, with hooks and an MCP-bridgeable surface so embedded agents read the buffer, write input, and run commands without DOM-scraping.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Particle-Academy/fancy-term.git"
+  },
+  "homepage": "https://github.com/Particle-Academy/fancy-term#readme",
+  "bugs": "https://github.com/Particle-Academy/fancy-term/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "tsup"
+  },
+  "keywords": [
+    "react",
+    "terminal",
+    "xterm",
+    "agents",
+    "mcp",
+    "human-plus-ux",
+    "fancy"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@xterm/xterm": ">=5.0.0",
+    "@xterm/addon-fit": ">=0.10.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@xterm/xterm": "^5.5.0",
+    "@xterm/addon-fit": "^0.10.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}