@steve02081504/virtual-console 0.0.8 → 0.1.1

package/README.md

@@ -3,43 +3,27 @@
 [![npm version](https://img.shields.io/npm/v/@steve02081504/virtual-console.svg)](https://www.npmjs.com/package/@steve02081504/virtual-console)
 [![GitHub issues](https://img.shields.io/github/issues/steve02081504/virtual-console)](https://github.com/steve02081504/virtual-console/issues)
 
-A powerful and flexible virtual console for Node.js that allows you to capture, manipulate, and redirect terminal output. Built with modern asynchronous contexts (`AsyncLocalStorage`) for robust, concurrency-safe operations.
+A powerful and flexible virtual console for **Node.js and the Browser** that allows you to capture, manipulate, redirect, and transform terminal output.
 
-`VirtualConsole` is perfect for:
+`VirtualConsole` acts as a smart proxy for the global `console`, providing:
 
-- **Testing:** Assert console output from your modules without polluting the test runner's output.
-- **Logging Frameworks:** Create custom logging solutions that can buffer, format, or redirect logs.
-- **CLI Tools:** Build interactive command-line interfaces with updatable status lines or progress bars.
-- **Debugging:** Isolate and inspect output from specific parts of your application, even in highly concurrent scenarios.
-
----
-
-## How It Works: The Global Console Proxy
-
-**This library is designed for zero-refactoring integration.** Upon import, it replaces `globalThis.console` with a smart proxy that is aware of the asynchronous execution context.
-
-1. **The Proxy:** The new `console` object is a proxy. When you call a method like `console.log()`, the proxy intercepts the call.
-
-2. **`AsyncLocalStorage` for Isolation:** The proxy uses `AsyncLocalStorage` to look up the currently active `VirtualConsole` instance for the current async operation.
-
-3. **Context-Aware Routing:**
-    - If you have activated a `VirtualConsole` instance using `vc.hookAsyncContext()`, the proxy finds your instance and routes all `console` calls to it. This allows your instance to capture output, handle stateful methods like `freshLine`, or apply custom logic.
-    - If no instance is active for the current context, the proxy forwards the call to a default, passthrough console that simply prints to the original terminal, just like the real `console` would.
-
-This architecture means you **don't need to refactor your code to pass console instances around**. Just keep using the global `console` as you always have, and wrap the code you want to monitor in a hook.
-
-**Enhanced Compatibility:** The proxy is designed to be a good citizen. If other libraries or your own code assign custom properties to the global `console` object (e.g., `console.myLogger = ...`), these properties are preserved and remain accessible.
+- **Async Context Isolation:** Safely capture output per request or task using `AsyncLocalStorage` (Node.js) or stack-based scoping (Browser).
+- **HTML Output Generation:** Automatically converts ANSI colors and console formatting (including `%c`) into HTML strings for display in web UIs or reports.
+- **Zero-Refactoring:** Works by proxying the global `console`, so you don't need to change your existing logging code.
 
 ## Features
 
-- **Zero-Configuration Capturing:** Capture output from any module without changing its source code.
-- **Concurrency-Safe Isolation:** Uses `AsyncLocalStorage` to guarantee that output from concurrent operations is captured independently and correctly.
-- **Output Recording:** Captures all `stdout` and `stderr` output to a string property for easy inspection.
-- **Real Console Passthrough:** Optionally, print to the actual console while also capturing.
-- **Full TTY Emulation:** Behaves like a real TTY, inheriting properties like `columns`, `rows`, and color support from the base console. It also respects terminal resize events.
-- **Updatable Lines (`freshLine`)**: A stateful method for creating overwritable lines, perfect for progress indicators. Requires a TTY with ANSI support.
-- **Custom Error Handling:** Provide a dedicated handler for `Error` objects passed to `console.error`.
-- **Extensible:** Can be integrated with other async-context-aware libraries via `setGlobalConsoleReflect`.
+- **Universal Compatibility:** Works in both Node.js and Browser environments.
+- **Output Recording:** Captures `stdout` and `stderr` to plain text (`outputs`) and **HTML** (`outputsHtml`).
+- **ANSI & HTML Support:**
+  - Node.js: Preserves ANSI color codes.
+  - Browser/HTML: Converts ANSI codes and `%c` CSS styles to inline HTML styles.
+- **Concurrency-Safe (Node.js):** Uses `AsyncLocalStorage` to guarantee that output from concurrent async operations is captured independently.
+- **Real Console Passthrough:** Optionally prints to the actual console/terminal while capturing.
+- **FreshLine (Updatable Lines):** Stateful method for creating overwritable lines (e.g., progress bars).
+  - *Node.js:* Uses ANSI escape codes to overwrite lines.
+  - *Browser:* Falls back gracefully to standard logging (simulated behavior).
+- **Custom Error Handling:** Dedicated interception for `console.error(new Error(...))`.
 
 ## Installation
 
@@ -47,95 +31,82 @@ This architecture means you **don't need to refactor your code to pass console i
 npm install @steve02081504/virtual-console
 ```
 
-## Quick Start: Testing Console Output
+## Usage
 
-The most common use case is testing. Wrap your function call in `hookAsyncContext` and then assert the captured output.
+### 1. Basic Testing (Capture Output)
+
+Wrap your function call in `hookAsyncContext` and assert the captured output.
 
 ```javascript
 import { VirtualConsole } from '@steve02081504/virtual-console';
 import { strict as assert } from 'node:assert';
 
-// 1. A function that logs to the console
 function greet(name) {
-  console.log(`Hello, ${name}!`);
-  console.error('An example error.');
+	console.log(`Hello, ${name}!`);
+	console.error(new Error('Something broke'));
 }
 
-// 2. In your test:
-async function testGreeting() {
-  const vc = new VirtualConsole();
+async function test() {
+	const vc = new VirtualConsole();
 
-  // 3. Run the function inside the hook to capture its output.
-  // All `console.*` calls inside `greet` are now routed to `vc`.
-  await vc.hookAsyncContext(() => greet('World'));
+	// Run inside the hook. All console calls are routed to 'vc'.
+	await vc.hookAsyncContext(() => greet('World'));
 
-  // 4. Assert the captured output
-  const expectedOutput = 'Hello, World!\nAn example error.\n';
-  assert.strictEqual(vc.outputs, expectedOutput);
-  console.log('Test passed!');
+	assert.ok(vc.outputs.includes('Hello, World!'));
+	assert.ok(vc.outputs.includes('Error: Something broke'));
 }
 
-testGreeting();
+test();
 ```
 
-## Advanced Usage
-
-### Use Case: Concurrent Progress Bars with `freshLine`
+### 2. Generating HTML Output for Web UIs
 
-This example demonstrates the power of async context isolation. We run two progress updates concurrently. Each `hookAsyncContext` creates an isolated "session," ensuring that each `console.freshLine` call updates its own line without interfering with the other.
+One of the most powerful features is `outputsHtml`, which converts console formatting to valid HTML string.
 
 ```javascript
 import { VirtualConsole } from '@steve02081504/virtual-console';
 
-const vc = new VirtualConsole({ realConsoleOutput: true });
+const vc = new VirtualConsole();
 
-async function updateProgress(taskName, duration) {
-  for (let i = 0; i <= 100; i += 20) {
-    // `console.freshLine` is a stateful method. It works correctly here
-    // because each task has its own isolated VirtualConsole state.
-    console.freshLine(taskName, `[${taskName}]: ${i}%`);
-    await new Promise(res => setTimeout(res, duration));
-  }
-  console.log(`[${taskName}]: Done!`);
-}
+await vc.hookAsyncContext(() => {
+	// ANSI Colors (Node.js style)
+	console.log('\x1b[31mRed Text\x1b[0m');
+
+	// CSS Styling (Browser style - %c)
+	console.log('%cBig Blue Text', 'color: blue; font-size: 20px');
+	
+	// Objects
+	console.log({ foo: 'bar' });
+});
 
-console.log('Starting concurrent tasks...');
+// Get the captured output as HTML
+const html = vc.outputsHtml;
 
-// Run two tasks, each in its own isolated hook.
-// Without this isolation, they would conflict and corrupt the output.
-await Promise.all([
-  vc.hookAsyncContext(() => updateProgress('Upload-A', 50)),
-  vc.hookAsyncContext(() => updateProgress('Process-B', 75)),
-]);
-
-console.log('All tasks finished!');
+// Result example:
+// <span style="color:rgb(170,0,0)">Red Text</span>
+// <span style="color: blue; font-size: 20px">Big Blue Text</span>
+// ...
 ```
 
-### Use Case: Custom Error Handling
+### 3. Concurrent Tasks (Node.js)
 
-You can provide a dedicated `error_handler` to process `Error` objects passed to `console.error`. This is useful for integrating with logging services or custom error-reporting frameworks.
+In Node.js, `VirtualConsole` uses `AsyncLocalStorage` to ensure logs from concurrent tasks don't mix.
 
 ```javascript
 import { VirtualConsole } from '@steve02081504/virtual-console';
 
-const reportedErrors = [];
-
-const vc = new VirtualConsole({
-  // This handler is called ONLY when a single Error object is passed to console.error
-  error_handler: (err) => {
-    console.log(`Reporting error: "${err.message}"`);
-    reportedErrors.push(err);
-  },
-  realConsoleOutput: true,
-});
+const vc = new VirtualConsole({ realConsoleOutput: true });
 
-await vc.hookAsyncContext(() => {
-  console.error(new Error('Something went wrong!')); // Handled by error_handler
-  console.error('A regular error message.'); // Not an Error object, logged normally
-});
+async function work(id, duration) {
+	console.log(`Starting task ${id}`); // Captured by the specific context
+	await new Promise(r => setTimeout(r, duration));
+	console.log(`Finished task ${id}`);
+}
 
-// Verify the custom handler was called
-console.log('Reported errors:', reportedErrors.map(e => e.message));
+await Promise.all([
+	vc.hookAsyncContext(() => work('A', 100)), // Captured in context A
+	vc.hookAsyncContext(() => work('B', 50)),  // Captured in context B
+]);
 ```
 
 ## API Reference
@@ -145,46 +116,57 @@ console.log('Reported errors:', reportedErrors.map(e => e.message));
 Creates a new `VirtualConsole` instance.
 
 - `options` `<object>`
-  - `realConsoleOutput` `<boolean>`: If `true`, output is also sent to the base console. **Default:** `false`.
-  - `recordOutput` `<boolean>`: If `true`, output is captured in the `outputs` property. **Default:** `true`.
-  - `base_console` `<Console>`: The console instance for passthrough. **Default:** The original `global.console` before it was patched.
-  - `error_handler` `<function(Error): void>`: A dedicated handler for `Error` objects passed to `console.error`. If `console.error` is called with a single argument that is an `instanceof Error`, this handler is invoked instead of the standard `console.error` logic. **Default:** `null`.
-  - `supportsAnsi` `<boolean>`: Manually set ANSI support, which affects `freshLine`. **Default:** Inherited from `base_console`'s stream, or the result of the `supports-ansi` package.
+  - `realConsoleOutput` `<boolean>`: If `true`, output is also sent to the base (real) console. **Default:** `false`.
+  - `recordOutput` `<boolean>`: If `true`, output is captured in `outputs` and `outputsHtml`. **Default:** `true`.
+  - `base_console` `<Console>`: The console instance to pass through to.
+  - `error_handler` `<function(Error): void>`: specific handler for `console.error(err)`.
+  - `supportsAnsi` `<boolean>`: Force enable/disable ANSI support (affects `freshLine`).
 
 ### `virtualConsole.hookAsyncContext(fn?)`
 
-Hooks the virtual console into an asynchronous context.
-
-- **`hookAsyncContext(fn)`**: Runs `fn` in a new context. All `console` calls within `fn` (and any functions it `await`s) are routed to this instance. Returns a `Promise` that resolves with the return value of `fn`.
-- **`hookAsyncContext()`**: Activates the instance for the *current* asynchronous context. Useful for "activating" a console and leaving it active for the remainder of an async flow (e.g., within middleware).
+Hooks the virtual console into the current execution context.
 
-### `virtualConsole.outputs`
+- **`hookAsyncContext(fn)`**: Runs `fn` and routes all `console.*` calls inside it to this instance. Returns a `Promise` with the result of `fn`.
+- **`hookAsyncContext()`**: (Advanced) Manually sets this instance as the active console for the current context.
 
-- `<string>`
+### Properties
 
-A string containing all captured `stdout` and `stderr` output.
+- **`vc.outputs`** `<string>`: Captured raw text output (includes ANSI codes in Node.js).
+- **`vc.outputsHtml`** `<string>`: Captured output converted to HTML strings. Handles ANSI codes and `%c` styling.
 
-### `console.freshLine(id, ...args)`
+### Methods
 
-*Note: This stateful method is available on the global `console` object but only works as intended inside a `hookAsyncContext`.*
+- **`console.freshLine(id, ...args)`**:
+  Prints a line that can be overwritten by subsequent calls with the same `id`. Useful for progress bars.
+  - *Node.js:* Uses ANSI cursor movements.
+  - *Browser:* Simulates behavior (appends new lines).
+- **`vc.clear()`**: Clears `outputs` and `outputsHtml`.
+- **`vc.error(err)`**: Custom error handling if configured.
 
-Prints a line. If the previously printed line (within the same hook) had the same `id`, it overwrites the previous line using ANSI escape codes. This requires a TTY environment.
+## Platform Differences
 
-- `id` `<string>`: A unique identifier for the overwritable line.
-- `...args` `<any>`: The content to print, same as `console.log()`.
+### Node.js
 
-### `virtualConsole.clear()`
+- Implementation relies on `node:async_hooks` (`AsyncLocalStorage`).
+- Context isolation works perfectly even across `setTimeout`, `Promise`, and other async boundaries.
+- `freshLine` supports real terminal cursor manipulation.
 
-Clears the captured `outputs` string. If `realConsoleOutput` is enabled, it also attempts to call `clear()` on the base console.
+### Browser
 
-### `virtualConsole.error(...args)`
+- Implementation relies on a global variable stack strategy.
+- **Scope Limitation:** `hookAsyncContext(fn)` works for the duration of the function execution. However, strict "async" context propagation (like passing context into a `setTimeout` callback) is mimicked but may not be as robust as Node.js's native hooks.
+- `freshLine` cannot erase previous lines in the real browser console limitations, so it appends logs instead.
 
-The standard `console.error` method. However, if an `error_handler` is configured in the constructor, and `error()` is called with a single argument that is an `instanceof Error`, the handler will be invoked with the error object.
+## Integration for Library Authors
 
-## For Library Authors: `setGlobalConsoleReflect(...)`
+If you are building a library that manages its own async contexts, you can synchronize with `VirtualConsole` using:
 
-`VirtualConsole` exposes its `AsyncLocalStorage`-based reflection mechanism. If you are building another library that also manages async context (e.g., a custom APM or transaction tracer), you can use `setGlobalConsoleReflect` to integrate `VirtualConsole`'s logic into your own context manager. This prevents the two libraries from fighting over control of the async context. See the source code for details on its function signature.
-
-## Contributing
+```javascript
+import { setGlobalConsoleReflect } from '@steve02081504/virtual-console';
 
-Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/steve02081504/virtual-console).
+setGlobalConsoleReflect(
+	(defaultConsole) => { /* return active console */ },
+	(consoleInstance) => { /* set active console */ },
+	(consoleInstance, fn) => { /* run fn in context */ }
+);
+```

package/browser.mjs

@@ -1,5 +1,7 @@
 import { FullProxy } from 'full-proxy'
 
+import { argsToHtml } from './util.mjs'
+
 /**
  * 存储原始的浏览器 console 对象。
  */
@@ -11,24 +13,85 @@ const originalConsole = window.console
  * @returns {string} 格式化后的单行字符串。
  */
 function formatArgs(args) {
-	return args.map(arg => {
-		if (Object(arg) instanceof String) return arg
-		if (arg instanceof Error && arg.stack) return arg.stack
-		try {
-			return JSON.stringify(arg, null, '\t')
+	if (args.length === 0) return ''
+	const format = args[0]
+	if (format?.constructor !== String)
+		return args.map(arg => {
+			if (Object(arg) instanceof String) return arg
+			if (arg instanceof Error && arg.stack) return arg.stack
+			try {
+				return JSON.stringify(arg, null, '\t')
+			}
+			catch {
+				return String(arg)
+			}
+		}).join(' ')
+
+	let output = ''
+	let argIndex = 1
+	let lastIndex = 0
+	const regex = /%[sdifoOc%]/g
+	let match
+
+	while ((match = regex.exec(format)) !== null) {
+		output += format.slice(lastIndex, match.index)
+		lastIndex = regex.lastIndex
+
+		if (match[0] === '%%') {
+			output += '%'
+			continue
 		}
-		catch {
-			return String(arg)
+
+		if (argIndex >= args.length) {
+			output += match[0]
+			continue
+		}
+
+		const arg = args[argIndex++]
+		switch (match[0]) {
+			case '%c':
+				break
+			case '%s':
+				output += String(arg)
+				break
+			case '%d':
+			case '%i':
+				output += String(parseInt(arg))
+				break
+			case '%f':
+				output += String(parseFloat(arg))
+				break
+			case '%o':
+			case '%O':
+				try { output += JSON.stringify(arg, null, '\t') }
+				catch { output += String(arg) }
+				break
 		}
-	}).join(' ')
+	}
+	output += format.slice(lastIndex)
+
+	while (argIndex < args.length) {
+		const arg = args[argIndex++]
+		if (output) output += ' '
+		if (arg instanceof Error && arg.stack) output += arg.stack
+		else if ((arg === null || arg instanceof Object) && !(arg instanceof Function))
+			try { output += JSON.stringify(arg, null, '\t') }
+			catch { output += String(arg) }
+
+		else output += String(arg)
+	}
+
+	return output
 }
 
 /**
- * 创建一个虚拟控制台，用于捕获输出，同时可以选择性地将输出传递给真实的浏览器控制台。
+ * 创建一个虚拟控制台，用于捕获输出，同时可以选择性地将输出传递给真实的控制台。
  */
 export class VirtualConsole {
 	/** @type {string} - 捕获的所有输出 */
 	outputs = ''
+	/** @type {string} - 捕获的所有输出 (HTML) */
+	outputsHtml = ''
 
 	/** @type {object} - 最终合并后的配置项 */
 	options
@@ -43,6 +106,7 @@ export class VirtualConsole {
 	 * @param {object} [options={}] - 配置选项。
 	 * @param {boolean} [options.realConsoleOutput=false] - 如果为 true，则在捕获输出的同时，也调用底层控制台进行实际输出。
 	 * @param {boolean} [options.recordOutput=true] - 如果为 true，则捕获输出并保存在 outputs 属性中。
+	 * @param {function(Error): void} [options.error_handler=null] - 一个专门处理单个 Error 对象的错误处理器。
 	 * @param {Console} [options.base_console=window.console] - 用于 realConsoleOutput 的底层控制台实例。
 	 */
 	constructor(options = {}) {
@@ -52,25 +116,32 @@ export class VirtualConsole {
 		this.options = {
 			realConsoleOutput: false,
 			recordOutput: true,
+			error_handler: null,
 			...options,
 		}
 
 		const methods = ['log', 'info', 'warn', 'debug', 'error', 'table', 'dir', 'assert', 'count', 'countReset', 'time', 'timeLog', 'timeEnd', 'group', 'groupCollapsed', 'groupEnd']
 		for (const method of methods)
-			if (typeof this.#base_console[method] === 'function')
+			if (this.#base_console[method] instanceof Function)
+				/**
+				 * 重写控制台方法
+				 * @param {...any} args - 控制台方法的参数。
+				 * @returns {void}
+				 */
 				this[method] = (...args) => {
+					if (method == 'error' && this.options.error_handler && args.length === 1 && args[0] instanceof Error) return this.options.error_handler(args[0])
 					this.#loggedFreshLineId = null // 任何常规输出都会中断 freshLine 序列
 
-					if (this.options.recordOutput)
+					if (this.options.recordOutput) {
 						this.outputs += formatArgs(args) + '\n'
+						this.outputsHtml += argsToHtml(args) + '<br/>\n'
+					}
 
 					// 实际输出
 					if (this.options.realConsoleOutput)
 						this.#base_console[method](...args)
 				}
 
-
-
 		this.freshLine = this.freshLine.bind(this)
 		this.clear = this.clear.bind(this)
 	}
@@ -92,8 +163,9 @@ export class VirtualConsole {
 	/**
 	 * 若提供fn，则在新的异步上下文中执行fn，并将fn上下文的控制台替换为此对象。
 	 * 否则，将当前异步上下文中的控制台替换为此对象。
-	 * @param {(() => T | Promise<T>) | undefined} [fn]
-	 * @returns {Promise<T> | void}
+	 * @template T - fn 函数的返回类型。
+	 * @param {(() => T | Promise<T>) | undefined} [fn] - 在新的异步上下文中执行的函数。
+	 * @returns {Promise<T> | void} 若提供fn，则返回 fn 函数的 Promise 结果；否则返回void。
 	 */
 	hookAsyncContext(fn) {
 		if (fn) return consoleReflectRun(this, fn)
@@ -118,23 +190,31 @@ export class VirtualConsole {
 	}
 
 	/**
-	 * 清空捕获的输出，并可以选择性地清空真实控制台。
+	 * 清空捕获的输出，并选择性地清空真实控制台。
+	 * @returns {void}
 	 */
 	clear() {
 		this.#loggedFreshLineId = null
 		this.outputs = ''
+		this.outputsHtml = ''
 		if (this.options.realConsoleOutput)
 			this.#base_console.clear()
 
 	}
 }
 
+/**
+ * 默认的全局虚拟控制台实例。
+ */
 export const defaultConsole = new VirtualConsole({
 	base_console: originalConsole,
 	recordOutput: false,
 	realConsoleOutput: true,
 })
 
+/**
+ * 全局控制台的附加属性。
+ */
 export const globalConsoleAdditionalProperties = {}
 
 // 模拟 AsyncLocalStorage 的上下文存储
@@ -149,7 +229,7 @@ let consoleReflectSet = (v) => {
 }
 
 /**
- * @template T
+ * @template T - fn 函数的返回类型
  * @type {(value: VirtualConsole, fn: () => T | Promise<T>) => Promise<T>}
  */
 let consoleReflectRun = async (v, fn) => {
@@ -165,11 +245,27 @@ let consoleReflectRun = async (v, fn) => {
 }
 
 // 暴露设置和获取反射逻辑的函数，以完全匹配原始API
+/**
+ * 设置全局控制台反射逻辑
+ * @template T - fn 函数的返回类型
+ * @param {(console: Console) => Console} Reflect 将 console 参数映射到新的 console 对象的函数。
+ * @param {(console: Console) => void} ReflectSet 设置当前 console 对象的函数。
+ * @param {(console: Console, fn: () => T) => Promise<T>} ReflectRun  在新的异步上下文中执行函数的函数。
+ * @returns {void}
+ */
 export function setGlobalConsoleReflect(Reflect, ReflectSet, ReflectRun) {
+	/**
+	 * 从默认控制台获取当前控制台对象。
+	 * @returns {Console} 当前控制台对象。
+	 */
 	consoleReflect = () => Reflect(defaultConsole)
 	consoleReflectSet = ReflectSet
 	consoleReflectRun = ReflectRun
 }
+/**
+ * 获取全局控制台反射逻辑。
+ * @returns {object} 包含 Reflect、ReflectSet 和 ReflectRun 函数的对象。
+ */
 export function getGlobalConsoleReflect() {
 	return {
 		Reflect: consoleReflect,
@@ -183,6 +279,13 @@ export function getGlobalConsoleReflect() {
  * 这与原始 Node.js 版本的实现完全相同。
  */
 export const console = globalThis.console = new FullProxy(() => Object.assign({}, globalConsoleAdditionalProperties, consoleReflect()), {
+	/**
+	 * 设置属性时的处理逻辑。
+	 * @param {object} target - 目标对象。
+	 * @param {string | symbol} property - 要设置的属性名。
+	 * @param {any} value - 要设置的属性值。
+	 * @returns {boolean} 指示属性是否成功设置的布尔值。
+	 */
 	set: (target, property, value) => {
 		target = consoleReflect()
 		if (property in target) return Reflect.set(target, property, value)

package/main.mjs

@@ -1,9 +1,30 @@
 const module = await import(globalThis.document ? './browser.mjs' : './node.mjs')
 
+/**
+ * @type {AsyncLocalStorage}
+ */
 export const consoleAsyncStorage = module.consoleAsyncStorage
+/**
+ * @type {typeof VirtualConsole}
+ */
 export const VirtualConsole = module.VirtualConsole
+/**
+ * @type {VirtualConsole}
+ */
 export const defaultConsole = module.defaultConsole
+/**
+ * @type {object}
+ */
 export const globalConsoleAdditionalProperties = module.globalConsoleAdditionalProperties
+/**
+ * @type {function}
+ */
 export const setGlobalConsoleReflect = module.setGlobalConsoleReflect
+/**
+ * @type {function}
+ */
 export const getGlobalConsoleReflect = module.getGlobalConsoleReflect
+/**
+ * @type {VirtualConsole}
+ */
 export const console = module.console

package/node.mjs

@@ -7,6 +7,11 @@ import ansiEscapes from 'ansi-escapes'
 import { FullProxy } from 'full-proxy'
 import supportsAnsi from 'supports-ansi'
 
+import { argsToHtml } from './util.mjs'
+
+/**
+ * 全局异步存储，用于管理控制台上下文。
+ */
 export const consoleAsyncStorage = new AsyncLocalStorage()
 const cleanupRegistry = new FinalizationRegistry(cleanupToken => {
 	const { stream, listener } = cleanupToken
@@ -15,27 +20,28 @@ const cleanupRegistry = new FinalizationRegistry(cleanupToken => {
 
 /**
  * 创建一个虚拟控制台，用于捕获输出，同时可以选择性地将输出传递给真实的控制台。
- *
- * @extends {Console}
+ * @augments {Console}
  */
 export class VirtualConsole extends Console {
 	/**
-	 * 在新的Async上下文中执行fn，并将fn上下文的控制台替换为此对象。
+	 * 在新的异步上下文中执行fn，并将该上下文的控制台替换为此对象。
+	 * 这是通过 Node.js 的 AsyncLocalStorage 实现的。
 	 * @template T
 	 * @overload
-	 * @param {() => T} fn - 在新的Async上下文中执行的函数。
+	 * @param {() => T | Promise<T>} fn - 在新的异步上下文中执行的函数。
 	 * @returns {Promise<T>} 返回 fn 函数的 Promise 结果。
 	 */
 	/**
-	 * 将当前Async上下文中的控制台替换为此对象。
+	 * 将当前“异步上下文”中的控制台替换为此对象。
 	 * @overload
 	 * @returns {void}
 	 */
 	/**
-	 * 若提供fn，则在新的Async上下文中执行fn，并将fn上下文的控制台替换为此对象。
-	 * 否则，将当前Async上下文中的控制台替换为此对象。
-	 * @param {(() => T) | undefined} [fn]
-	 * @returns {Promise<T> | void}
+	 * 若提供fn，则在新的异步上下文中执行fn，并将fn上下文的控制台替换为此对象。
+	 * 否则，将当前异步上下文中的控制台替换为此对象。
+	 * @template T - fn 函数的返回类型。
+	 * @param {(() => T | Promise<T>) | undefined} [fn] - 在新的异步上下文中执行的函数。
+	 * @returns {Promise<T> | void} 若提供fn，则返回 fn 函数的 Promise 结果；否则返回void。
 	 */
 	hookAsyncContext(fn) {
 		if (fn) return consoleReflectRun(this, fn)
@@ -43,6 +49,8 @@ export class VirtualConsole extends Console {
 	}
 	/** @type {string} - 捕获的所有输出 */
 	outputs = ''
+	/** @type {string} - 捕获的所有输出 (HTML) */
+	outputsHtml = ''
 
 	/** @type {object} - 最终合并后的配置项 */
 	options
@@ -57,11 +65,12 @@ export class VirtualConsole extends Console {
 	 * @param {object} [options={}] - 配置选项。
 	 * @param {boolean} [options.realConsoleOutput=false] - 如果为 true，则在捕获输出的同时，也调用底层控制台进行实际输出。
 	 * @param {boolean} [options.recordOutput=true] - 如果为 true，则捕获输出并保存在 outputs 属性中。
+	 * @param {boolean} [options.supportsAnsi] - 如果为 true, 则启用 ANSI 转义序列支持。
 	 * @param {function(Error): void} [options.error_handler=null] - 一个专门处理单个 Error 对象的错误处理器。
 	 * @param {Console} [options.base_console=console] - 用于 realConsoleOutput 的底层控制台实例。
 	 */
 	constructor(options = {}) {
-		super(new Writable({ write: () => { } }), new Writable({ write: () => { } }))
+		super(new Writable({ /** 啥也不干  */ write: () => { } }), new Writable({ /** 啥也不干  */ write: () => { } }))
 
 		this.base_console = options.base_console || consoleReflect()
 		delete options.base_console
@@ -77,8 +86,14 @@ export class VirtualConsole extends Console {
 		for (const method of ['log', 'info', 'warn', 'debug', 'error']) {
 			if (!this[method]) continue
 			const originalMethod = this[method]
+			/**
+			 * 将控制台方法重写为捕获输出并根据配置决定是否传递给底层控制台。
+			 * @param {...any} args - 控制台方法的参数。
+			 * @returns {void}
+			 */
 			this[method] = (...args) => {
 				if (method == 'error' && this.options.error_handler && args.length === 1 && args[0] instanceof Error) return this.options.error_handler(args[0])
+				if (this.options.recordOutput) this.outputsHtml += argsToHtml(args) + '<br/>\n'
 				if (!this.options.realConsoleOutput || this.options.recordOutput) return originalMethod.apply(this, args)
 				this.#loggedFreshLineId = null
 				return this.#base_console[method](...args)
@@ -86,15 +101,35 @@ export class VirtualConsole extends Console {
 		}
 	}
 
+	/**
+	 * 获取用于 realConsoleOutput 的底层控制台实例。
+	 * @returns {Console} 底层控制台实例。
+	 */
 	get base_console() {
 		return this.#base_console
 	}
 
+	/**
+	 * 设置用于 realConsoleOutput 的底层控制台实例。
+	 * @param {Console} value - 底层控制台实例。
+	 * @returns {void}
+	 */
 	set base_console(value) {
 		this.#base_console = value
 
+		/**
+		 * 创建一个虚拟的控制台流，用于捕获输出。
+		 * @param {NodeJS.WritableStream} targetStream - 目标流。
+		 * @returns {NodeJS.WritableStream} 虚拟流。
+		 */
 		const createVirtualStream = (targetStream) => {
 			const virtualStream = new Writable({
+				/**
+				 * 写入数据到虚拟流。
+				 * @param {Buffer | string} chunk - 要写入的数据块。
+				 * @param {string} encoding - 编码格式。
+				 * @param {() => void} callback - 写入完成的回调函数。
+				 */
 				write: (chunk, encoding, callback) => {
 					this.#loggedFreshLineId = null
 
@@ -110,14 +145,42 @@ export class VirtualConsole extends Console {
 			if (targetStream.isTTY) {
 				Object.defineProperties(virtualStream, {
 					isTTY: { value: true, configurable: true, writable: false, enumerable: true },
-					columns: { get: () => targetStream.columns, configurable: true, enumerable: true },
-					rows: { get: () => targetStream.rows, configurable: true, enumerable: true },
-					getColorDepth: { get: () => targetStream.getColorDepth.bind(targetStream), configurable: true, enumerable: true },
-					hasColors: { get: () => targetStream.hasColors.bind(targetStream), configurable: true, enumerable: true },
+					columns: {
+						/**
+						 * 获取目标流的列数
+						 * @returns {number} 列数
+						 */
+						get: () => targetStream.columns, configurable: true, enumerable: true
+					},
+					rows: {
+						/**
+						 * 获取目标流的行数
+						 * @returns {number} 行数
+						 */
+						get: () => targetStream.rows, configurable: true, enumerable: true
+					},
+					getColorDepth: {
+						/**
+						 * 获取目标流的颜色深度
+						 * @returns {number} 颜色深度
+						 */
+						get: () => targetStream.getColorDepth.bind(targetStream), configurable: true, enumerable: true
+					},
+					hasColors: {
+						/**
+						 * 判断目标流是否支持颜色
+						 * @returns {boolean} 是否支持颜色
+						 */
+						get: () => targetStream.hasColors.bind(targetStream), configurable: true, enumerable: true
+					},
 				})
 
 				const virtualStreamRef = new WeakRef(virtualStream)
 
+				/**
+				 * 监听目标流的 resize 事件，并在虚拟流上触发相应的事件。
+				 * @returns {void}
+				 */
 				const resizeListener = () => {
 					virtualStreamRef.deref()?.emit('resize')
 				}
@@ -151,35 +214,58 @@ export class VirtualConsole extends Console {
 		this.#loggedFreshLineId = id
 	}
 
+	/**
+	 * 清空捕获的输出，并选择性地清空真实控制台。
+	 * @returns {void}
+	 */
 	clear() {
 		this.#loggedFreshLineId = null
 		this.outputs = ''
+		this.outputsHtml = ''
 		if (this.options.realConsoleOutput)
 			this.#base_console.clear()
 	}
 }
 
 const originalConsole = globalThis.console
+/**
+ * 默认的虚拟控制台实例。
+ */
 export const defaultConsole = new VirtualConsole({ base_console: originalConsole, recordOutput: false, realConsoleOutput: true })
+/**
+ * 全局控制台的附加属性。
+ */
 export const globalConsoleAdditionalProperties = {}
 /** @type {() => VirtualConsole} */
 let consoleReflect = () => consoleAsyncStorage.getStore() ?? defaultConsole
 /** @type {(value: VirtualConsole) => void} */
 let consoleReflectSet = (v) => consoleAsyncStorage.enterWith(v)
-/** @type {(value: VirtualConsole, fn: () => T) => Promise<T>} */
+/**
+ * @template T - fn 函数的返回类型
+ * @type {(value: VirtualConsole, fn: () => T) => Promise<T>}
+ */
 let consoleReflectRun = (v, fn) => consoleAsyncStorage.run(v, fn)
 /**
  * 设置全局控制台反射逻辑
- * @template T
- * @param {(console: Console) => Console} Reflect
- * @param {(value: Console) => void} ReflectSet
- * @param {(value: Console, fn: () => T) => Promise<T>} ReflectRun
+ * @template T - fn 函数的返回类型
+ * @param {(console: Console) => Console} Reflect 从默认控制台映射到新的控制台对象的函数。
+ * @param {(value: Console) => void} ReflectSet 设置当前控制台对象的函数。
+ * @param {(value: Console, fn: () => T) => Promise<T>} ReflectRun 在新的异步上下文中执行函数的函数。
+ * @returns {void}
  */
 export function setGlobalConsoleReflect(Reflect, ReflectSet, ReflectRun) {
+	/**
+	 * 从默认控制台获取当前控制台对象。
+	 * @returns {Console} 当前控制台对象。
+	 */
 	consoleReflect = () => Reflect(defaultConsole)
 	consoleReflectSet = ReflectSet
 	consoleReflectRun = ReflectRun
 }
+/**
+ * 获取全局控制台反射逻辑
+ * @returns {object} 包含 Reflect、ReflectSet 和 ReflectRun 函数的对象。
+ */
 export function getGlobalConsoleReflect() {
 	return {
 		Reflect: consoleReflect,
@@ -187,7 +273,17 @@ export function getGlobalConsoleReflect() {
 		ReflectRun: consoleReflectRun
 	}
 }
+/**
+ * 全局控制台实例。
+ */
 export const console = globalThis.console = new FullProxy(() => Object.assign({}, globalConsoleAdditionalProperties, consoleReflect()), {
+	/**
+	 * 设置属性时的处理逻辑。
+	 * @param {object} target - 目标对象。
+	 * @param {string | symbol} property - 要设置的属性名。
+	 * @param {any} value - 要设置的属性值。
+	 * @returns {any} 属性值。
+	 */
 	set: (target, property, value) => {
 		target = consoleReflect()
 		if (property in target) return Reflect.set(target, property, value)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/virtual-console",
-	"version": "0.0.8",
+	"version": "0.1.1",
 	"description": "A virtual console for capturing and manipulating terminal output.",
 	"main": "main.mjs",
 	"type": "module",
@@ -19,6 +19,7 @@
 	"dependencies": {
 		"ansi-escapes": "latest",
 		"full-proxy": "latest",
-		"supports-ansi": "latest"
+		"supports-ansi": "latest",
+		"ansi_up": "latest"
 	}
 }

package/util.mjs

@@ -0,0 +1,78 @@
+import { AnsiUp } from 'ansi_up'
+
+const ansi_up = new AnsiUp()
+
+/**
+ * 将 console 参数格式化为 HTML 字符串。
+ * @param {any[]} args - console 方法接收的参数数组。
+ * @returns {string} 格式化后的 HTML 字符串。
+ */
+export function argsToHtml(args) {
+	if (args.length === 0) return ''
+	const format = args[0]
+	if (format?.constructor !== String)
+		return args.map(arg => {
+			if (arg instanceof Error && arg.stack) return ansi_up.ansi_to_html(arg.stack)
+			if ((arg === null || arg instanceof Object) && !(arg instanceof Function))
+				try { return ansi_up.ansi_to_html(JSON.stringify(arg, null, '\t')) }
+				catch { return String(arg) }
+
+			return ansi_up.ansi_to_html(String(arg))
+		}).join(' ')
+
+
+	let html = ansi_up.ansi_to_html(format)
+	let argIndex = 1
+	let hasStyle = false
+
+	const regex = /%[sdifoOc%]/g
+	html = html.replace(regex, (match) => {
+		if (match === '%%') return '%'
+		if (argIndex >= args.length) return match
+
+		const arg = args[argIndex++]
+		switch (match) {
+			case '%c': {
+				hasStyle = true
+				const style = String(arg)
+				return `</span><span style="${style}">`
+			}
+			case '%s':
+				return ansi_up.ansi_to_html(String(arg))
+			case '%d':
+			case '%i':
+				return String(parseInt(arg))
+			case '%f':
+				return String(parseFloat(arg))
+			case '%o':
+			case '%O':
+				try { return ansi_up.ansi_to_html(JSON.stringify(arg)) }
+				catch { return String(arg) }
+		}
+		return match
+	})
+
+	if (hasStyle) html = `<span>${html}</span>`
+
+	const replaceTable = {
+		'<span style="">': '<span>',
+		'<span></span>': '',
+	}
+
+	Object.entries(replaceTable).forEach(([key, value]) => {
+		html = html.replaceAll(key, value)
+	})
+
+	while (argIndex < args.length) {
+		const arg = args[argIndex++]
+		html += ' '
+		if (arg instanceof Error && arg.stack) html += ansi_up.ansi_to_html(arg.stack)
+		else if ((arg === null || arg instanceof Object) && !(arg instanceof Function))
+			try { html += ansi_up.ansi_to_html(JSON.stringify(arg, null, '\t')) }
+			catch { html += String(arg) }
+
+		else html += ansi_up.ansi_to_html(String(arg))
+	}
+
+	return html
+}