@travetto/terminal 3.0.0-rc.10

package/README.md

@@ -0,0 +1,9 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/terminal/DOC.ts and execute "npx trv doc" to rebuild -->
+# Terminal
+## General terminal support
+
+**Install: @travetto/terminal**
+```bash
+npm install @travetto/terminal
+```

package/__index__.ts

@@ -0,0 +1,10 @@
+export * from './src/codes';
+export * from './src/color-define';
+export * from './src/color-output';
+export * from './src/iterable';
+export * from './src/named-colors';
+export * from './src/operation';
+export * from './src/query';
+export * from './src/terminal';
+export * from './src/types';
+export * from './src/writer';

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@travetto/terminal",
+  "version": "3.0.0-rc.10",
+  "description": "General terminal support",
+  "keywords": [
+    "terminal",
+    "ansi256",
+    "travetto",
+    "typescript"
+  ],
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src"
+  ],
+  "main": "__index__.ts",
+  "repository": {
+    "url": "https://github.com/travetto/travetto.git",
+    "directory": "module/terminal"
+  },
+  "travetto": {
+    "displayName": "Terminal"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/codes.ts

@@ -0,0 +1,41 @@
+const ESC = '\x1b[';
+const OSC = '\x1b]';
+const ST = '\x1b\\';
+
+// eslint-disable-next-line no-control-regex
+export const ANSI_CODE_REGEX = /(\x1b|\x1B)[\[\]][?]?[0-9;]+[A-Za-z]/g;
+
+export const OSC_QUERY_FIELDS = {
+  backgroundColor: 11,
+  foregroundColor: 10
+};
+
+export type OSCQueryField = keyof (typeof OSC_QUERY_FIELDS);
+
+export const DEVICE_STATUS_FIELDS = {
+  cursorPosition: 6,
+};
+
+export type DeviceStatusField = keyof (typeof DEVICE_STATUS_FIELDS);
+
+export const ANSICodes = {
+  DEBUG: (text: string): string => text.replaceAll(ESC, '<ESC>').replaceAll(OSC, '<OSC>').replaceAll('\n', '<NL>').replaceAll(ST, '<ST>'),
+  CURSOR_DY: (row: number): string => `${ESC}${Math.abs(row)}${row < 0 ? 'A' : 'B'}`,
+  CURSOR_DX: (col: number): string => `${ESC}${Math.abs(col)}${col < 0 ? 'D' : 'C'}`,
+  COLUMN_SET: (col: number): string => `${ESC}${col}G`,
+  POSITION_SET: (row: number, col: number): string => `${ESC}${row};${col}H`,
+  ERASE_SCREEN: (dir: 0 | 1 | 2 | 3 = 0): string => `${ESC}${dir}J`,
+  ERASE_LINE: (dir: 0 | 1 | 2 = 0): string => `${ESC}${dir}K`,
+  STYLE: (codes: (string | number)[]): string => `${ESC}${codes.join(';')}m`,
+  SHOW_CURSOR: (): string => `${ESC}?25h`,
+  HIDE_CURSOR: (): string => `${ESC}?25l`,
+  SCROLL_RANGE_SET: (start: number, end: number): string => `${ESC}${start};${end}r`,
+  SCROLL_RANGE_CLEAR: (): string => `${ESC}r`,
+  SCROLL_WINDOW: (rows: number): string => `${ESC}${Math.abs(rows)}${rows < 0 ? 'S' : 'T'}`,
+  POSITION_RESTORE: (): string => `${ESC}u`,
+  POSITION_SAVE: (): string => `${ESC}s`,
+  DEVICE_STATUS_REPORT: (code: DeviceStatusField): string => `${ESC}${DEVICE_STATUS_FIELDS[code]}n`,
+  OSC_QUERY: (code: OSCQueryField): string => `${OSC}${OSC_QUERY_FIELDS[code]};?${ST}`,
+};
+
+export const stripAnsiCodes = (text: string): string => text.replace(ANSI_CODE_REGEX, '');

package/src/color-define.ts

@@ -0,0 +1,195 @@
+import { NAMED_COLORS } from './named-colors';
+import { RGB, TermColorScheme } from './types';
+
+type I = number;
+type HSL = [h: I, s: I, l: I];
+export type DefinedColor = { rgb: RGB, hsl: HSL, idx16: I, idx16bg: I, idx256: I, scheme: TermColorScheme };
+export type RGBInput = I | keyof (typeof NAMED_COLORS) | `#${string}`;
+
+const _rgb = (r: I, g: I = r, b: I = g): RGB => [r, g, b];
+
+const STD_PRE = ['std', 'bright'] as const;
+const STD_COLORS = ['Black', 'Red', 'Green', 'Yellow', 'Blue', 'Magenta', 'Cyan', 'White'] as const;
+
+// eslint-disable-next-line no-bitwise
+const toRgbArray = (val: number): RGB => [(val >> 16) & 255, (val >> 8) & 255, val & 255];
+
+const ANSI256_TO_16_IDX = [30, 31, 32, 33, 34, 35, 36, 37, 90, 91, 92, 93, 94, 95, 96, 97];
+const ANSI16_TO_BG = new Map(ANSI256_TO_16_IDX.map(x => [x, x + 10]));
+
+// Inspired/sourced from: https://github.com/mina86/ansi_colours/blob/master/src/ansi256.rs
+const ANSI256_GRAY_MAPPING = [
+  [16, 5],
+  [232, 9], [233, 10], [234, 10], [235, 10], [236, 10], [237, 10], [238, 10], [239, 10], [240, 8],
+  [59, 5],
+  [241, 7], [242, 10], [243, 9], [244, 9],
+  [102, 5],
+  [245, 6], [246, 10], [247, 10], [248, 9],
+  [145, 5],
+  [249, 6], [250, 10], [251, 10], [252, 9],
+  [188, 5],
+  [253, 6], [254, 10], [255, 14],
+  [231, 9]
+].flatMap(([v, r]) => new Array<number>(v).fill(r));
+
+const STEPS_256 = [0, 95, 135, 175, 215, 255];
+
+const ANSI256_TO_RGB: RGB[] = [
+  ...STD_PRE.flatMap(p => STD_COLORS.map(c => NAMED_COLORS[`${p}${c}`]).map(toRgbArray)),
+  ...STEPS_256.flatMap(r => STEPS_256.flatMap(g => STEPS_256.map(b => _rgb(r, g, b)))),
+  ...new Array(24).fill(0).map((_, i) => _rgb(i * 10 + 8)) // Grays
+];
+
+// Pulled from: https://github.com/mina86/ansi_colours/blob/master/src/ansi256.rs
+const RED_256_LEVELS = [38, 115, 155, 196, 235];
+const GREEN_256_LEVELS = [38, 115, 155, 196, 235];
+const BLUE_256_LEVELS = [35, 115, 155, 195, 235];
+
+export class ColorDefineUtil {
+  static CACHE = new Map<number | string, DefinedColor>();
+
+  static #snapToLevel(levels: number[], val: number): number {
+    for (let i = 0; i < levels.length; i += 1) {
+      if (val < levels[i]) { return i; }
+    }
+    return levels.length;
+  }
+
+  // Returns luminance of given sRGB color.
+  // Pulled from: https://github.com/mina86/ansi_colours/blob/master/src/ansi256.rs
+  // eslint-disable-next-line no-bitwise
+  static #luminance = ([r, g, b]: RGB): number => (((3567664 * r + 11998547 * g + 1211005 * b) + (1 << 23)) >> 24) & 255;
+
+  // Pulled from: https://github.com/mina86/ansi_colours/blob/master/src/ansi256.rs
+  static #distance = ([xr, xg, xb]: RGB, [yr, yg, yb]: RGB, sr = xr + yr): number =>
+    (1024 + sr) * ((xr - yr) ** 2) + 2048 * ((xg - yg) ** 2) + (1534 - sr) * ((xb - yb) ** 2);
+
+  static #snapToAnsi256Bands([r, g, b]: RGB): [idx: number, snapped: RGB] {
+    const ri = this.#snapToLevel(RED_256_LEVELS, r);
+    const gi = this.#snapToLevel(GREEN_256_LEVELS, g);
+    const bi = this.#snapToLevel(BLUE_256_LEVELS, b);
+    return [(ri * 36 + 16 + gi * 6 + bi), [STEPS_256[ri], STEPS_256[gi], STEPS_256[bi]]];
+  }
+
+  /**
+   * Converts [R,G,B] to an ANSI 256 index
+   */
+  // Inspired/sourced from: https://github.com/mina86/ansi_colours/blob/master/src/ansi256.rs
+  static ansi256FromRgb(rgb: RGB): number {
+    const grayIdx = ANSI256_GRAY_MAPPING[this.#luminance(rgb)];
+    const grayDist = this.#distance(rgb, ANSI256_TO_RGB[grayIdx]);
+    const [snappedIdx, snapped] = this.#snapToAnsi256Bands(rgb);
+    return this.#distance(rgb, snapped) < grayDist ? snappedIdx : grayIdx;
+  }
+
+  /**
+   * Converts [R,G,B] to an ANSI 16 index
+   */
+  static ansi16FromRgb(rgb: RGB): number {
+    let min = Number.MAX_SAFE_INTEGER;
+    let minIdx = -1;
+    for (let i = 0; i < 16; i += 1) {
+      const dist = this.#distance(rgb, ANSI256_TO_RGB[i]);
+      if (dist < min) {
+        min = dist;
+        minIdx = i;
+      }
+    }
+    return ANSI256_TO_16_IDX[minIdx];
+  }
+
+  /**
+   * ANSI 256 into RGB
+   */
+  static rgbFromAnsi256(val: number): RGB {
+    return ANSI256_TO_RGB[val];
+  }
+
+  /**
+   * Converts [R,G,B] to [H,S,L]
+   */
+  static hsl([r, g, b]: RGB): HSL {
+    const [rf, gf, bf] = [r / 255, g / 255, b / 255];
+    const max = Math.max(rf, gf, bf), min = Math.min(rf, gf, bf);
+    let h = 0;
+    let s = 0;
+    const l = (max + min) / 2;
+
+    if (max === min) {
+      h = s = 0; // achromatic
+    } else {
+      const d = max - min;
+      s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+      switch (max) {
+        case rf: h = (gf - bf) / d + (gf < bf ? 6 : 0); break;
+        case gf: h = (bf - rf) / d + 2; break;
+        case bf: h = (rf - gf) / d + 4; break;
+      }
+      h /= 6;
+    }
+    return [h, s, l];
+  }
+
+
+  /**
+   * Converts input value into [R,G,B] output
+   */
+  static toRgb(val: RGBInput): RGB {
+    if (typeof val === 'string') {
+      if (val.startsWith('#')) {
+        const res = val.match(/^#(?<rh>[a-f0-9]{2})(?<gh>[a-f0-9]{2})(?<bh>[a-f0-9]{2})$/i);
+        if (res) {
+          const { rh, gh, bh } = res.groups!;
+          return [parseInt(rh, 16), parseInt(gh, 16), parseInt(bh, 16)];
+        }
+      } else if (val in NAMED_COLORS) {
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        return this.toRgb(NAMED_COLORS[val as keyof typeof NAMED_COLORS]);
+      }
+      throw new Error(`Unknown color format: ${val}`);
+    } else if (typeof val === 'number') {
+      return toRgbArray(val);
+    } else {
+      return val;
+    }
+  }
+
+  /**
+   * Determine if a color is light or dark
+   */
+  static getScheme(color: RGB): TermColorScheme {
+    const [r, g, b] = color;
+    return (r + g + b) / 3 < 128 ? 'dark' : 'light';
+  }
+
+  /**
+   * Define a color and all its parts
+   */
+  static defineColor(val: RGBInput): DefinedColor {
+    if (!this.CACHE.has(val)) {
+      const rgb = this.toRgb(val);
+      const idx16 = this.ansi16FromRgb(rgb);
+      const idx256 = this.ansi256FromRgb(rgb);
+      const hsl = this.hsl(rgb);
+      const idx16bg = ANSI16_TO_BG.get(idx16)!;
+      const scheme = this.getScheme(rgb);
+      this.CACHE.set(val, { rgb, idx16, idx16bg, idx256, hsl, scheme });
+    }
+    return this.CACHE.get(val)!;
+  }
+
+  /**
+   * Build ANSI compatible color codes by level
+   */
+  static getColorCodes(inp: RGBInput, bg: boolean): [number[], number[]][] {
+    const spec = this.defineColor(inp);
+    const { idx16, idx16bg, idx256, rgb } = spec;
+    const [open, close] = bg ? [48, 49] : [38, 39];
+    return [
+      [[], []],
+      [[bg ? idx16bg : idx16], [close]],
+      [[open, 5, idx256], [close]],
+      [[open, 2, ...rgb], [close]]
+    ];
+  }
+}

package/src/color-output.ts

@@ -0,0 +1,127 @@
+import tty from 'tty';
+
+import { ColorDefineUtil, RGBInput } from './color-define';
+import { ANSICodes } from './codes';
+import { TermColorScheme, TermColorLevel, TermState, RGB } from './types';
+
+export type TermStyle =
+  { text?: RGBInput, background?: RGBInput, italic?: boolean, underline?: boolean, inverse?: boolean, blink?: boolean };
+
+export type TermStyleInput = TermStyle | RGBInput;
+export type Prim = string | number | boolean | Date | RegExp;
+export type TermColorPaletteInput = Record<string, TermStyleInput | [TermStyleInput, TermStyleInput]>;
+export type TermColorFn = (text: Prim) => string;
+export type TermColorPalette<T> = Record<keyof T, TermColorFn>;
+
+const COLOR_LEVEL_MAP = { 1: 0, 4: 1, 8: 2, 24: 3 } as const;
+type ColorBits = keyof (typeof COLOR_LEVEL_MAP);
+
+/**
+ * Utils for colorizing output
+ */
+export class ColorOutputUtil {
+
+  /**
+   * Detect color level from tty information
+   */
+  static async readTermColorLevel(stream: tty.WriteStream): Promise<TermColorLevel> {
+    const force = process.env.FORCE_COLOR;
+    const disable = process.env.NO_COLOR ?? process.env.NODE_DISABLE_COLORS;
+    if (force !== undefined) {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      return Math.max(Math.min(/^\d+$/.test(force) ? parseInt(force, 10) : 1, 3), 0) as TermColorLevel;
+    } else if (disable !== undefined && /^(1|true|yes|on)/i.test(disable)) {
+      return 0;
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return stream.isTTY ? COLOR_LEVEL_MAP[stream.getColorDepth() as ColorBits] : 0;
+  }
+
+  /**
+   * Read foreground/background color if env var is set
+   */
+  static async readBackgroundScheme(
+    query: () => Promise<RGB | undefined> | RGB | undefined,
+    env: string | undefined = process.env.COLORFGBG
+  ): Promise<TermColorScheme | undefined> {
+    let color = await query();
+    if (!color && env) {
+      const [, bg] = env.split(';');
+      color = ColorDefineUtil.rgbFromAnsi256(+bg);
+    }
+    if (color) {
+      const hex = `#${color.map(x => x.toString(16).padStart(2, '0')).join('')}` as const;
+      return ColorDefineUtil.defineColor(hex).scheme;
+    }
+  }
+
+  /**
+   * Get styled levels, 0-3
+   */
+  static getStyledLevels(inp: TermStyle | RGBInput): [string, string][] {
+    const cfg = (typeof inp !== 'object') ? { text: inp } : inp;
+    const levelPairs: [string, string][] = [['', '']];
+    const text = cfg.text ? ColorDefineUtil.getColorCodes(cfg.text, false) : undefined;
+    const bg = cfg.background ? ColorDefineUtil.getColorCodes(cfg.background, true) : undefined;
+
+    for (const level of [1, 2, 3]) {
+      const prefix: number[] = [];
+      const suffix: number[] = [];
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      for (const key of Object.keys(cfg) as (keyof typeof cfg)[]) {
+        if (!cfg[key]) {
+          continue;
+        }
+        switch (key) {
+          case 'inverse': prefix.push(7); suffix.push(27); break;
+          case 'underline': prefix.push(4); suffix.push(24); break;
+          case 'italic': prefix.push(3); suffix.push(23); break;
+          case 'blink': prefix.push(5); suffix.push(25); break;
+          case 'text': prefix.push(...text![level][0]); suffix.push(...text![level][1]); break;
+          case 'background': prefix.push(...bg![level][0]); suffix.push(...bg![level][1]); break;
+        }
+      }
+      levelPairs[level] = [
+        ANSICodes.STYLE(prefix),
+        ANSICodes.STYLE(suffix.reverse())
+      ];
+    }
+    return levelPairs;
+  }
+
+  /**
+   * Make a simple primitive colorer
+   */
+  static colorer(term: TermState, style: TermStyleInput | [light: TermStyleInput, dark: TermStyleInput]): TermColorFn {
+    const schemes = {
+      light: this.getStyledLevels(Array.isArray(style) ? style[1] ?? style[0] : style),
+      dark: this.getStyledLevels(Array.isArray(style) ? style[0] : style),
+    };
+    return (v: Prim): string => {
+      const [prefix, suffix] = schemes[term.backgroundScheme][term.colorLevel];
+      return (v === undefined || v === null) ? '' : `${prefix}${v}${suffix}`;
+    };
+  }
+
+  /**
+   * Creates a color palette based on input styles
+   */
+  static palette<P extends TermColorPaletteInput>(term: TermState, input: P): TermColorPalette<P> {
+    // Common color support
+    const out: Partial<TermColorPalette<P>> = {};
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    for (const [k, col] of Object.entries(input) as [keyof P, TermStyleInput][]) {
+      out[k] = this.colorer(term, col);
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return out as TermColorPalette<P>;
+  }
+
+  /**
+   * Convenience method to creates a color template function based on input styles
+   */
+  static templateFunction<P extends TermColorPaletteInput>(term: TermState, input: P): (key: keyof P, val: Prim) => string {
+    const pal = this.palette(term, input);
+    return (key: keyof P, val: Prim) => pal[key](val);
+  }
+}

package/src/iterable.ts

@@ -0,0 +1,100 @@
+import timers from 'timers/promises';
+import { DelayedConfig, Indexed } from './types';
+
+export type StoppableIterable<T> = { stream: AsyncIterable<T>, stop: () => void };
+
+export type MapFn<T, U> = (val: T, i: number) => U | Promise<U>;
+
+const isIdx = (x: unknown): x is Indexed => (x !== undefined && x !== null) && typeof x === 'object' && 'idx' in x;
+
+export class IterableUtil {
+
+  static DELAY = ({ initialDelay = 0, cycleDelay = 0 }: DelayedConfig = {}) =>
+    <T>(x: T, i: number): Promise<T> => timers.setTimeout(i === 0 ? initialDelay : cycleDelay).then(() => x);
+
+  static ORDERED = <T extends Indexed>(): (val: T) => boolean => {
+    let last = -1;
+    return (v: T): boolean => (last = Math.max(v.idx, last)) === v.idx;
+  };
+
+  static map<T, U, V, W>(source: AsyncIterable<T>, fn1: MapFn<T, U>, fn2: MapFn<U, V>, fn3: MapFn<V, W>): AsyncIterable<W>;
+  static map<T, U, V>(source: AsyncIterable<T>, fn1: MapFn<T, U>, fn2: MapFn<U, V>): AsyncIterable<V>;
+  static map<T, U>(source: AsyncIterable<T>, fn: MapFn<T, U>): AsyncIterable<U>;
+  static async * map<T>(source: AsyncIterable<T>, ...fns: MapFn<unknown, unknown>[]): AsyncIterable<unknown> {
+    let idx = -1;
+    for await (const el of source) {
+      if (el !== undefined) {
+        idx += 1;
+        let m = el;
+        for (const fn of fns) {
+          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+          m = (await fn(m, idx)) as typeof m;
+        }
+        yield m;
+      }
+    }
+  }
+
+  static async * filter<T>(source: AsyncIterable<T>, pred: (val: T, i: number) => boolean | Promise<boolean>): AsyncIterable<T> {
+    let idx = -1;
+    for await (const el of source) {
+      if (await pred(el, idx += 1)) {
+        yield el;
+      }
+    }
+  }
+
+  static cycle<T>(items: T[]): StoppableIterable<T> {
+    let done = false;
+    async function* buildStream(): AsyncIterable<T> {
+      let i = -1;
+      while (!done) {
+        yield items[(i += 1) % items.length];
+      }
+    }
+    return { stream: buildStream(), stop: (): void => { done = true; } };
+  }
+
+  static async drain<T>(source: AsyncIterable<T>): Promise<T[]> {
+    const items: T[] = [];
+    for await (const ev of source) {
+      items[isIdx(ev) ? ev.idx : items.length] = ev;
+    }
+    return items;
+  }
+
+  static simpleQueue(): {
+    close: () => Promise<void>;
+    add: <T>(item: () => Promise<T>) => Promise<T>;
+    running: Promise<void>;
+  } {
+    let done = false;
+    let fire: () => void;
+    let next = new Promise<void>(r => fire = r);
+
+    const queue: Function[] = [];
+    async function run(): Promise<void> {
+      while (!done) {
+        if (!queue.length) {
+          await next;
+          next = new Promise(r => fire = r);
+        }
+        await queue.shift()?.();
+      }
+    }
+    const running = run();
+    return {
+      running,
+      close: (): Promise<void> => {
+        done = true;
+        fire();
+        return running;
+      },
+      add: <T>(fn: () => Promise<T>): Promise<T> => {
+        const prom = new Promise<T>(r => queue.push(() => fn().then(r)));
+        fire();
+        return prom;
+      }
+    };
+  }
+}

package/src/named-colors.ts

@@ -0,0 +1,160 @@
+export const NAMED_COLORS = {
+  // Name: RGB
+  stdBlack: 0x000000,
+  stdRed: 0xcd0000,
+  stdGreen: 0x00cd00,
+  stdYellow: 0xcdcd00,
+  stdBlue: 0x0000ee,
+  stdMagenta: 0xcd00cd,
+  stdCyan: 0x00cdcd,
+  stdWhite: 0xe5e5e5,
+  brightBlack: 0x7f7f7f,
+  brightRed: 0xff0000,
+  brightGreen: 0x00fc00,
+  brightYellow: 0xffff00,
+  brightBlue: 0x0000fc,
+  brightMagenta: 0xff00ff,
+  brightCyan: 0x00ffff,
+  brightWhite: 0xffffff,
+
+  aliceBlue: 0xf0f8ff,
+  antiqueWhite: 0xfaebd7,
+  aqua: 0x00ffff,
+  aquamarine: 0x7fffd4,
+  azure: 0xf0ffff,
+  beige: 0xf5f5dc,
+  bisque: 0xffe4c4,
+  black: 0x000000,
+  blanchedAlmond: 0xffebcd,
+  blue: 0x0000ff,
+  blueViolet: 0x8a2be2,
+  brown: 0xa52a2a,
+  burlyWood: 0xdeb887,
+  cadetBlue: 0x5f9ea0,
+  chartreuse: 0x7fff00,
+  chocolate: 0xd2691e,
+  coral: 0xff7f50,
+  cornflowerBlue: 0x6495ed,
+  cornSilk: 0xfff8dc,
+  crimson: 0xdc143c,
+  cyan: 0x00ffff,
+  darkBlue: 0x00008b,
+  darkCyan: 0x008b8b,
+  darkGoldenrod: 0xb8860b,
+  darkGray: 0xa9a9a9,
+  darkGreen: 0x006400,
+  darkKhaki: 0xbdb76b,
+  darkMagenta: 0x8b008b,
+  darkOliveGreen: 0x556b2f,
+  darkOrange: 0xff8c00,
+  darkOrchid: 0x9932cc,
+  darkRed: 0x8b0000,
+  darkSalmon: 0xe9967a,
+  darkSeaGreen: 0x8fbc8f,
+  darkSlateBlue: 0x483d8b,
+  darkSlateGray: 0x2f4f4f,
+  darkTurquoise: 0x00ced1,
+  darkViolet: 0x9400d3,
+  deepPink: 0xff1493,
+  deepSkyBlue: 0x00bfff,
+  dimGray: 0x696969,
+  dodgerBlue: 0x1e90ff,
+  firebrick: 0xb22222,
+  floralWhite: 0xfffaf0,
+  forestGreen: 0x228b22,
+  fuchsia: 0xff00ff,
+  gainsboro: 0xdcdcdc,
+  ghostWhite: 0xf8f8ff,
+  gold: 0xffd700,
+  goldenrod: 0xdaa520,
+  gray: 0x808080,
+  green: 0x008000,
+  greenYellow: 0xadff2f,
+  honeydew: 0xf0fff0,
+  hotPink: 0xff69b4,
+  indianRed: 0xcd5c5c,
+  indigo: 0x4b0082,
+  ivory: 0xfffff0,
+  khaki: 0xf0e68c,
+  lavender: 0xe6e6fa,
+  lavenderBlush: 0xfff0f5,
+  lawnGreen: 0x7cfc00,
+  lemonChiffon: 0xfffacd,
+  lightBlue: 0xadd8e6,
+  lightCoral: 0xf08080,
+  lightCyan: 0xe0ffff,
+  lightGoldenRodYellow: 0xfafad2,
+  lightGray: 0xd3d3d3,
+  lightGreen: 0x90ee90,
+  lightPink: 0xffb6c1,
+  lightSalmon: 0xffa07a,
+  lightSeaGreen: 0x20b2aa,
+  lightSkyBlue: 0x87cefa,
+  lightSlateGray: 0x778899,
+  lightSteelBlue: 0xb0c4de,
+  lightYellow: 0xffffe0,
+  lime: 0x00ff00,
+  limeGreen: 0x32cd32,
+  linen: 0xfaf0e6,
+  magenta: 0xff00ff,
+  maroon: 0x800000,
+  mediumAquamarine: 0x66cdaa,
+  mediumBlue: 0x0000cd,
+  mediumOrchid: 0xba55d3,
+  mediumPurple: 0x9370db,
+  mediumSeaGreen: 0x3cb371,
+  mediumSlateBlue: 0x7b68ee,
+  mediumSpringGreen: 0x00fa9a,
+  mediumTurquoise: 0x48d1cc,
+  mediumVioletRed: 0xc71585,
+  midnightBlue: 0x191970,
+  mintCream: 0xf5fffa,
+  mistyRose: 0xffe4e1,
+  moccasin: 0xffe4b5,
+  navajoWhite: 0xffdead,
+  navy: 0x000080,
+  oldLace: 0xfdf5e6,
+  olive: 0x808000,
+  oliveDrab: 0x6b8e23,
+  orange: 0xffa500,
+  orangeRed: 0xff4500,
+  orchid: 0xda70d6,
+  paleGoldenrod: 0xeee8aa,
+  paleGreen: 0x98fb98,
+  paleTurquoise: 0xafeeee,
+  paleVioletRed: 0xdb7093,
+  papayaWhip: 0xffefd5,
+  peachPuff: 0xffdab9,
+  peru: 0xcd853f,
+  pink: 0xffc0cb,
+  plum: 0xdda0dd,
+  powderBlue: 0xb0e0e6,
+  purple: 0x800080,
+  red: 0xff0000,
+  rosyBrown: 0xbc8f8f,
+  royalBlue: 0x4169e1,
+  saddleBrown: 0x8b4513,
+  salmon: 0xfa8072,
+  sandyBrown: 0xf4a460,
+  seaGreen: 0x2e8b57,
+  seashell: 0xfff5ee,
+  sienna: 0xa0522d,
+  silver: 0xc0c0c0,
+  skyBlue: 0x87ceeb,
+  slateBlue: 0x6a5acd,
+  slateGray: 0x708090,
+  snow: 0xfffafa,
+  springGreen: 0x00ff7f,
+  steelBlue: 0x4682b4,
+  tan: 0xd2b48c,
+  teal: 0x008080,
+  thistle: 0xd8bfd8,
+  tomato: 0xff6347,
+  turquoise: 0x40e0d0,
+  violet: 0xee82ee,
+  wheat: 0xf5deb3,
+  white: 0xffffff,
+  whitesmoke: 0xf5f5f5,
+  yellow: 0xffff00,
+  yellowGreen: 0x9acd32,
+} as const;

package/src/operation.ts

@@ -0,0 +1,134 @@
+import { IterableUtil } from './iterable';
+import { TerminalWriter } from './writer';
+import { Indexed, TerminalProgressRender, TerminalStreamingConfig, TerminalWaitingConfig, TermState } from './types';
+import { ColorOutputUtil, TermStyleInput } from './color-output';
+
+const STD_WAIT_STATES = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'.split('');
+
+export class TerminalOperation {
+
+  /**
+   * Allows for writing at top, bottom, or current position while new text is added
+   */
+  static async streamToPosition(term: TermState, source: AsyncIterable<string>, config: TerminalStreamingConfig = {}): Promise<void> {
+    const curPos = config.at ?? { ...await term.getCursorPosition() };
+    const pos = config.position ?? 'inline';
+
+    const writePos = pos === 'inline' ?
+      { ...curPos, x: 0 } :
+      { x: 0, y: pos === 'top' ? 0 : -1 };
+
+    try {
+      const batch = TerminalWriter.for(term).hideCursor();
+      if (pos !== 'inline') {
+        batch.storePosition().scrollRange(pos === 'top' ? { start: 2 } : { end: -2 }).restorePosition();
+        if (pos === 'top' && curPos.y === 0) {
+          batch.changePosition({ y: 1 }).write('');
+        } else if (pos === 'bottom' && curPos.y === term.height - 1) {
+          batch.changePosition({ y: -1 }).write('\n');
+        }
+      } else {
+        batch.write('\n'); // Move past line
+      }
+      await batch.commit();
+
+      for await (const text of source) {
+        await TerminalWriter.for(term).setPosition(writePos).write(text).clearLine(1).commit(true);
+      }
+      if (config.clearOnFinish ?? true) {
+        await TerminalWriter.for(term).setPosition(writePos).clearLine().commit(true);
+      }
+    } finally {
+      const finalCursor = await term.getCursorPosition();
+      await TerminalWriter.for(term).scrollRangeClear().setPosition(finalCursor).showCursor().commit();
+    }
+  }
+
+  /**
+   * Consumes a stream, of events, tied to specific list indices, and updates in place
+   */
+  static async streamList(term: TermState, source: AsyncIterable<Indexed & { text: string }>): Promise<void> {
+    let max = 0;
+    try {
+      await TerminalWriter.for(term).hideCursor().commit();
+      for await (const { idx, text } of source) {
+        max = Math.max(idx, max);
+        await TerminalWriter.for(term).write('\n'.repeat(idx)).rewriteLine(text).clearLine(1).changePosition({ y: -idx }).commit();
+      }
+    } finally {
+      await TerminalWriter.for(term).changePosition({ y: max + 1 }).writeLine('\n').showCursor().commit();
+    }
+  }
+
+  /**
+   * Waiting indicator, streamed to a specific position, can be canceled
+   */
+  static streamWaiting(term: TermState, message: string, config: TerminalWaitingConfig = {}): () => Promise<void> {
+    const { stop, stream } = IterableUtil.cycle(STD_WAIT_STATES);
+    const indicator = IterableUtil.map(
+      stream,
+      IterableUtil.DELAY(config),
+      (ch, i) => config.end ? `${message} ${ch}` : `${ch} ${message}`
+    );
+
+    const final = this.streamToPosition(term, indicator, config);
+    return async () => { stop(); return final; };
+  }
+
+  /**
+   * Build progress par formatter for terminal progress events
+   */
+  static buildProgressBar(term: TermState, style: TermStyleInput): TerminalProgressRender {
+    const color = ColorOutputUtil.colorer(term, style);
+    return ({ total, idx, text }): string => {
+      text ||= total ? '%idx/%total' : '%idx';
+
+      const totalStr = `${total ?? ''}`;
+      const idxStr = `${idx}`.padStart(totalStr.length);
+      const pct = total === undefined ? 0 : (idx / total);
+      const line = text
+        .replace(/%idx/, idxStr)
+        .replace(/%total/, totalStr)
+        .replace(/%pct/, `${Math.trunc(pct * 100)}`);
+      const full = ` ${line}`.padEnd(term.width);
+      const mid = Math.trunc(pct * term.width);
+      const [l, r] = [full.substring(0, mid), full.substring(mid)];
+      return `${color(l)}${r}`;
+    };
+  }
+
+  /**
+   * Stream lines with a waiting indicator
+   */
+  static async streamLinesWithWaiting(term: TermState, lines: AsyncIterable<string | undefined>, cfg: TerminalWaitingConfig = {}): Promise<void> {
+    let writer: (() => Promise<unknown>) | undefined;
+    let line: string | undefined;
+
+    let pos = await term.getCursorPosition();
+
+
+    const commitLine = async (): Promise<void> => {
+      await writer?.();
+      if (line) {
+        const msg = cfg.committedPrefix ? `${cfg.committedPrefix} ${line}` : line;
+        if (cfg.position === 'inline') {
+          await TerminalWriter.for(term).setPosition(pos).write(msg).commit(true);
+        } else {
+          await TerminalWriter.for(term).writeLine(msg).commit();
+        }
+        line = undefined;
+      }
+    };
+
+    for await (let msg of lines) {
+      await commitLine();
+      if (msg !== undefined) {
+        msg = msg.replace(/\n$/, '');
+        pos = await term.getCursorPosition();
+        writer = this.streamWaiting(term, msg, { ...cfg, at: pos, clearOnFinish: false });
+        line = msg;
+      }
+    }
+    await commitLine();
+  }
+}

package/src/query.ts

@@ -0,0 +1,96 @@
+import tty from 'tty';
+
+import { ANSICodes } from './codes';
+import { IterableUtil } from './iterable';
+import { RGB, TermCoord, TermQuery } from './types';
+
+const to256 = (x: string): number => Math.trunc(parseInt(x, 16) / (16 ** (x.length - 2)));
+const COLOR_RESPONSE = /(?<r>][0-9a-f]+)[/](?<g>[0-9a-f]+)[/](?<b>[0-9a-f]+)[/]?(?<a>[0-9a-f]+)?/i;
+
+const ANSIQueries = {
+  /** Parse xterm color response */
+  color: (field: 'background' | 'foreground'): TermQuery<RGB | undefined> => ({
+    query: (): string => ANSICodes.OSC_QUERY(`${field}Color`),
+    response: (response: Buffer): RGB | undefined => {
+      const groups = response.toString('utf8').match(COLOR_RESPONSE)?.groups ?? {};
+      return 'r' in groups ? [to256(groups.r), to256(groups.g), to256(groups.b)] : undefined;
+    }
+  }),
+  /** Parse cursor query response into {x,y} */
+  cursorPosition: {
+    query: (): string => ANSICodes.DEVICE_STATUS_REPORT('cursorPosition'),
+    response: (response: Buffer): TermCoord => {
+      const groups = response.toString('utf8').match(/(?<r>\d*);(?<c>\d*)/)?.groups ?? {};
+      return 'c' in groups ? { x: +(groups.c) - 1, y: +(groups.r) - 1 } : { x: 0, y: 0 };
+    }
+  }
+};
+
+/**
+ * Terminal query support with centralized queuing for multiple writes to the same stream
+ */
+export class TerminalQuerier {
+
+  static #cache = new Map<tty.ReadStream, TerminalQuerier>();
+
+  static for(input: tty.ReadStream, output: tty.WriteStream): TerminalQuerier {
+    if (!this.#cache.has(input)) {
+      this.#cache.set(input, new TerminalQuerier(input, output));
+    }
+    return this.#cache.get(input)!;
+  }
+
+  #queue = IterableUtil.simpleQueue();
+  #output: tty.WriteStream;
+  #input: tty.ReadStream;
+
+  constructor(input: tty.ReadStream, output: tty.WriteStream) {
+    this.#input = input;
+    this.#output = output;
+  }
+
+  async #readInput(query: string): Promise<Buffer> {
+    const isRaw = this.#input.isRaw;
+    const isPaused = this.#input.isPaused();
+    const data = this.#input.listeners('data');
+    try {
+      this.#input.removeAllListeners('data');
+
+      if (isPaused) {
+        this.#input.resume();
+      }
+
+      this.#input.setRawMode(true);
+      // Send data, but do not wait on it
+      this.#output.write(query);
+      await new Promise(res => this.#input.once('readable', res));
+      const val: Buffer | string = this.#input.read();
+      return typeof val === 'string' ? Buffer.from(val, 'utf8') : val;
+    } finally {
+      if (isPaused) {
+        this.#input.pause();
+      }
+      this.#input.setRawMode(isRaw);
+      for (const fn of data) {
+        // @ts-ignore
+        this.#input.on('data', fn);
+      }
+    }
+  }
+
+  query<T>(q: TermQuery<T>): Promise<T> {
+    return this.#queue.add(() => this.#readInput(q.query()).then(q.response));
+  }
+
+  cursorPosition(): Promise<TermCoord> {
+    return this.query(ANSIQueries.cursorPosition);
+  }
+
+  backgroundColor(): Promise<RGB | undefined> {
+    return this.query(ANSIQueries.color('background'));
+  }
+
+  close(): Promise<void> {
+    return this.#queue.close();
+  }
+}

package/src/terminal.ts

@@ -0,0 +1,207 @@
+import tty from 'tty';
+
+import { IterableUtil, MapFn } from './iterable';
+import {
+  TermColorLevel, TermColorScheme, TerminalProgressEvent, TerminalTableConfig,
+  TerminalTableEvent, TerminalWaitingConfig, TermLinePosition, TermState, TermCoord
+} from './types';
+import { TerminalOperation } from './operation';
+import { TerminalQuerier } from './query';
+import { TerminalWriter } from './writer';
+import { ColorOutputUtil, Prim, TermColorFn, TermColorPalette, TermColorPaletteInput, TermStyleInput } from './color-output';
+
+type TerminalStreamPositionConfig = {
+  position?: TermLinePosition;
+  staticMessage?: string;
+};
+
+type TerminalProgressConfig = TerminalStreamPositionConfig & {
+  style?: TermStyleInput;
+};
+
+/**
+ * An enhanced tty write stream
+ */
+export class Terminal implements TermState {
+
+  static async for(config: Partial<TermState>): Promise<Terminal> {
+    const term = new Terminal(config);
+    await term.init();
+    return term;
+  }
+
+  #init: Promise<void>;
+  #output: tty.WriteStream;
+  #input: tty.ReadStream;
+  #interactive: boolean;
+  #width?: number;
+  #backgroundScheme?: TermColorScheme;
+  #colorLevel?: TermColorLevel;
+  #query: TerminalQuerier;
+
+  constructor(config: Partial<TermState>) {
+    this.#output = config.output ?? process.stdout;
+    this.#input = config.input ?? process.stdin;
+    this.#interactive = config.interactive ?? (this.#output.isTTY && !/^(true|yes|on|1)$/i.test(process.env.TRV_QUIET ?? ''));
+    this.#width = config.width;
+    this.#colorLevel = config.colorLevel;
+    this.#backgroundScheme = config.backgroundScheme;
+    this.#query = TerminalQuerier.for(this.#input, this.#output);
+  }
+
+  get output(): tty.WriteStream {
+    return this.#output;
+  }
+
+  get input(): tty.ReadStream {
+    return this.#input;
+  }
+
+  get interactive(): boolean {
+    return this.#interactive;
+  }
+
+  get width(): number {
+    return this.#width ?? (this.#output.isTTY ? this.#output.columns : 120);
+  }
+
+  get height(): number {
+    return (this.#output.isTTY ? this.#output.rows : 120);
+  }
+
+  get colorLevel(): TermColorLevel {
+    return this.#colorLevel ?? 0;
+  }
+
+  get backgroundScheme(): TermColorScheme {
+    return this.#backgroundScheme ?? 'dark';
+  }
+
+  writer(): TerminalWriter {
+    return TerminalWriter.for(this);
+  }
+
+  async writeLines(...text: string[]): Promise<void> {
+    return this.writer().writeLines(text, this.interactive).commit();
+  }
+
+  async init(): Promise<void> {
+    if (!this.#init) {
+      this.#init = (async (): Promise<void> => {
+        this.#colorLevel ??= await ColorOutputUtil.readTermColorLevel(this.#output);
+        this.#backgroundScheme ??= await ColorOutputUtil.readBackgroundScheme(
+          () => this.interactive ? this.#query.backgroundColor() : undefined
+        );
+      })();
+      process.on('exit', () => this.reset());
+    }
+    return this.#init;
+  }
+
+  async reset(): Promise<void> {
+    await this.#query.close();
+    if (this.interactive) {
+      await this.writer().reset().commit();
+    }
+    return;
+  }
+
+  getCursorPosition(): Promise<TermCoord> {
+    return this.#query.cursorPosition();
+  }
+
+  /**
+   * Waiting message with a callback to end
+   */
+  async withWaiting<T>(message: string, work: Promise<T> | (() => Promise<T>), config: TerminalWaitingConfig = {}): Promise<T> {
+    const res = (typeof work === 'function' ? work() : work);
+    if (!this.interactive) {
+      await this.writeLines(`${message}...`);
+      return res;
+    }
+    return res.finally(TerminalOperation.streamWaiting(this, message, config));
+  }
+
+  /**
+   * Stream line output, showing a waiting indicator for each line until the next one occurs
+   *
+   * @param lines
+   * @param config
+   * @returns
+   */
+  async streamLinesWithWaiting(lines: AsyncIterable<string | undefined>, config: TerminalWaitingConfig): Promise<void> {
+    if (!this.interactive) {
+      for await (const line of lines) {
+        if (line !== undefined) {
+          const out = config.committedPrefix ? `${config.committedPrefix} ${line}` : line;
+          await this.writeLines(out);
+        }
+      }
+    } else {
+      return TerminalOperation.streamLinesWithWaiting(this, lines, { position: 'bottom', ...config });
+    }
+  }
+
+  /**
+   * Consumes a stream, of events, tied to specific list indices, and updates in place
+   */
+  async streamList<T>(source: AsyncIterable<T>, resolve: MapFn<T, TerminalTableEvent>, config: TerminalTableConfig = {}): Promise<void> {
+    const resolved = IterableUtil.map(source, resolve);
+
+    await this.writeLines(...(config.header ?? []));
+
+    if (!this.interactive) {
+      const isDone = IterableUtil.filter(resolved, ev => !!ev.done);
+      if (config.forceNonInteractiveOrder) {
+        await this.writeLines(...(await IterableUtil.drain(isDone)).map(x => x.text), '');
+      } else {
+        await IterableUtil.drain(IterableUtil.map(isDone, ev => this.writeLines(ev.text)));
+        await this.writeLines('');
+      }
+      return;
+    }
+
+    await TerminalOperation.streamList(this, resolved);
+  }
+
+  /**
+   * Streams an iterable to a specific location, with support for non-interactive ttys
+   */
+  async streamToPosition<T>(source: AsyncIterable<T>, resolve: MapFn<T, string>, config?: TerminalStreamPositionConfig): Promise<void> {
+    if (!this.interactive) {
+      if (config?.staticMessage) {
+        await this.writeLines(config.staticMessage);
+      }
+      await IterableUtil.drain(source);
+      return;
+    }
+    return TerminalOperation.streamToPosition(this, IterableUtil.map(source, resolve), config);
+  }
+
+  /**
+   * Track progress of an asynchronous iterator, allowing the showing of a progress bar if the stream produces idx and total
+   */
+  async trackProgress<T, V extends TerminalProgressEvent>(
+    source: AsyncIterable<T>, resolve: MapFn<T, V>, config?: TerminalProgressConfig
+  ): Promise<void> {
+    const render = TerminalOperation.buildProgressBar(this, config?.style ?? { background: 'limeGreen', text: 'black' });
+    return this.streamToPosition(source, async (v, i) => render(await resolve(v, i)), config);
+  }
+
+  /** Creates a colorer function */
+  colorer(style: TermStyleInput | [light: TermStyleInput, dark: TermStyleInput]): TermColorFn {
+    return ColorOutputUtil.colorer(this, style);
+  }
+
+  /** Creates a color palette based on input styles */
+  palette<P extends TermColorPaletteInput>(input: P): TermColorPalette<P> {
+    return ColorOutputUtil.palette(this, input);
+  }
+
+  /** Convenience method to creates a color template function based on input styles */
+  templateFunction<P extends TermColorPaletteInput>(input: P): (key: keyof P, val: Prim) => string {
+    return ColorOutputUtil.templateFunction(this, input);
+  }
+}
+
+export const GlobalTerminal = new Terminal({ output: process.stdout });

