@particle-academy/fancy-term 0.1.0 → 0.2.0

package/README.md

@@ -16,10 +16,13 @@ Like every Fancy UI component it serves two surfaces at once:
 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`.
+> **Status:** 0.2.0. `<Terminal>` + `useTerminal` / `useTerminalFit` /
+> `useTerminalSession` are in place, plus **shell / profile switching** (the
+> `<ShellSwitcher>` component, controlled `shells` / `activeShell` props, and the
+> session hook's `switchShell`). The `registerTerminalBridge` MCP bridge
+> (`terminal_read` / `terminal_write` / `terminal_run` / `terminal_set_shell`) and
+> the trust‑but‑verify staged-command affordance ship in
+> `@particle-academy/agent-integrations`.
 
 ## Install
 
@@ -70,6 +73,10 @@ fancy-query's `useFancyStream`.
 | `cursorBlink` / `cursorStyle` | | `"block" \| "underline" \| "bar"` |
 | `fontFamily` / `fontSize` / `scrollback` | | |
 | `initialOutput` | `string` | written once on mount (uncontrolled use) |
+| `shells` | `ShellProfile[]` | the shells / profiles the host offers (see [Switching shells](#switching-shells)) |
+| `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`) |
 
 The ref exposes a `TerminalHandle`:
 
@@ -78,9 +85,105 @@ 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.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)
 ```
 
