@effect-tui/core 0.1.0 → 0.1.4

package/package.json

@@ -1,57 +1,57 @@
 {
-  "name": "@effect-tui/core",
-  "version": "0.1.0",
-  "description": "Terminal UI library built with Effect",
-  "type": "module",
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kitlangton/effect-tui.git"
-  },
-  "homepage": "https://github.com/kitlangton/effect-tui",
-  "bugs": "https://github.com/kitlangton/effect-tui/issues",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "types": "./dist/index.d.ts",
-  "keywords": [
-    "terminal",
-    "tui",
-    "effect",
-    "cli",
-    "console"
-  ],
-  "author": "Kit Langton",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
-  },
-  "scripts": {
-    "build": "tsc -p .",
-    "typecheck": "tsc -p . --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "format": "biome format --write .",
-    "format:check": "biome format .",
-    "prepublishOnly": "bun run typecheck && bun run build"
-  },
-  "peerDependencies": {
-    "effect": "^3.0.0"
-  },
-  "devDependencies": {
-    "@effect/vitest": "^0.27.0",
-    "@types/node": "^24.10.1",
-    "effect": "^3.19.8",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.14"
-  }
+	"name": "@effect-tui/core",
+	"version": "0.1.4",
+	"description": "Terminal UI library built with Effect",
+	"type": "module",
+	"files": [
+		"dist",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/kitlangton/effect-tui.git"
+	},
+	"homepage": "https://github.com/kitlangton/effect-tui",
+	"bugs": "https://github.com/kitlangton/effect-tui/issues",
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"types": "./dist/index.d.ts",
+	"keywords": [
+		"terminal",
+		"tui",
+		"effect",
+		"cli",
+		"console"
+	],
+	"author": "Kit Langton",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc -p .",
+		"typecheck": "tsc -p . --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"format": "biome format --write .",
+		"format:check": "biome format .",
+		"prepublishOnly": "bun run typecheck && bun run build"
+	},
+	"peerDependencies": {
+		"effect": "^3.19.13"
+	},
+	"devDependencies": {
+		"@effect/vitest": "^0.27.0",
+		"@types/node": "^25.0.3",
+		"effect": "^3.19.13",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.16"
+	}
 }

package/src/ansi.ts

@@ -1,83 +1,211 @@
-// ANSI escape sequences and terminal control utilities
+// ansi.ts — ANSI escape sequences for terminal control
 
 /** CSI prefix (ESC [) */
 const CSI = "\x1b["
 
-/** Basic ANSI codes and helpers */
+/** ANSI escape sequence primitives */
 export const ANSI = {
-  /** Reset all attributes */
-  reset: `${CSI}0m`,
-
-  /** Cursor control */
-  cursor: {
-    /** Hide cursor */
-    hide: `${CSI}?25l`,
-    /** Show cursor */
-    show: `${CSI}?25h`,
-    /** Move cursor to home position (1,1) */
-    home: `${CSI}H`,
-    /** Move cursor to 1-based row/column */
-    to: (row1: number, col1: number) => `${CSI}${row1};${col1}H`,
-    /** Move cursor to 1-based column on current row */
-    toCol: (col1: number) => `${CSI}${col1}G`,
-  },
-
-  /** Screen control */
-  screen: {
-    /** Enter alternate screen buffer */
-    altEnter: `${CSI}?1049h`,
-    /** Exit alternate screen buffer */
-    altExit: `${CSI}?1049l`,
-    /** Clear entire display */
-    clear: `${CSI}2J`,
-    /** Clear scrollback buffer */
-    clearScrollback: `${CSI}3J`,
-  },
-
-  /** Scrolling */
-  scroll: {
-    /** Scroll up by n lines */
-    up: (n: number) => `${CSI}${n}S`,
-  },
-
-  /** Device Status Reports / queries */
-  report: {
-    /** Report Cursor Position (response: ESC [ row ; col R) */
-    cursorPosition: `${CSI}6n`,
-  },
-
-  /** Bracketed paste mode */
-  paste: {
-    bracketed: {
-      on: `${CSI}?2004h`,
-      off: `${CSI}?2004l`,
-    },
-  },
-
-  /** Mouse reporting toggles */
-  mouse: {
-    /** Enable button tracking and SGR coordinates */
-    on: `${CSI}?1002h${CSI}?1006h`,
-    /** Disable SGR coords and button tracking */
-    off: `${CSI}?1006l${CSI}?1002l`,
-  },
-} as const
+	/** Cursor control */
+	cursor: {
+		/** Move cursor to 1-based row/column position */
+		to: (x: number, y: number) => `${CSI}${y};${x}H`,
+		/** Move cursor to 1-based column on current row */
+		toCol: (col: number) => `${CSI}${col}G`,
+		/** Move cursor up by n rows */
+		up: (n: number) => (n > 0 ? `${CSI}${n}A` : ""),
+		/** Move cursor down by n rows */
+		down: (n: number) => (n > 0 ? `${CSI}${n}B` : ""),
+		/** Hide cursor */
+		hide: `${CSI}?25l`,
+		/** Show cursor */
+		show: `${CSI}?25h`,
+		/** Move cursor to start of current line */
+		startOfLine: "\r",
+		/** Move cursor to home position (1,1) */
+		home: `${CSI}H`,
+	},
 