package/src/types.ts

@@ -0,0 +1,33 @@
+import tty from 'tty';
+
+export type Indexed = { idx: number };
+export type DelayedConfig = { initialDelay?: number, cycleDelay?: number };
+
+type I = number;
+export type RGB = [r: I, g: I, b: I] | (readonly [r: I, g: I, b: I]);
+export type TermCoord = { x: number, y: number };
+export type TermLinePosition = 'top' | 'bottom' | 'inline';
+export type TermColorField = 'foregroundColor' | 'backgroundColor';
+
+export type TerminalTableEvent = { idx: number, text: string, done?: boolean };
+export type TerminalTableConfig = { header?: string[], forceNonInteractiveOrder?: boolean };
+export type TerminalProgressEvent = { idx: number, total?: number, text?: string };
+export type TerminalProgressRender = (ev: TerminalProgressEvent) => string;
+export type TerminalStreamingConfig = { position?: TermLinePosition, clearOnFinish?: boolean, at?: TermCoord };
+export type TerminalWaitingConfig = { end?: boolean, committedPrefix?: string } & TerminalStreamingConfig & DelayedConfig;
+
+export type TermColorLevel = 0 | 1 | 2 | 3;
+export type TermColorScheme = 'dark' | 'light';
+
+export type TermState = {
+  interactive: boolean;
+  height: number;
+  width: number;
+  input: tty.ReadStream;
+  output: tty.WriteStream;
+  colorLevel: TermColorLevel;
+  backgroundScheme: TermColorScheme;
+  getCursorPosition(): Promise<TermCoord>;
+};
+
+export type TermQuery<T> = { query: () => string, response: (inp: Buffer) => T };

