@jsenv/terminal-recorder 1.5.16 → 1.5.18

package/README.md

@@ -1,20 +1,61 @@
-# terminal snapshot [![npm package](https://img.shields.io/npm/v/@jsenv/terminal-recorder.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/terminal-recorder)
+# Terminal Recorder [![npm package](https://img.shields.io/npm/v/@jsenv/terminal-recorder.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/terminal-recorder)
 
-Help to generate beautiful terminal snapshots:
+Create beautiful terminal recordings in multiple formats for documentation and demos.
 
-## svg
+🎬 Generate static SVGs of terminal output  
+🎭 Create animated GIF recordings  
+🎥 Export MP4 and WebM videos  
+🎨 Full ANSI color and Unicode support
 
-![toto](./docs/svg/terminal.svg)
+## Output Examples
 
-## gif
+### SVG (Static)
 
-![toto](./docs/animated/terminal.gif)
+![Terminal SVG Example](./docs/svg/terminal.svg)
 
-## Example
+### GIF (Animated)
+
+![Terminal GIF Example](./docs/animated/terminal.gif)
+
+## Installation
+
+```console
+npm install @jsenv/terminal-recorder
+```
+
+## Quick Start
 
 ```js
 import { writeFileSync } from "node:fs";
+import { startTerminalRecording } from "@jsenv/terminal-recorder";
 
+// Start recording with multiple output formats
+const recorder = await startTerminalRecording({
+  svg: { title: "Terminal Demo" },
+  gif: true,
+  video: true,
+});
+
+// Write terminal content with ANSI color codes
+recorder.write("[1;32mHello[0m [1;34mWorld![0m");
+
+// Wait a moment for animation
+await new Promise((resolve) => setTimeout(resolve, 500));
+
+// Stop recording and get results
+const result = await recorder.stop();
+
+// Save in different formats
+writeFileSync("./terminal.svg", await result.svg());
+writeFileSync("./terminal.gif", await result.gif());
+writeFileSync("./terminal.mp4", await result.mp4());
+writeFileSync("./terminal.webm", await result.webm());
+```
+
+## Full Example
+
+```js
+import { writeFileSync } from "node:fs";
 import { startTerminalRecording } from "@jsenv/terminal-recorder";
 
 const terminalRecorder = await startTerminalRecording({
@@ -24,28 +65,136 @@ const terminalRecorder = await startTerminalRecording({
   video: true,
   gif: true,
 });
+
+// Show colorful text with delays between each line
 const datas = [
-  `red `,
-  `yellow `,
-  `green `,
-  `cyan `,
-  `blue `,
-  `magenta`,
+  `[31mred[39m `,
+  `[33myellow[39m `,
+  `[32mgreen[39m `,
+  `[36mcyan[39m `,
+  `[34mblue[39m `,
+  `[35mmagenta[39m`,
 ];
+
 for (const data of datas) {
   terminalRecorder.write(data);
   await new Promise((resolve) => setTimeout(resolve, 200));
 }
+
+// Stop recording and export all formats
 const result = await terminalRecorder.stop();
+
+// Save outputs
 const svg = await result.svg();
 writeFileSync(new URL("./terminal.svg", import.meta.url), svg);
+
 const gif = await result.gif();
 writeFileSync(new URL("./terminal.gif", import.meta.url), gif);
+
 const webm = await result.webm();
 writeFileSync(new URL("./terminal.webm", import.meta.url), webm);
+
 const mp4 = await result.mp4();
 writeFileSync(new URL("./terminal.mp4", import.meta.url), mp4);
 ```
 
-The animated formats (.gif, .webm, .mp4) are rendered by xterm in chrome headless using playwright.
-Xterm is used by VsCode integrated terminal, it supports ansi, unicode and so on.
+## API Reference
+
+### startTerminalRecording(options)
+
+Starts a terminal recording session with the specified options.
+
+```js
+const recorder = await startTerminalRecording({
+  // SVG options (set to false to disable)
+  svg: {
+    title: "My Terminal", // Title shown in the terminal window
+    width: 800, // Width in pixels
+    height: 400, // Height in pixels
+    fontSize: 14, // Font size in pixels
+    fontFamily: "monospace", // Font family
+    theme: {
+      // Terminal color theme
+      background: "#1e1e1e",
+      foreground: "#ffffff",
+      // Additional theme options...
+    },
+  },
+
+  // Enable video output formats (WebM, MP4)
+  video: true,
+
+  // Enable GIF output
+  gif: {
+    fps: 10, // Frames per second
+    quality: 80, // Quality (1-100)
+    repeat: 0, // 0 = loop forever, -1 = no repeat, n = repeat n times
+  },
+
+  // Terminal configuration
+  cols: 80, // Number of columns
+  rows: 24, // Number of rows
+});
+```
+
+### recorder.write(data)
+
+Writes data to the terminal. Supports ANSI color codes and escape sequences.
+
+```js
+// Simple text
+recorder.write("Hello World");
+
+// With ANSI colors
+recorder.write("\x1b[31mRed Text\x1b[0m");
+
+// With SGR parameters
+recorder.write("[1;32mBold Green[0m");
+```
+
+### recorder.stop()
+
+Stops the recording and returns a result object with methods to generate different output formats.
+
+```js
+const result = await recorder.stop();
+
+// Get SVG string
+const svg = await result.svg();
+
+// Get GIF buffer
+const gif = await result.gif();
+
+// Get WebM video buffer
+const webm = await result.webm();
+
+// Get MP4 video buffer
+const mp4 = await result.mp4();
+```
+
+## How It Works
+
+- **SVG generation**: Direct rendering of terminal state to SVG
+- **Animated formats**: Uses [xterm.js](https://xtermjs.org/) in Chrome headless via Playwright
+- **Video encoding**: Leverages browser's video encoding capabilities
+
+## Compatibility
+
+- Node.js: 16.x and above
+- Requires Playwright for animated formats
+- Works on macOS, Linux, and Windows
+
+## Use Cases
+
+- Create documentation with terminal examples
+- Record CLI tool demos for README files
+- Generate terminal screenshots for blog posts
+- Create animated terminal presentations
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@jsenv/terminal-recorder",
-  "version": "1.5.16",
+  "version": "1.5.18",
   "description": "Record terminal output as .svg, .gif, .webm, .mp4",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/jsenv/core",
-    "directory": "packages/independent/tooling/terminal-recorder"
+    "directory": "packages/tooling/terminal-recorder"
   },
   "author": {
     "name": "dmail",
@@ -20,7 +20,7 @@
     ".": {
       "node": "./src/main.js",
       "browser": {
-        "development": "./src/main_browser.js",
+        "dev:jsenv": "./src/main_browser.js",
         "default": "./dist/terminal_recorder_browser.js"
       }
     },
@@ -37,8 +37,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/humanize": "1.5.1",
-    "@jsenv/server": "16.1.1",
+    "@jsenv/humanize": "1.6.0",
+    "@jsenv/server": "16.1.2",
     "@playwright/browser-chromium": "1.51.1",
     "@jsenv/terminal-text-size": "0.0.1",
     "ansi-regex": "6.1.0",
@@ -52,6 +52,13 @@
     "@xterm/addon-fit": "0.10.0",
     "@xterm/addon-serialize": "0.13.0",
     "@xterm/addon-webgl": "0.18.0",
-    "@xterm/xterm": "5.5.0"
+    "@xterm/xterm": "5.5.0",
+    "@jsenv/core": "../../../",
+    "@jsenv/assert": "../assert",
+    "@jsenv/https-local": "../https-local",
+    "@jsenv/filesystem": "../filesystem",
+    "@jsenv/snapshot": "../snapshot",
+    "@jsenv/terminal-recorder": "./",
+    "@jsenv/plugin-commonjs": "../../related/plugin-commonjs"
   }
 }

package/src/.jsenv/chrome@134.00/@fs/Users/dmail/Documents/dev/{core → jsenv/core}/node_modules/@xterm/addon-serialize/lib/addon-serialize.mjs.map

@@ -12,17 +12,17 @@
     "webpack://SerializeAddon/src/common/services/Services.ts",
     "webpack://SerializeAddon/webpack/bootstrap",
     "webpack://SerializeAddon/src/SerializeAddon.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/webpack/universalModuleDefinition",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/browser/ColorContrastCache.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/browser/services/ThemeService.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/common/Color.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/common/EventEmitter.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/common/Lifecycle.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/common/MultiKeyMap.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/common/services/ServiceRegistry.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/common/services/Services.ts",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/webpack/bootstrap",
-    "file:///Users/dmail/Documents/dev/core/webpack:/SerializeAddon/src/SerializeAddon.ts"
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/webpack/universalModuleDefinition",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/browser/ColorContrastCache.ts",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/browser/services/ThemeService.ts",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/common/Color.ts",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/common/EventEmitter.ts",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/common/Lifecycle.ts",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/common/MultiKeyMap.ts",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/common/services/ServiceRegistry.ts",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/common/services/Services.ts",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/webpack/bootstrap",
+    "file:///Users/dmail/Documents/dev/jsenv/core/webpack:/SerializeAddon/src/SerializeAddon.ts"
   ],
   "names": [
     "root",