+## Switching shells
+
+fancy-term is a **frontend wrapper** — it never spawns a shell. It owns the
+*selected-shell state, the UI, and the change events*; the **host reacts** by
+reconnecting its PTY / command backend to the chosen profile. That separation
+keeps the wrapper portable across any backend.
+
+A `ShellProfile` is fully JSON-friendly (an agent can emit one):
+
+```ts
+interface ShellProfile {
+  id: string;        // stable key, e.g. "powershell"
+  label: string;     // display, e.g. "PowerShell"
+  icon?: string;     // optional short glyph / emoji / single char
+  command?: string;  // host hint, e.g. "pwsh" / "cmd.exe"
+  args?: string[];   // host hint
+  cwd?: string;      // host hint
+}
+```
+
+`command` / `args` / `cwd` are **host hints only** — fancy-term passes the choice
+along; your backend decides what to launch. Spread the built-in presets and
+filter to what your host actually offers:
+
+```ts
+import { BUILTIN_SHELLS } from "@particle-academy/fancy-term";
+// cmd · powershell · pwsh · git-bash · bash · zsh
+const shells = BUILTIN_SHELLS.filter((s) => ["pwsh", "git-bash"].includes(s.id));
+```
+
+### On the `<Terminal>` (controlled)
+
+```tsx
+const [shell, setShell] = useState("pwsh");
+
+<div style={{ height: 360 }}>
+  <Terminal
+    output={out}
+    onData={(d) => backend.send(d)}
+    shells={shells}
+    activeShell={shell}
+    onShellChange={(id) => {
+      setShell(id);
+      backend.reconnect(id); // host reconnects its PTY to the chosen shell
+    }}
+    showShellBar           // opt-in: render the built-in switcher toolbar
+  />
+</div>
+```
+
+The root carries `data-fancy-terminal-shell="<id>"` so an agent (or an MCP bridge)
+can read the active shell without DOM-guessing. Omit `activeShell` for an
+uncontrolled terminal that tracks the selection internally.
+
+### Standalone `<ShellSwitcher>`
+
+Place the picker anywhere — it's a self-contained, accessible (Arrow / Enter /
+Esc), Fancy-dark-themed dropdown with zero third-party deps:
+
+```tsx
+import { ShellSwitcher } from "@particle-academy/fancy-term";
+
+<ShellSwitcher
+  shells={shells}
+  value={shell}
+  onChange={(id, profile) => backend.reconnect(profile)}
+/>
+```
+
+Stable handles: the root carries `data-fancy-shell-switcher`, each option carries
+`data-shell-id`.
+
+### In the session hook
+
+`useTerminalSession` accepts a `shell` and exposes `switchShell(id)`. Switching
+**resets the buffer** and calls the transport's optional `connect(shell)` so the
+host can (re)wire its backend. Transports that don't care about shells just omit
+`connect` — fully backward compatible.
+
+```tsx
+const session = useTerminalSession({
+  shell: "pwsh",
+  transport: {
+    send: (d) => backend.send(d),
+    subscribe: (onChunk) => backend.onOutput(onChunk),
+    connect: (shell) => backend.connect(shell), // (re)connect to the chosen shell
+  },
+});
+
+// later — reset + reconnect to a new shell:
+session.switchShell("git-bash");
+<Terminal output={session.output} onData={session.sendData} />
+```
+
 ## Hooks
 
 ```tsx
@@ -105,10 +208,12 @@ const session = useTerminalSession({
 
 ## 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
+`<Terminal>` is **controlled** (`value`/`onData`, `activeShell`/`onShellChange`),
+carries **stable handles** (`data-fancy-terminal` + `data-fancy-terminal-shell`,
+`data-fancy-shell-switcher` / `data-shell-id`, plus the ref API), takes
+**JSON-friendly** props (including `ShellProfile[]`), and is **bridgeable** —
+`registerTerminalBridge` (in `agent-integrations`) maps `terminal_read` /
+`terminal_write` / `terminal_run` / `terminal_set_shell` onto the handle, wraps
 mutations so every write broadcasts `AgentActivity`, and supports a staged
 "agent proposes → human confirms" mode for destructive commands.
 

package/dist/index.cjs

@@ -87,7 +87,13 @@ function useTerminal(containerRef, options = {}) {
       },
       focus: () => xtermRef.current?.focus(),
       getBuffer: () => readBuffer(xtermRef.current),
-      getSelection: () => xtermRef.current?.getSelection() ?? ""
+      getSelection: () => xtermRef.current?.getSelection() ?? "",
+      // 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.
+      setShell: () => {
+      },
+      getShell: () => void 0
     };
   }
   const handle = handleRef.current;
@@ -145,12 +151,231 @@ function useTerminal(containerRef, options = {}) {
   return handle;
 }
 
+// src/types.ts
+function resolveShell(shells, id) {
+  if (!shells || id === void 0) return void 0;
+  return shells.find((s) => s.id === id);
+}
+var BUILTIN_SHELLS = [
+  { id: "cmd", label: "Command Prompt", icon: ">_", command: "cmd.exe" },
+  { id: "powershell", label: "Windows PowerShell", icon: "PS", command: "powershell.exe" },
+  { id: "pwsh", label: "PowerShell", icon: "PS", command: "pwsh" },
+  {
+    id: "git-bash",
+    label: "Git Bash",
+    icon: "",
+    command: "C:\\Program Files\\Git\\bin\\bash.exe",
+    args: ["--login", "-i"]
+  },
+  { id: "bash", label: "Bash", icon: "$", command: "bash" },
+  { id: "zsh", label: "Zsh", icon: "%", command: "zsh" }
+];
+var PANEL_BG = "#18181b";
+var BORDER = "#3f3f46";
+var FG = "#e4e4e7";
+var MUTED = "#a1a1aa";
+var ACCENT = "#8b5cf6";
+var HOVER_BG = "#27272a";
+function ShellSwitcher({
+  shells,
+  value,
+  onChange,
+  className,
+  style,
+  disabled
+}) {
+  const [open, setOpen] = react.useState(false);
+  const [activeIndex, setActiveIndex] = react.useState(0);
+  const rootRef = react.useRef(null);
+  const listId = react.useId();
+  const selected = resolveShell(shells, value);
+  const selectedIndex = selected ? shells.indexOf(selected) : -1;
+  react.useEffect(() => {
+    if (!open) return;
+    const onDocClick = (e) => {
+      if (rootRef.current && !rootRef.current.contains(e.target)) setOpen(false);
+    };
+    document.addEventListener("mousedown", onDocClick);
+    return () => document.removeEventListener("mousedown", onDocClick);
+  }, [open]);
+  const openMenu = react.useCallback(() => {
+    if (disabled) return;
+    setActiveIndex(selectedIndex >= 0 ? selectedIndex : 0);
+    setOpen(true);
+  }, [disabled, selectedIndex]);
+  const pick = react.useCallback(
+    (i) => {
+      const profile = shells[i];
+      if (!profile) return;
+      onChange(profile.id, profile);
+      setOpen(false);
+    },
+    [shells, onChange]
+  );
+  const onButtonKeyDown = (e) => {
+    if (disabled) return;
+    if (e.key === "ArrowDown" || e.key === "ArrowUp" || e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      openMenu();
+    }
+  };
+  const onListKeyDown = (e) => {
+    if (e.key === "Escape") {
+      e.preventDefault();
+      setOpen(false);
+      return;
+    }
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActiveIndex((i) => Math.min(shells.length - 1, i + 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActiveIndex((i) => Math.max(0, i - 1));
+    } else if (e.key === "Home") {
+      e.preventDefault();
+      setActiveIndex(0);
+    } else if (e.key === "End") {
+      e.preventDefault();
+      setActiveIndex(shells.length - 1);
+    } else if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      pick(activeIndex);
+    }
+  };
+  const buttonStyle = {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: 6,
+    height: 26,
+    padding: "0 8px",
+    fontSize: 12,
+    lineHeight: 1,
+    fontFamily: "inherit",
+    color: FG,
+    background: PANEL_BG,
+    border: `1px solid ${BORDER}`,
+    borderRadius: 6,
+    cursor: disabled ? "default" : "pointer",
+    opacity: disabled ? 0.6 : 1,
+    userSelect: "none"
+  };
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      ref: rootRef,
+      "data-fancy-shell-switcher": "",
+      "data-active-shell": value ?? void 0,
+      className,
+      style: { position: "relative", display: "inline-block", ...style },
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsxs(
+          "button",
+          {
+            type: "button",
+            "aria-haspopup": "listbox",
+            "aria-expanded": open,
+            "aria-label": "Select shell",
+            disabled,
+            style: buttonStyle,
+            onClick: () => open ? setOpen(false) : openMenu(),
+            onKeyDown: onButtonKeyDown,
+            children: [
+              selected?.icon ? /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", style: { color: ACCENT }, children: selected.icon }) : null,
+              /* @__PURE__ */ jsxRuntime.jsx("span", { children: selected?.label ?? "Select shell" }),
+              /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", style: { color: MUTED, fontSize: 9 }, children: "\u25BC" })
+            ]
+          }
+        ),
+        open ? /* @__PURE__ */ jsxRuntime.jsx(
+          "ul",
+          {
+            role: "listbox",
+            id: listId,
+            "aria-label": "Shells",
+            tabIndex: -1,
+            autoFocus: true,
+            onKeyDown: onListKeyDown,
+            ref: (el) => el?.focus(),
+            style: {
+              position: "absolute",
+              zIndex: 50,
+              top: "calc(100% + 4px)",
+              left: 0,
+              minWidth: "100%",
+              margin: 0,
+              padding: 4,
+              listStyle: "none",
+              background: PANEL_BG,
+              border: `1px solid ${BORDER}`,
+              borderRadius: 8,
+              boxShadow: "0 8px 24px rgba(0,0,0,0.45)",
+              outline: "none"
+            },
+            children: shells.map((s, i) => {
+              const isSelected = s.id === value;
+              const isActive = i === activeIndex;
+              return /* @__PURE__ */ jsxRuntime.jsxs(
+                "li",
+                {
+                  role: "option",
+                  "aria-selected": isSelected,
+                  "data-shell-id": s.id,
+                  onMouseEnter: () => setActiveIndex(i),
+                  onClick: () => pick(i),
+                  style: {
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    padding: "6px 8px",
+                    fontSize: 12,
+                    borderRadius: 5,
+                    color: FG,
+                    cursor: "pointer",
+                    background: isActive ? HOVER_BG : "transparent"
+                  },
+                  children: [
+                    /* @__PURE__ */ jsxRuntime.jsx(
+                      "span",
+                      {
+                        "aria-hidden": "true",
+                        style: {
+                          width: 18,
+                          textAlign: "center",
+                          color: isSelected ? ACCENT : MUTED
+                        },
+                        children: s.icon ?? ""
+                      }
+                    ),
+                    /* @__PURE__ */ jsxRuntime.jsx("span", { style: { flex: 1 }, children: s.label }),
+                    isSelected ? /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", style: { color: ACCENT, fontSize: 11 }, children: "\u2713" }) : null
+                  ]
+                },
+                s.id
+              );
+            })
+          }
+        ) : null
+      ]
+    }
+  );
+}
+
 // 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 };
 }
+
+// src/shell-select.ts
+function decideShellSelect(shells, current, id) {
+  const profile = resolveShell(shells, id);
+  if (!profile) return null;
+  return { profile, changed: current !== id };
+}
+function decideShellSwitch(current, next) {
+  return { changed: current !== next };
+}
 var Terminal = react.forwardRef(function Terminal2({
   output,
   theme,
@@ -166,11 +391,27 @@ var Terminal = react.forwardRef(function Terminal2({
   initialOutput,
   onData,
   onResize,
+  shells,
+  activeShell,
+  onShellChange,
+  showShellBar = false,
   className,
   style,
   ...rest
 }, ref) {
   const containerRef = react.useRef(null);
+  const isShellControlled = activeShell !== void 0;
+  const [internalShell, setInternalShell] = react.useState(void 0);
+  const shellId = isShellControlled ? activeShell : internalShell;
+  const shellStateRef = react.useRef({ shells, shellId, isShellControlled, onShellChange });
+  shellStateRef.current = { shells, shellId, isShellControlled, onShellChange };
+  const selectShell = react.useCallback((id) => {
+    const s = shellStateRef.current;
+    const decision = decideShellSelect(s.shells, s.shellId, id);
+    if (!decision) return;
+    if (!s.isShellControlled) setInternalShell(id);
+    s.onShellChange?.(id, decision.profile);
+  }, []);
   const handle = useTerminal(containerRef, {
     theme,
     rows,
@@ -188,7 +429,15 @@ var Terminal = react.forwardRef(function Terminal2({
     onData,
     onResize
   });
-  react.useImperativeHandle(ref, () => handle, [handle]);
+  react.useImperativeHandle(
+    ref,
+    () => ({
+      ...handle,
+      setShell: selectShell,
+      getShell: () => shellStateRef.current.shellId
+    }),
+    [handle, selectShell]
+  );
   const written = react.useRef("");
   react.useEffect(() => {
     if (output === void 0) return;
@@ -198,38 +447,102 @@ var Terminal = react.forwardRef(function Terminal2({
     handle.write(change.write);
     written.current = output;
   }, [output, handle]);
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const surface = /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
       ref: containerRef,
       "data-fancy-terminal": "",
       "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;
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      "data-fancy-terminal-shell": shellId ?? void 0,
       className,
-      style: { width: "100%", height: "100%", ...style },
-      ...rest
+      style: { display: "flex", flexDirection: "column", width: "100%", height: "100%", ...style },
+      ...rest,
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            style: {
+              display: "flex",
+              alignItems: "center",
+              gap: 8,
+              padding: "4px 6px",
+              background: "#09090b",
+              borderBottom: "1px solid #27272a"
+            },
+            children: /* @__PURE__ */ jsxRuntime.jsx(
+              ShellSwitcher,
+              {
+                shells,
+                value: shellId,
+                onChange: (id) => selectShell(id),
+                disabled: readOnly
+              }
+            )
+          }
+        ),
+        surface
+      ]
     }
   );
 });
 function useTerminalSession(options) {
-  const [output, setOutput] = react.useState(options.initial ?? "");
+  const initial = options.initial ?? "";
+  const [output, setOutput] = react.useState(initial);
+  const [internalShell, setInternalShell] = react.useState(options.shell);
+  const shell = options.shell !== void 0 ? options.shell : internalShell;
   const transportRef = react.useRef(options.transport);
   transportRef.current = options.transport;
+  const initialRef = react.useRef(initial);
+  initialRef.current = initial;
   react.useEffect(() => {
     const unsub = transportRef.current.subscribe((chunk) => setOutput((o) => o + chunk));
     return () => {
       if (typeof unsub === "function") unsub();
     };
   }, []);
+  const connectedShell = react.useRef(void 0);
+  const mounted = react.useRef(false);
+  react.useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      connectedShell.current = shell;
+      void transportRef.current.connect?.(shell);
+      return;
+    }
+    if (!decideShellSwitch(connectedShell.current, shell).changed) return;
+    connectedShell.current = shell;
+    setOutput(initialRef.current);
+    void transportRef.current.connect?.(shell);
+  }, [shell]);
   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 };
+  const switchShell = react.useCallback((id) => {
+    setInternalShell((cur) => cur === id ? cur : id);
+    if (!decideShellSwitch(connectedShell.current, id).changed) return;
+    connectedShell.current = id;
+    setOutput(initialRef.current);
+    void transportRef.current.connect?.(id);
+  }, []);
+  return { output, sendData, append, clear, shell, switchShell };
 }
 
+exports.BUILTIN_SHELLS = BUILTIN_SHELLS;
+exports.ShellSwitcher = ShellSwitcher;
 exports.Terminal = Terminal;
 exports.fancyDarkTheme = fancyDarkTheme;
+exports.resolveShell = resolveShell;
 exports.useTerminal = useTerminal;
 exports.useTerminalFit = useTerminalFit;
 exports.useTerminalSession = useTerminalSession;