@particle-academy/fancy-term 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+All notable changes to `@particle-academy/fancy-term` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+> **Pre-1.0:** breaking changes land in MINOR releases. Until 1.0 the minor
+> number is not a compatibility promise — read the entry, not the version.
+
+> This file starts here. Earlier releases predate it and were never written up;
+> `git log` is the record for those. It is not backfilled rather than
+> guessed-at, because a changelog that invents its own history is worse than one
+> that admits where it begins.
+
+## [Unreleased]
+
+## 0.6.0 — 2026-10-10
+
+### Added
+
+- **`@particle-academy/fancy-term/xterm.css` — load the stylesheet without naming xterm.**
+
+  ```ts
+  import "@particle-academy/fancy-term/xterm.css";
+  ```
+
+  The terminal has never rendered without xterm's stylesheet, so every consumer
+  had to write `import "@xterm/xterm/css/xterm.css"` in their own source — which
+  made xterm the one third-party package a Fancy-only app still had to name.
+
+  **Nothing to do.** The old import is identical in effect and still works; this
+  is an additional way in, not a replacement. The new subpath is an `@import` of
+  xterm's own stylesheet rather than a copy of it, so it resolves to the single
+  copy already in your tree and there is no vendored third-party file to drift.
+
+### Changed
+
+- **The `@xterm/*` peer ranges are now bounded above** — `@xterm/xterm` moves
+  from `>=5.0.0` to `>=5.0.0 <6`, and `@xterm/addon-fit` from `>=0.10.0` to
+  `>=0.10.0 <0.11`.
+
+  **This was live, not theoretical.** `@xterm/xterm@6.0.0` and
+  `@xterm/addon-fit@0.11.0` are both `latest` on npm as of today, so the old
+  ranges admitted a MAJOR this package has never been built against — and
+  nothing reported it, because a resolver quietly picking an untested version
+  looks exactly like success. The pairing made it worse rather than safer:
+  `addon-fit@0.10.0` declares `peerDependencies: {"@xterm/xterm": "^5.0.0"}` and
+  accidentally held the line, while **`0.11.0` declares no peer at all** — so
+  `>=0.10.0` plus `>=5.0.0` allowed xterm 6 with addon-fit 0.11, an untested
+  combination, silently.
+
+  **What you must do: almost certainly nothing.** If you are on xterm 5.x and
+  addon-fit 0.10.x — what `npm install` has been resolving all along, and what
+  this package is built and tested against — the range still admits your
+  version and the upgrade is invisible. **If you have explicitly moved to xterm
+  6 or addon-fit 0.11, this release will now fail at install with a peer
+  conflict instead of running untested code.** That is the intended behaviour:
+  it turns a silent runtime risk into a loud install-time error. Tell us and we
+  will qualify 6 properly — widening a range later is safe by construction,
+  since it only ever adds candidates.
+
+  `>=X <2.0` remains correct for a *first-party* sibling, where we cut the
+  releases and the upper bound is a promise we keep. On third-party it is a
+  promise someone else makes.
+
+- **xterm stays a PEER deliberately, and this is the release that writes down
+  why.** `<Terminal>` hands the live `XTerm` instance to the consumer through
+  `handle.xterm`, `handle.ready` and `onReady(xterm)` — the same reason a React
+  component cannot own its copy of React. If this package owned xterm, a
+  consumer on a different version would get two copies and addons and
+  `instanceof` would operate on the wrong class with no warning. The peer's
+  value is not "one copy", it is that a conflict fails loudly at install. The
+  reasoning now sits in the README, in `src/index.ts`, in `xterm.css` and in
+  `src/packaging.test.ts`, so the next person who proposes tidying it into
+  `dependencies` meets the argument first.
+
+### Fixed
+
+- **`CHANGELOG.md` is now in the published tarball.** `files` did not whitelist it, so npm never shipped it — and this package puts breaking changes in MINOR releases and tells you in the README to read the entry before taking one. The instruction existed for the author, who has the file, and not for the consumer, who is the only one being instructed. Nothing for you to do; the file simply arrives from this release on.
+
+### Security
+
+- `source-map-js` is pinned forward to `^1.2.2` via `overrides`. Versions up to
+  1.2.1 allow an event-loop denial of service through indexed source-map section
+  offsets, and it arrives here transitively through the build toolchain.
+  **Nothing for a consumer to do, and no runtime change**: an npm package does
+  not ship a lockfile, so this governs builds OF this repo, not anything
+  installed FROM it. Recorded rather than left silent because the override it
+  sits beside — `shell-quote` `^1.9.0`, added for an earlier advisory — was
+  carried with no note of why, and had drifted back inside the vulnerable range
+  before anyone looked.
+
+## 0.5.1 — 2026-09-29
+
+### Fixed
+
+- **`docs/` is real now.** `files` already listed `docs`, and the directory did
+  not exist — so every published tarball carried a `files` entry pointing at
+  nothing and shipped no reference at all. That is the worse half of this
+  defect: a `files` array that names `docs` reads as compliant to anyone
+  checking the manifest, so nothing ever looked in the tarball.
+
+  Adds `docs/Terminal.md` and `docs/ShellSwitcher.md` — the full prop and
+  `TerminalOptions` tables, the imperative handle (including `getBuffer()`, the
+  Human+ affordance an agent reads instead of scraping the DOM), why the
+  clipboard is injectable and what silently breaks in a sandboxed Electron
+  renderer without a provider, why OSC 52 defaults to write-only, and how
+  pasted images reach the host.
+
+  No code changed.
+
+## 0.5.0 — 2026-08-07
+
+### Changed
+
+- **BREAKING — Node 22 is now declared as the floor.** `engines.node` is `>=22`, where this package previously declared **nothing at all**.
+
+  Declaring nothing was not the same as supporting old Node: a consumer on 18 installed cleanly and found out at runtime.
+
+  **What you must do:** on Node 22 or newer, nothing. Note npm only *warns* on an `engines` mismatch while **pnpm fails the install**, so this surfaces differently depending on your package manager. Node 18 is end-of-life and 20 is maintenance-only.
+
+- **BREAKING — React 18 is no longer supported.** `peerDependencies.react` / `react-dom` are now `^19.0.0`.
+
+  **What you must do:** on React 19, nothing. On React 18, stay on the previous release, or upgrade your app to 19 first.
+
+  React 18 support was a claim nothing tested — every build and test in this package ran against 19, so the 18 half of the old range was never executed. An untested compatibility claim is worse than an absent one, because it reads as support.
+
+### Why
+
+These are the kit 0.5 platform floors, applied across every package at once so a consumer never has to resolve a mix. **No API changed, nothing was removed, nothing was renamed** — only what the package requires.
+
+
+## 0.4.1 — 2026-07-06
+
+### Fixed
+
+- context-menu Copy writes the menu-open selection snapshot, not a click-time re-read
+
+## 0.4.0 — 2026-07-02
+
+### Added
+
+- Electron-safe clipboard — injectable provider, OSC 52, copy/paste modes, ready signal (#1)
+
+## 0.3.0 — 2026-06-14
+
+### Added
+
+- clipboard (copy/paste + images) + customizable selection context menu
+
+## 0.2.2 — 2026-06-11
+
+### Fixed
+
+- omit undefined rows/cols from xterm constructor (was console-erroring)
+
+## 0.2.1 — 2026-06-11
+
+### Fixed
+
+- guard fit() via proposeDimensions — no xterm resize(undefined) on unlaid-out container
+
+## 0.2.0 — 2026-06-11
+
+### Changed
+
+- **BREAKING** — shell / profile switching (UI + API + session)
+
+## 0.1.0 — 2026-06-10
+
+### Added
+
+- fancy-term 0.1.0 — Human+ Terminal (xterm.js wrapper)
+
+### Changed
+
+- Replaced an `eslint-disable jsx-a11y/no-autofocus` in `ShellSwitcher` with a
+  plain comment explaining why the autofocus is deliberate. `jsx-a11y` has never
+  been a dependency of this package, so the directive silenced a rule that did
+  not exist — and broke linting the moment ESLint was actually turned on.
+  **No action needed**, no behaviour change.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,7 @@
 # @particle-academy/fancy-term
 
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
 **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
@@ -16,7 +18,7 @@ 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.2.0. `<Terminal>` + `useTerminal` / `useTerminalFit` /
+> **Status:** pre-1.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
@@ -32,12 +34,29 @@ 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:
+stylesheet once in your app, from here rather than from xterm:
 
 ```ts
-import "@xterm/xterm/css/xterm.css";
+import "@particle-academy/fancy-term/xterm.css";
 ```
 
+Without it the terminal does not render: xterm's character-measurement helper
+has to stay out of layout, and without these rules it does not, so the cell size
+comes out wrong.
+
+That subpath re-exports xterm's own stylesheet with `@import`, so it resolves to
+the single copy already in your tree. `import "@xterm/xterm/css/xterm.css"` is
+identical in effect and still works — the subpath exists so a Fancy-only app has
+no reason to name a third-party package in its own source.
+
+**Why xterm is a peer and not a dependency**, since it is the obvious thing to
+"tidy": `<Terminal>` hands you the live `XTerm` instance — `handle.xterm`,
+`handle.ready`, `onReady(xterm)` — exactly as a React component hands out React
+elements and therefore cannot own React. If this package owned its own xterm
+copy, a consumer on a different version would get two, and addons and
+`instanceof` would operate on the wrong class with no warning anywhere. The peer
+turns that silent runtime break into a loud install-time error.
+
 ## `<Terminal>`
 
 The parent needs a height — the terminal fits its container (like any xterm

package/docs/ShellSwitcher.md

@@ -0,0 +1,57 @@
+# ShellSwitcher
+
+The shell/profile selector shown above a `<Terminal>`. fancy-term renders the
+control and tracks the choice; **the host owns the list and does the work** —
+reconnecting a PTY to the chosen shell is yours.
+
+## Import
+
+```tsx
+import { ShellSwitcher, BUILTIN_SHELLS, resolveShell } from "@particle-academy/fancy-term";
+```
+
+## Usage
+
+Most hosts never render it directly — set `showShellBar` on `<Terminal>`:
+
+```tsx
+<Terminal
+  shells={BUILTIN_SHELLS}
+  showShellBar
+  onShellChange={(id, profile) => session.reconnect(profile)}
+/>
+```
+
+Render it yourself when it belongs somewhere else in your chrome:
+
+```tsx
+<ShellSwitcher shells={shells} active={id} onChange={setId} />
+```
+
+## `ShellProfile`
+
+A profile is plain data, so an agent can emit one and a host can store it:
+
+| Field | Description |
+|---|---|
+| id | The id used by `activeShell`, `setShell` and `onShellChange`. |
+| label | What the user sees. |
+| … | Whatever else your backend needs to launch it. |
+
+`BUILTIN_SHELLS` is a set of sensible presets to spread, not a fixed menu —
+add, remove or replace freely.
+
+## `resolveShell(shells, id)`
+
+The pure helper that `setShell`, `<ShellSwitcher>` and the session hook all
+agree on. Returns the matching `ShellProfile`, or `undefined` when the id is not
+in the list — which is why an unknown id is a no-op rather than a crash.
+
+## Controlled vs uncontrolled
+
+Pass `activeShell` to control the selection. Omit it and `<Terminal>` tracks it
+internally; `handle.setShell(id)` still works and still fires `onShellChange`.
+
+## See also
+
+- [Terminal](./Terminal.md)

package/docs/Terminal.md

@@ -0,0 +1,117 @@
+# Terminal
+
+A controlled, themeable terminal over xterm.js. The output buffer is React
+state, so a host can stream command output straight from its own data layer,
+and an agent can read what the human sees.
+
+## Import
+
+```tsx
+import { Terminal } from "@particle-academy/fancy-term";
+```
+
+## Basic Usage
+
+```tsx
+<Terminal output={log} onData={(d) => pty.write(d)} />
+```
+
+## Controlled output
+
+`output` is diffed against the previous value and only the **appended delta** is
+written, so re-rendering on every chunk is cheap — wire it to a stream and let
+React do the rest. Replacing `output` with a string that does not extend the
+previous one resets the terminal and rewrites it.
+
+## Props
+
+Extends `TerminalOptions` (below) and the native `<div>` attributes, minus
+`onInput`, `onResize`, `onPaste`, `contextMenu` and `children`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| output | `string` | — | The controlled buffer. Only the appended delta is written. |
+| shells | `ShellProfile[]` | — | The shells/profiles you offer. Spread `BUILTIN_SHELLS` for presets; the host owns the list. |
+| activeShell | `string` | — | Controlled active shell id. Omit for internal selection. |
+| onShellChange | `(id, profile) => void` | — | Fired when the user or `setShell` switches. |
+| showShellBar | `boolean` | `false` | Render the built-in `<ShellSwitcher>` above the surface. Opt-in so existing layout is unchanged. |
+| contextMenu | `TerminalContextMenuConfig` | `true` | `false` disables; an array replaces the items; `(ctx, defaults) => items` lets you add/reorder. |
+
+### `TerminalOptions`
+
+| Option | Type | Default | Description |
+|------|------|---------|-------------|
+| theme | `TerminalTheme` | Fancy dark | xterm colour theme. |
+| rows / cols | `number` | — | Fixed grid. Omit and leave `fit` on to size from the container. |
+| fit | `boolean` | `true` | Auto-fit via the fit addon + `ResizeObserver`. |
+| readOnly | `boolean` | `false` | Block stdin (display-only). |
+| cursorBlink | `boolean` | `true` | |
+| cursorStyle | `CursorStyle` | `"block"` | |
+| fontFamily | `string` | — | Monospace stack. |
+| fontSize | `number` | `13` | |
+| scrollback | `number` | `1000` | |
+| initialOutput | `string` | — | Written once on mount, before any controlled `output`. |
+| onData | `(data: string) => void` | — | Keystrokes and paste data. Wire to your PTY. |
+| onResize | `(size) => void` | — | |
+| clipboard | `ClipboardOption` | `true` | See below. |
+| osc52 | `Osc52Mode` | `"copy"` | See below. |
+| copyPaste | `CopyPasteMode` | — | `"contextmenu"`, `"linux"` (highlight-to-copy, middle-click paste) or `"winmac"`. Ctrl+Shift+C always copies. |
+| onReady | `(xterm: XTerm) => void` | — | Once opened and attached — the imperative twin of `handle.ready`. |
+| onPaste | `(payload) => void \| boolean` | — | See "Pasted images" below. |
+
+## Clipboard is injectable, and that matters in Electron
+
+`clipboard` gates the copy chord, the paste interceptor, the context-menu
+copy/paste and OSC 52:
+
+- `true` / omitted — backed by `navigator.clipboard`.
+- `false` — disabled. Native text paste still works.
+- a `{ writeText, readText }` **provider** — every copy/paste path routes
+  through it.
+
+Supply a provider in a sandboxed Electron renderer, where `navigator.clipboard`
+**silently no-ops**, to bridge to the main-process clipboard over IPC. Silently
+is the operative word: without it, copy appears to work and nothing lands.
+
+## OSC 52 defaults to write-only, deliberately
+
+Terminal programs (Claude Code, tmux, vim) can set or read the system clipboard
+via `ESC ] 52`. `osc52` is `"copy"` by default — writes only. `"read"` and
+`"both"` also answer read requests, which lets anything running in the terminal
+exfiltrate the clipboard, so they are opt-in. `false` disables it entirely.
+
+## Pasted images
+
+`onPaste` receives `{ text, files, images }` on every paste. Plain text still
+pastes natively; this is where a host receives pasted **images**, which a shell
+cannot render — upload them, hand them to an agent, or write a path. Return
+`false` to consume the paste entirely (for example to transform it, then call
+`handle.paste(...)` yourself).
+
+## Imperative handle
+
+| Member | Type | Description |
+|---|---|---|
+| xterm | `XTerm \| null` | The instance. Null before mount. |
+| ready | `Promise<XTerm>` | Resolves once opened and measured. `await` it instead of polling; re-armed if the terminal is recreated. |
+| write / writeln | `(data: string) => void` | Raw write; ANSI honoured. |
+| clear / reset | `() => void` | Viewport (keeps scrollback) / full reset. |
+| fit | `() => void` | Re-fit. No-op on a 0-size box or with `fit` off. |
+| focus | `() => void` | |
+| getBuffer | `() => string` | The full buffer as plain text — **what an agent "sees"**. |
+| getSelection | `() => string` | |
+| copySelection | `() => Promise<boolean>` | False when nothing is selected or no clipboard. |
+| paste | `(text?) => Promise<void>` | Reads the system clipboard with no argument. Honours bracketed paste. |
+| selectAll / clearSelection | `() => void` | |
+| setShell | `(id: string) => void` | Resolves the profile and fires `onShellChange`. No-op for an unknown id. |
+| getShell | `() => string \| undefined` | |
+
+`getBuffer()` is the Human+ affordance: an agent reads the same text the person
+is looking at, rather than scraping the DOM.
+
+## Headless hooks
+
+`useTerminal`, `useTerminalFit` and `useTerminalSession` expose the engine layer
+if you would rather build your own surface. `useTerminalSession` takes a
+`TerminalSessionTransport` and manages connect/reconnect against your backend —
+see [ShellSwitcher](./ShellSwitcher.md) for the shell-selection half.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-term",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -22,12 +22,16 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
-    }
+    },
+    "./xterm.css": "./xterm.css",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "xterm.css",
     "docs",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -47,31 +51,32 @@
     "fancy"
   ],
   "peerDependencies": {
-    "@xterm/addon-fit": ">=0.10.0",
-    "@xterm/xterm": ">=5.0.0",
+    "@xterm/addon-fit": ">=0.10.0 <0.11",
+    "@xterm/xterm": ">=5.0.0 <6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/xterm": "^5.5.0",
     "eslint": "^10.8.0",
     "eslint-plugin-react-hooks": "^7.1.1",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tsup": "^8.5.0",
     "typescript": "^5.8.0",
     "typescript-eslint": "^8.65.0",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"
   },
   "license": "MIT",
   "overrides": {
-    "esbuild": "^0.28.1"
+    "esbuild": "^0.28.1",
+    "source-map-js": "^1.2.2"
   },
   "engines": {
     "node": ">=22"

package/xterm.css

@@ -0,0 +1,28 @@
+/**
+ * @particle-academy/fancy-term/xterm.css
+ *
+ * The stylesheet <Terminal> needs, loadable without naming xterm.
+ *
+ *     import "@particle-academy/fancy-term/xterm.css";
+ *
+ * xterm.js does not render without its own stylesheet — its character-measurement
+ * helper is absolutely positioned, so without these rules it participates in
+ * layout and the terminal computes a wrong cell size. Every consumer therefore
+ * had to write `import "@xterm/xterm/css/xterm.css"` in their own source, which
+ * made xterm the one third-party package a Fancy-only app still had to name.
+ *
+ * This is an @import, deliberately, NOT a copy of xterm's stylesheet:
+ *
+ *   • It resolves from the CONSUMER's tree, where the peer is installed — so
+ *     there is still exactly one xterm, which is the whole reason xterm is a
+ *     peer rather than a dependency (<Terminal> hands the live XTerm instance
+ *     out through `handle.xterm` / `handle.ready` / `onReady`, so a second copy
+ *     would silently break addons and `instanceof`).
+ *   • A vendored copy would drift from the xterm version actually installed,
+ *     and would make us a redistributor of a third-party file.
+ *
+ * `src/packaging.test.ts` pins it: with comments stripped, this file must be
+ * EXACTLY the one @import below and nothing else. So do not add a rule here —
+ * app-level overrides belong in the app, where they can be seen.
+ */
+@import "@xterm/xterm/css/xterm.css";