-/** Terminal session control utilities (compositions of ANSI primitives) */
-export const Terminal = {
-  /** Enter full-screen mode: alternate screen + hide cursor */
-  enterFullscreen: ANSI.screen.altEnter + ANSI.cursor.hide,
+	/** Line control */
+	line: {
+		/** Clear entire line */
+		clear: `${CSI}2K`,
+		/** Clear from cursor to end of line */
+		clearToEnd: `${CSI}0K`,
+	},
+
+	/** Screen control */
+	screen: {
+		/** Enter alternate screen buffer */
+		enterAlt: `${CSI}?1049h`,
+		/** Exit alternate screen buffer */
+		exitAlt: `${CSI}?1049l`,
+		/** Clear entire screen */
+		clear: `${CSI}2J`,
+		/** Clear from cursor to end of screen */
+		clearToEnd: `${CSI}J`,
+		/** Clear scrollback buffer */
+		clearScrollback: `${CSI}3J`,
+	},
+
+	/** Mouse reporting */
+	mouse: {
+		/** Enable SGR extended mouse mode with any-event tracking (scroll wheel support) */
+		enable: `${CSI}?1003h${CSI}?1006h`,
+		/** Disable mouse tracking */
+		disable: `${CSI}?1006l${CSI}?1003l`,
+	},
+
+	/** Bracketed paste mode */
+	paste: {
+		/** Enable bracketed paste */
+		enable: `${CSI}?2004h`,
+		/** Disable bracketed paste */
+		disable: `${CSI}?2004l`,
+		/** Paste start marker */
+		startMarker: `${CSI}200~`,
+		/** Paste end marker */
+		endMarker: `${CSI}201~`,
+	},
+
+	/** Line reflow control (DEC mode 2028 - limited terminal support) */
+	reflow: {
+		/** Disable line reflow on resize (Contour, some others) */
+		disable: `${CSI}?2028l`,
+		/** Enable line reflow on resize (default) */
+		enable: `${CSI}?2028h`,
+	},
+
+	/** Scroll region control (DECSTBM) */
+	scrollRegion: {
+		/** Set scroll region to rows [top, bottom] (1-indexed, inclusive) */
+		set: (top: number, bottom: number) => `${CSI}${top};${bottom}r`,
+		/** Reset scroll region to full screen */
+		reset: `${CSI}r`,
+	},
+
+	/** Line insertion/deletion */
+	lines: {
+		/** Insert n blank lines at cursor, pushing content down (IL) */
+		insert: (n: number) => (n > 0 ? `${CSI}${n}L` : ""),
+		/** Delete n lines at cursor, pulling content up (DL) */
+		delete: (n: number) => (n > 0 ? `${CSI}${n}M` : ""),
+	},
 
-  /** Exit full-screen mode: reset + show cursor + exit alternate screen */
-  exitFullscreen: ANSI.reset + ANSI.cursor.show + ANSI.screen.altExit,
+	/** Cursor save/restore (DECSC/DECRC) */
+	cursorState: {
+		/** Save cursor position and attributes */
+		save: "\x1b7",
+		/** Restore cursor position and attributes */
+		restore: "\x1b8",
+	},
 
-  /** Clear screen and move cursor to home */
-  clearAndHome: ANSI.screen.clear + ANSI.cursor.home,
+	/**
+	 * Kitty keyboard protocol
+	 * @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+	 * Enables enhanced key reporting with modifier detection for Ctrl+Shift+key combos
+	 */
+	keyboard: {
+		/**
+		 * Enable Kitty keyboard protocol with flags.
+		 * Flag 1 (disambiguate): Reports Ctrl+C as CSI sequence instead of raw ETX,
+		 * allowing detection of Ctrl+Shift+C vs Ctrl+C.
+		 * Supported by: Kitty, iTerm2 3.5+, WezTerm, Ghostty, foot, Contour, rio
+		 * NOTE: Many terminals intercept Ctrl+Shift+C for their own copy - may need
+		 * to configure terminal or use different keybinding.
+		 */
+		enable: (flags = 1) => `${CSI}>${flags}u`,
+		/** Disable/pop Kitty keyboard protocol */
+		disable: `${CSI}<u`,
+		/** Query current keyboard mode (response: CSI ? flags u) */
+		query: `${CSI}?u`,
+	},
 
-  /** Convenience shorthands for common toggles */
-  bracketedPasteOn: ANSI.paste.bracketed.on,
-  bracketedPasteOff: ANSI.paste.bracketed.off,
-  mouseOn: ANSI.mouse.on,
-  mouseOff: ANSI.mouse.off,
-  reportCursorPosition: ANSI.report.cursorPosition,
+	/**
+	 * xterm modifyOtherKeys mode
+	 * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
+	 * Alternative to Kitty protocol, supported by xterm and some other terminals.
+	 */
+	modifyOtherKeys: {
+		/** Enable mode 2 (full modifier reporting) */
+		enable: `${CSI}>4;2m`,
+		/** Disable modifyOtherKeys */
+		disable: `${CSI}>4;0m`,
+	},
+
+	/** Style/SGR reset */
+	resetStyle: `${CSI}0m`,
+
+	/** Build style SGR sequence */
+	style: (s: {
+		fg?: number
+		bg?: number
+		bold?: boolean
+		italic?: boolean
+		underline?: boolean
+		inverse?: boolean
+	}) => {
+		const codes: number[] = []
+		if (s.bold) codes.push(1)
+		if (s.italic) codes.push(3)
+		if (s.underline) codes.push(4)
+		if (s.inverse) codes.push(7)
+		if (s.fg !== undefined) {
+			if (s.fg < 256) {
+				codes.push(38, 5, s.fg)
+			} else {
+				// Truecolor: decode from packed RGB
+				const r = (s.fg >> 16) & 0xff
+				const g = (s.fg >> 8) & 0xff
+				const b = s.fg & 0xff
+				codes.push(38, 2, r, g, b)
+			}
+		}
+		if (s.bg !== undefined) {
+			if (s.bg < 256) {
+				codes.push(48, 5, s.bg)
+			} else {
+				const r = (s.bg >> 16) & 0xff
+				const g = (s.bg >> 8) & 0xff
+				const b = s.bg & 0xff
+				codes.push(48, 2, r, g, b)
+			}
+		}
+		return codes.length > 0 ? `${CSI}${codes.join(";")}m` : ""
+	},
+
+	/** Scrolling */
+	scroll: {
+		/** Scroll up by n lines */
+		up: (n: number) => `${CSI}${n}S`,
+	},
+
+	/** Device Status Reports */
+	report: {
+		/** Request cursor position (response: ESC [ row ; col R) */
+		cursorPosition: `${CSI}6n`,
+	},
+} as const
+
+/** High-level terminal control utilities (compositions of ANSI primitives) */
+export const Terminal = {
+	/** Enter full-screen mode: alternate screen + clear + hide cursor */
+	enterFullscreen: ANSI.screen.enterAlt + ANSI.screen.clear + ANSI.cursor.hide,
+	/** Exit full-screen mode: show cursor + exit alternate screen */
+	exitFullscreen: ANSI.screen.exitAlt + ANSI.cursor.show,
+	/** Hide cursor */
+	hideCursor: ANSI.cursor.hide,
+	/** Show cursor */
+	showCursor: ANSI.cursor.show,
+	/** Clear screen and move cursor to home */
+	clearAndHome: ANSI.screen.clear + ANSI.cursor.home,
+	/** Enable bracketed paste mode */
+	bracketedPasteOn: ANSI.paste.enable,
+	/** Disable bracketed paste mode */
+	bracketedPasteOff: ANSI.paste.disable,
+	/** Enable mouse tracking */
+	mouseOn: ANSI.mouse.enable,
+	/** Disable mouse tracking */
+	mouseOff: ANSI.mouse.disable,
+	/** Request cursor position report */
+	reportCursorPosition: ANSI.report.cursorPosition,
 } as const