@particle-academy/fancy-term 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,199 @@
+# 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.1 — 2026-10-10
+
+### Added
+
+- **`@particle-academy/fancy-term/styles.css`** — the same stylesheet under the
+  name the rest of the kit uses.
+
+  0.6.0 shipped the re-export as `/xterm.css` only, which was descriptive but
+  wrong by convention: `fancy-code`, `fancy-whiteboard`, `fancy-artboard`,
+  `fancy-sheets` and `fancy-slides` **all** export `./styles.css`, unanimously.
+  A consumer who knows the kit types that name, and in 0.6.0 they got a resolve
+  error. Both names now serve the one file, and a test asserts they cannot drift
+  apart.
+
+  Use whichever reads better — `/styles.css` for consistency with the rest of
+  your Fancy imports, `/xterm.css` if you would rather the import said what it
+  actually is. Nothing to change if you are already on `/xterm.css`.
+
+## 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

@@ -34,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-term",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "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,17 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
-    }
+    },
+    "./styles.css": "./xterm.css",
+    "./xterm.css": "./xterm.css",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "xterm.css",
     "docs",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -47,8 +52,8 @@
     "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"
   },
@@ -71,7 +76,8 @@
   },
   "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";