package/src/writer.ts

@@ -0,0 +1,146 @@
+import { ANSICodes } from './codes';
+import { TermCoord, TermState } from './types';
+
+const boundIndex = (v: number, size: number): number => {
+  if (v < 0) {
+    v = size + v;
+  }
+  return Math.max(Math.min(v, size - 1), 0);
+};
+
+/**
+ * Buffered/batched writer.  Meant to be similar to readline.Readline, but with more general writing support and extensibility
+ */
+export class TerminalWriter {
+
+  static for(term: TermState): TerminalWriter {
+    return new TerminalWriter(term);
+  }
+
+  #queue: (string | number)[] = [];
+  #term: TermState;
+  #restoreOnCommit = false;
+
+  constructor(term: TermState) {
+    this.#term = term;
+  }
+
+  /** Restore on commit */
+  restoreOnCommit(): this {
+    this.#restoreOnCommit = true;
+    return this;
+  }
+
+  commit(restorePosition: boolean = this.#restoreOnCommit): Promise<void> {
+    const q = this.#queue.filter(x => x !== undefined);
+    this.#queue = [];
+    if (q.length && restorePosition) {
+      q.unshift(ANSICodes.POSITION_SAVE());
+      q.push(ANSICodes.POSITION_RESTORE());
+    }
+    return q.length ? new Promise(r => this.#term.output.write(q.join(''), () => r())) : Promise.resolve();
+  }
+
+  write(...text: (string | number)[]): this {
+    this.#queue.push(...text);
+    return this;
+  }
+
+  /** Stores current cursor position, if called multiple times before restore, last one ones */
+  storePosition(): this {
+    return this.write(ANSICodes.POSITION_SAVE());
+  }
+
+  /** Restores cursor position, will not behave correctly if nested  */
+  restorePosition(): this {
+    return this.write(ANSICodes.POSITION_RESTORE());
+  }
+
+  /** Rewrite a single line in the stream  */
+  rewriteLine(text: string): this {
+    return this.setPosition({ x: 0 }).write(text);
+  }
+
+  /** Clear line, -1 (left), 0 (both), 1 (right), from current cursor */
+  clearLine(dir: -1 | 0 | 1 = 0): this {
+    return this.write(ANSICodes.ERASE_LINE(dir === 0 ? 2 : (dir === 1 ? 0 : 1)));
+  }
+
+  /** Set position */
+  setPosition({ x = 0, y }: Partial<TermCoord>): this {
+    if (y !== undefined) {
+      y = boundIndex(y, this.#term.output.rows);
+    }
+    x = boundIndex(x, this.#term.output.columns);
+    if (y !== undefined) {
+      return this.write(ANSICodes.POSITION_SET(y + 1, x + 1));
+    } else {
+      return this.write(ANSICodes.COLUMN_SET(x + 1));
+    }
+  }
+
+  /** Relative movement */
+  changePosition({ x, y }: Partial<TermCoord>): this {
+    if (x) {
+      this.write(ANSICodes.CURSOR_DX(x));
+    }
+    if (y) {
+      this.write(ANSICodes.CURSOR_DY(y));
+    }
+    return this;
+  }
+
+  /** Write single line */
+  writeLine(line: string = ''): this {
+    return this.write(`${line}\n`);
+  }
+
+  /** Write multiple lines */
+  writeLines(lines: (string | undefined)[], clear = false): this {
+    lines = lines.filter(x => x !== undefined);
+    let text = lines.join('\n');
+    if (text.length > 0) {
+      if (clear) {
+        text = text.replaceAll('\n', `${ANSICodes.ERASE_LINE(0)}\n`);
+      }
+      text = `${text}\n`;
+    }
+    return this.write(text);
+  }
+
+  /** Show cursor */
+  showCursor(): this {
+    return this.write(ANSICodes.SHOW_CURSOR());
+  }
+
+  /** Hide cursor */
+  hideCursor(): this {
+    return this.write(ANSICodes.HIDE_CURSOR());
+  }
+
+  /** Set scrolling range */
+  scrollRange({ start, end }: { start?: number, end?: number }): this {
+    start = boundIndex(start ?? 0, this.#term.output.rows);
+    end = boundIndex(end ?? -1, this.#term.output.rows);
+    return this.write(ANSICodes.SCROLL_RANGE_SET(start + 1, end + 1));
+  }
+
+  /** Clear scrolling range */
+  scrollRangeClear(): this {
+    return this.write(ANSICodes.SCROLL_RANGE_CLEAR());
+  }
+
+  /** Scrolling window y <=0 - up,  else down */
+  scrollY(y: number): this {
+    return this.write(ANSICodes.SCROLL_WINDOW(y));
+  }
+
+  /** Reset */
+  reset(): this {
+    return this
+      .write(ANSICodes.POSITION_SAVE())
+      .write(ANSICodes.SHOW_CURSOR())
+      .write(ANSICodes.SCROLL_RANGE_CLEAR())
+      .write(ANSICodes.POSITION_RESTORE());
+  }
+}