@silvery/term 0.3.0

package/src/adapters/yoga-adapter.ts

@@ -0,0 +1,370 @@
+/**
+ * Yoga Layout Engine Adapter
+ *
+ * Wraps yoga-wasm-web to implement the LayoutEngine interface.
+ */
+
+import type {
+  Align,
+  Direction,
+  Display,
+  Edge,
+  FlexDirection,
+  Gutter,
+  Justify,
+  Overflow,
+  PositionType,
+  Wrap,
+  Yoga,
+  Node as YogaNode,
+} from "yoga-wasm-web"
+import type {
+  AlignValue,
+  DirectionValue,
+  DisplayValue,
+  EdgeValue,
+  FlexDirectionValue,
+  GutterValue,
+  JustifyValue,
+  LayoutConstants,
+  LayoutEngine,
+  LayoutNode,
+  MeasureFunc,
+  MeasureMode,
+  MeasureModeValue,
+  OverflowValue,
+  PositionTypeValue,
+  WrapValue,
+} from "../layout-engine"
+
+// ============================================================================
+// Yoga Node Adapter
+// ============================================================================
+
+/**
+ * Wraps a Yoga node to implement LayoutNode interface.
+ */
+class YogaNodeAdapter implements LayoutNode {
+  private node: YogaNode
+  private yoga: Yoga
+  private hasMeasureFunc = false
+
+  constructor(node: YogaNode, yoga: Yoga) {
+    this.node = node
+    this.yoga = yoga
+  }
+
+  /** Get the underlying Yoga node (for tree operations) */
+  getYogaNode(): YogaNode {
+    return this.node
+  }
+
+  // Tree operations
+  insertChild(child: LayoutNode, index: number): void {
+    const yogaChild = (child as YogaNodeAdapter).getYogaNode()
+    this.node.insertChild(yogaChild, index)
+  }
+
+  removeChild(child: LayoutNode): void {
+    const yogaChild = (child as YogaNodeAdapter).getYogaNode()
+    this.node.removeChild(yogaChild)
+  }
+
+  free(): void {
+    this.node.free()
+  }
+
+  // Measure function
+  setMeasureFunc(measureFunc: MeasureFunc): void {
+    this.hasMeasureFunc = true
+    this.node.setMeasureFunc((width, widthMode, height, heightMode) => {
+      const widthModeStr = this.measureModeToString(widthMode)
+      const heightModeStr = this.measureModeToString(heightMode)
+      return measureFunc(width, widthModeStr, height, heightModeStr)
+    })
+  }
+
+  // Dirty tracking - forces layout recalculation
+  // Yoga only allows markDirty() on leaf nodes with measure functions
+  markDirty(): void {
+    if (this.hasMeasureFunc) {
+      this.node.markDirty()
+    }
+  }
+
+  private measureModeToString(mode: number): MeasureMode {
+    if (mode === this.yoga.MEASURE_MODE_EXACTLY) return "exactly"
+    if (mode === this.yoga.MEASURE_MODE_AT_MOST) return "at-most"
+    return "undefined"
+  }
+
+  // Dimension setters
+  setWidth(value: number): void {
+    this.node.setWidth(value)
+  }
+  setWidthPercent(value: number): void {
+    this.node.setWidthPercent(value)
+  }
+  setWidthAuto(): void {
+    this.node.setWidthAuto()
+  }
+  setHeight(value: number): void {
+    this.node.setHeight(value)
+  }
+  setHeightPercent(value: number): void {
+    this.node.setHeightPercent(value)
+  }
+  setHeightAuto(): void {
+    this.node.setHeightAuto()
+  }
+  setMinWidth(value: number): void {
+    this.node.setMinWidth(value)
+  }
+  setMinWidthPercent(value: number): void {
+    this.node.setMinWidthPercent(value)
+  }
+  setMinHeight(value: number): void {
+    this.node.setMinHeight(value)
+  }
+  setMinHeightPercent(value: number): void {
+    this.node.setMinHeightPercent(value)
+  }
+  setMaxWidth(value: number): void {
+    this.node.setMaxWidth(value)
+  }
+  setMaxWidthPercent(value: number): void {
+    this.node.setMaxWidthPercent(value)
+  }
+  setMaxHeight(value: number): void {
+    this.node.setMaxHeight(value)
+  }
+  setMaxHeightPercent(value: number): void {
+    this.node.setMaxHeightPercent(value)
+  }
+
+  // Flex properties
+  setFlexGrow(value: number): void {
+    this.node.setFlexGrow(value)
+  }
+  setFlexShrink(value: number): void {
+    this.node.setFlexShrink(value)
+  }
+  setFlexBasis(value: number): void {
+    this.node.setFlexBasis(value)
+  }
+  setFlexBasisPercent(value: number): void {
+    this.node.setFlexBasisPercent(value)
+  }
+  setFlexBasisAuto(): void {
+    this.node.setFlexBasisAuto()
+  }
+  setFlexDirection(direction: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded FlexDirection type
+    this.node.setFlexDirection(direction as FlexDirection)
+  }
+  setFlexWrap(wrap: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Wrap type
+    this.node.setFlexWrap(wrap as Wrap)
+  }
+
+  // Alignment
+  setAlignItems(align: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Align type
+    this.node.setAlignItems(align as Align)
+  }
+  setAlignSelf(align: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Align type
+    this.node.setAlignSelf(align as Align)
+  }
+  setAlignContent(align: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Align type
+    this.node.setAlignContent(align as Align)
+  }
+  setJustifyContent(justify: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Justify type
+    this.node.setJustifyContent(justify as Justify)
+  }
+
+  // Spacing
+  setPadding(edge: number, value: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Edge type
+    this.node.setPadding(edge as Edge, value)
+  }
+  setMargin(edge: number, value: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Edge type
+    this.node.setMargin(edge as Edge, value)
+  }
+  setBorder(edge: number, value: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Edge type
+    this.node.setBorder(edge as Edge, value)
+  }
+  setGap(gutter: number, value: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Gutter type
+    this.node.setGap(gutter as Gutter, value)
+  }
+
+  // Display & Position
+  setDisplay(display: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Display type
+    this.node.setDisplay(display as Display)
+  }
+  setPositionType(positionType: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded PositionType type
+    this.node.setPositionType(positionType as PositionType)
+  }
+  setPosition(edge: number, value: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Edge type
+    this.node.setPosition(edge as Edge, value)
+  }
+  setPositionPercent(edge: number, value: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Edge type
+    this.node.setPositionPercent(edge as Edge, value)
+  }
+  setOverflow(overflow: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Overflow type
+    this.node.setOverflow(overflow as Overflow)
+  }
+
+  // Aspect Ratio
+  setAspectRatio(value: number): void {
+    this.node.setAspectRatio(value)
+  }
+
+  // Layout calculation
+  calculateLayout(width: number, height: number, direction?: number): void {
+    // LayoutEngine uses plain numbers; Yoga uses branded Direction type
+    this.node.calculateLayout(width, height, (direction ?? this.yoga.DIRECTION_LTR) as Direction)
+  }
+
+  // Layout results
+  getComputedLeft(): number {
+    return this.node.getComputedLeft()
+  }
+  getComputedTop(): number {
+    return this.node.getComputedTop()
+  }
+  getComputedWidth(): number {
+    return this.node.getComputedWidth()
+  }
+  getComputedHeight(): number {
+    return this.node.getComputedHeight()
+  }
+}
+
+// ============================================================================
+// Yoga Layout Engine
+// ============================================================================
+
+/**
+ * Layout engine implementation using Yoga (WASM).
+ */
+export class YogaLayoutEngine implements LayoutEngine {
+  private yoga: Yoga
+  private _constants: LayoutConstants
+
+  constructor(yoga: Yoga) {
+    this.yoga = yoga
+    // Cast Yoga's branded types to our LayoutEngine branded types at the adapter boundary
+    this._constants = {
+      // Flex Direction
+      FLEX_DIRECTION_COLUMN: yoga.FLEX_DIRECTION_COLUMN as unknown as FlexDirectionValue,
+      FLEX_DIRECTION_COLUMN_REVERSE: yoga.FLEX_DIRECTION_COLUMN_REVERSE as unknown as FlexDirectionValue,
+      FLEX_DIRECTION_ROW: yoga.FLEX_DIRECTION_ROW as unknown as FlexDirectionValue,
+      FLEX_DIRECTION_ROW_REVERSE: yoga.FLEX_DIRECTION_ROW_REVERSE as unknown as FlexDirectionValue,
+
+      // Wrap
+      WRAP_NO_WRAP: yoga.WRAP_NO_WRAP as unknown as WrapValue,
+      WRAP_WRAP: yoga.WRAP_WRAP as unknown as WrapValue,
+      WRAP_WRAP_REVERSE: yoga.WRAP_WRAP_REVERSE as unknown as WrapValue,
+
+      // Align
+      ALIGN_AUTO: yoga.ALIGN_AUTO as unknown as AlignValue,
+      ALIGN_FLEX_START: yoga.ALIGN_FLEX_START as unknown as AlignValue,
+      ALIGN_CENTER: yoga.ALIGN_CENTER as unknown as AlignValue,
+      ALIGN_FLEX_END: yoga.ALIGN_FLEX_END as unknown as AlignValue,
+      ALIGN_STRETCH: yoga.ALIGN_STRETCH as unknown as AlignValue,
+      ALIGN_BASELINE: yoga.ALIGN_BASELINE as unknown as AlignValue,
+      ALIGN_SPACE_BETWEEN: yoga.ALIGN_SPACE_BETWEEN as unknown as AlignValue,
+      ALIGN_SPACE_AROUND: yoga.ALIGN_SPACE_AROUND as unknown as AlignValue,
+      ALIGN_SPACE_EVENLY: yoga.ALIGN_SPACE_EVENLY as unknown as AlignValue,
+
+      // Justify
+      JUSTIFY_FLEX_START: yoga.JUSTIFY_FLEX_START as unknown as JustifyValue,
+      JUSTIFY_CENTER: yoga.JUSTIFY_CENTER as unknown as JustifyValue,
+      JUSTIFY_FLEX_END: yoga.JUSTIFY_FLEX_END as unknown as JustifyValue,
+      JUSTIFY_SPACE_BETWEEN: yoga.JUSTIFY_SPACE_BETWEEN as unknown as JustifyValue,
+      JUSTIFY_SPACE_AROUND: yoga.JUSTIFY_SPACE_AROUND as unknown as JustifyValue,
+      JUSTIFY_SPACE_EVENLY: yoga.JUSTIFY_SPACE_EVENLY as unknown as JustifyValue,
+
+      // Edge
+      EDGE_LEFT: yoga.EDGE_LEFT as unknown as EdgeValue,
+      EDGE_TOP: yoga.EDGE_TOP as unknown as EdgeValue,
+      EDGE_RIGHT: yoga.EDGE_RIGHT as unknown as EdgeValue,
+      EDGE_BOTTOM: yoga.EDGE_BOTTOM as unknown as EdgeValue,
+      EDGE_HORIZONTAL: yoga.EDGE_HORIZONTAL as unknown as EdgeValue,
+      EDGE_VERTICAL: yoga.EDGE_VERTICAL as unknown as EdgeValue,
+      EDGE_ALL: yoga.EDGE_ALL as unknown as EdgeValue,
+
+      // Gutter
+      GUTTER_COLUMN: yoga.GUTTER_COLUMN as unknown as GutterValue,
+      GUTTER_ROW: yoga.GUTTER_ROW as unknown as GutterValue,
+      GUTTER_ALL: yoga.GUTTER_ALL as unknown as GutterValue,
+
+      // Display
+      DISPLAY_FLEX: yoga.DISPLAY_FLEX as unknown as DisplayValue,
+      DISPLAY_NONE: yoga.DISPLAY_NONE as unknown as DisplayValue,
+
+      // Position Type
+      POSITION_TYPE_STATIC: yoga.POSITION_TYPE_STATIC as unknown as PositionTypeValue,
+      POSITION_TYPE_RELATIVE: yoga.POSITION_TYPE_RELATIVE as unknown as PositionTypeValue,
+      POSITION_TYPE_ABSOLUTE: yoga.POSITION_TYPE_ABSOLUTE as unknown as PositionTypeValue,
+
+      // Overflow
+      OVERFLOW_VISIBLE: yoga.OVERFLOW_VISIBLE as unknown as OverflowValue,
+      OVERFLOW_HIDDEN: yoga.OVERFLOW_HIDDEN as unknown as OverflowValue,
+      OVERFLOW_SCROLL: yoga.OVERFLOW_SCROLL as unknown as OverflowValue,
+
+      // Direction
+      DIRECTION_LTR: yoga.DIRECTION_LTR as unknown as DirectionValue,
+
+      // Measure Mode
+      MEASURE_MODE_UNDEFINED: yoga.MEASURE_MODE_UNDEFINED as unknown as MeasureModeValue,
+      MEASURE_MODE_EXACTLY: yoga.MEASURE_MODE_EXACTLY as unknown as MeasureModeValue,
+      MEASURE_MODE_AT_MOST: yoga.MEASURE_MODE_AT_MOST as unknown as MeasureModeValue,
+    }
+  }
+
+  createNode(): LayoutNode {
+    return new YogaNodeAdapter(this.yoga.Node.create(), this.yoga)
+  }
+
+  get constants(): LayoutConstants {
+    return this._constants
+  }
+
+  get name(): string {
+    return "yoga"
+  }
+}
+
+// ============================================================================
+// Initialization Helper
+// ============================================================================
+
+/**
+ * Create a Yoga layout engine from an initialized Yoga instance.
+ */
+export function createYogaEngine(yoga: Yoga): YogaLayoutEngine {
+  return new YogaLayoutEngine(yoga)
+}
+
+/**
+ * Initialize Yoga and create a layout engine.
+ * Uses yoga-wasm-web/auto which automatically selects the right implementation.
+ */
+export async function initYogaEngine(): Promise<YogaLayoutEngine> {
+  const { default: yoga } = (await import("yoga-wasm-web/auto")) as {
+    default: Yoga
+  }
+  return new YogaLayoutEngine(yoga)
+}

package/src/ansi/ansi.ts

@@ -0,0 +1,251 @@
+/**
+ * ANSI terminal control helpers.
+ *
+ * Pure string-returning functions for terminal control sequences.
+ * No side effects, no stdout writes -- consumers compose and write.
+ *
+ * Covers: screen management, cursor control, scroll regions,
+ * mouse tracking, keyboard protocols, and bracketed paste.
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
+ * @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ */
+
+// =============================================================================
+// Base Constants
+// =============================================================================
+
+/** Escape character (0x1B) */
+const ESC = "\x1b"
+
+/** Control Sequence Introducer: ESC [ */
+const CSI = `${ESC}[`
+
+/** Operating System Command: ESC ] */
+const OSC = `${ESC}]`
+
+/** Bell character (0x07) -- used as string terminator in OSC sequences */
+const BEL = "\x07"
+
+// =============================================================================
+// Screen
+// =============================================================================
+
+/**
+ * Enter the alternate screen buffer (DEC private mode 1049).
+ * The alternate screen preserves the main scrollback buffer.
+ */
+export function enterAltScreen(): string {
+  return `${CSI}?1049h`
+}
+
+/**
+ * Leave the alternate screen buffer and restore the main screen.
+ */
+export function leaveAltScreen(): string {
+  return `${CSI}?1049l`
+}
+
+/**
+ * Clear the entire screen (ED 2 -- Erase in Display, all).
+ */
+export function clearScreen(): string {
+  return `${CSI}2J`
+}
+
+/**
+ * Clear the current line (EL 2 -- Erase in Line, entire line).
+ */
+export function clearLine(): string {
+  return `${CSI}2K`
+}
+
+// =============================================================================
+// Cursor
+// =============================================================================
+
+/**
+ * Move cursor to an absolute position.
+ * Uses 0-indexed row/col; converts to 1-indexed CUP (Cursor Position).
+ */
+export function cursorTo(row: number, col: number): string {
+  return `${CSI}${row + 1};${col + 1}H`
+}
+
+/**
+ * Move cursor to the home position (top-left, row 0, col 0).
+ */
+export function cursorHome(): string {
+  return `${CSI}H`
+}
+
+/**
+ * Hide the cursor (DEC private mode 25, reset).
+ */
+export function cursorHide(): string {
+  return `${CSI}?25l`
+}
+
+/**
+ * Show the cursor (DEC private mode 25, set).
+ */
+export function cursorShow(): string {
+  return `${CSI}?25h`
+}
+
+/**
+ * Set cursor style via DECSCUSR (DEC Set Cursor Style).
+ *
+ * | Style       | Code | Description              |
+ * | ----------- | ---- | ------------------------ |
+ * | block       | 2    | Steady block             |
+ * | underline   | 4    | Steady underline         |
+ * | beam        | 6    | Steady bar (vertical)    |
+ *
+ * Steady variants are used (even codes). Blinking would be odd codes.
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, iTerm2, Alacritty, foot.
+ */
+export function cursorStyle(style: "block" | "underline" | "beam"): string {
+  const code = style === "block" ? 2 : style === "underline" ? 4 : 6
+  return `${CSI}${code} q`
+}
+
+// =============================================================================
+// Terminal
+// =============================================================================
+
+/**
+ * Set the terminal window title using OSC 2 (window title only).
+ * Does not affect icon title. Widely supported.
+ */
+export function setTitle(title: string): string {
+  return `${OSC}2;${title}${BEL}`
+}
+
+/**
+ * Enable mouse tracking.
+ *
+ * Enables three modes for full mouse support:
+ * - 1000: Basic button press/release reporting
+ * - 1002: Button-event tracking (drag events)
+ * - 1006: SGR extended coordinates (supports >223 columns)
+ */
+export function enableMouse(): string {
+  return `${CSI}?1000h${CSI}?1002h${CSI}?1006h`
+}
+
+/**
+ * Disable mouse tracking.
+ *
+ * Disables in reverse order of enabling.
+ */
+export function disableMouse(): string {
+  return `${CSI}?1006l${CSI}?1002l${CSI}?1000l`
+}
+
+/**
+ * Enable bracketed paste mode (DEC private mode 2004).
+ * Terminal wraps pasted text with markers so the app can distinguish
+ * paste from typed input.
+ */
+export function enableBracketedPaste(): string {
+  return `${CSI}?2004h`
+}
+
+/**
+ * Disable bracketed paste mode.
+ */
+export function disableBracketedPaste(): string {
+  return `${CSI}?2004l`
+}
+
+/**
+ * Enable synchronized update mode (DEC private mode 2026).
+ * Tells the terminal to batch output and paint atomically, preventing tearing.
+ * Supported by: Ghostty, Kitty, WezTerm, iTerm2, Foot, Alacritty 0.14+, tmux 3.2+.
+ * Terminals that don't support it safely ignore this sequence.
+ */
+export function enableSyncUpdate(): string {
+  return `${CSI}?2026h`
+}
+
+/**
+ * Disable synchronized update mode.
+ * Sending this when not in sync mode is a harmless no-op.
+ */
+export function disableSyncUpdate(): string {
+  return `${CSI}?2026l`
+}
+
+// =============================================================================
+// Scroll
+// =============================================================================
+
+/**
+ * Set the terminal scroll region (DECSTBM -- DEC Set Top and Bottom Margins).
+ * Uses 0-indexed top/bottom; converts to 1-indexed for the terminal.
+ *
+ * Supported by most modern terminals: xterm, iTerm2, Kitty, Ghostty, WezTerm, etc.
+ */
+export function setScrollRegion(top: number, bottom: number): string {
+  return `${CSI}${top + 1};${bottom + 1}r`
+}
+
+/**
+ * Reset the scroll region to the full terminal height.
+ */
+export function resetScrollRegion(): string {
+  return `${CSI}r`
+}
+
+/**
+ * Scroll content up by N lines within the current scroll region (SU).
+ * New blank lines appear at the bottom.
+ */
+export function scrollUp(n: number): string {
+  if (n <= 0) return ""
+  return `${CSI}${n}S`
+}
+
+/**
+ * Scroll content down by N lines within the current scroll region (SD).
+ * New blank lines appear at the top.
+ */
+export function scrollDown(n: number): string {
+  if (n <= 0) return ""
+  return `${CSI}${n}T`
+}
+
+// =============================================================================
+// Keyboard
+// =============================================================================
+
+/**
+ * Enable the Kitty keyboard protocol (push mode).
+ *
+ * Sends CSI > flags u to opt into the specified modes.
+ * Supported by: Ghostty, Kitty, WezTerm, foot. Ignored by unsupported terminals.
+ *
+ * Flags are a bitfield:
+ *
+ * | Flag | Bit | Description                               |
+ * | ---- | --- | ----------------------------------------- |
+ * | 1    | 0   | Disambiguate escape codes                 |
+ * | 2    | 1   | Report event types (press/repeat/release)  |
+ * | 4    | 2   | Report alternate keys                     |
+ * | 8    | 3   | Report all keys as escape codes           |
+ * | 16   | 4   | Report associated text                    |
+ *
+ * @param flags Bitfield of Kitty keyboard flags
+ */
+export function enableKittyKeyboard(flags: number): string {
+  return `${CSI}>${flags}u`
+}
+
+/**
+ * Disable the Kitty keyboard protocol (pop mode stack).
+ * Sends CSI < u to restore the previous keyboard mode.
+ */
+export function disableKittyKeyboard(): string {
+  return `${CSI}<u`
+}

package/src/ansi/constants.ts

@@ -0,0 +1,76 @@
+/**
+ * ANSI escape code constants for extended terminal features.
+ *
+ * @see https://sw.kovidgoyal.net/kitty/underlines/
+ * @see https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+ */
+
+// =============================================================================
+// Extended Underline Styles (ISO 8613-6 / ECMA-48)
+// =============================================================================
+
+/**
+ * Extended underline style codes.
+ * Uses colon-separated parameters (ISO 8613-6): \x1b[4:Nm
+ */
+export const UNDERLINE_CODES = {
+  /** No underline */
+  none: "\x1b[4:0m",
+  /** Standard single underline */
+  single: "\x1b[4:1m",
+  /** Double underline (two parallel lines) */
+  double: "\x1b[4:2m",
+  /** Curly/wavy underline (spell check style) */
+  curly: "\x1b[4:3m",
+  /** Dotted underline */
+  dotted: "\x1b[4:4m",
+  /** Dashed underline */
+  dashed: "\x1b[4:5m",
+  /** Reset extended underline (same as none) */
+  reset: "\x1b[4:0m",
+} as const
+
+// =============================================================================
+// Standard Underline (Fallback)
+// =============================================================================
+
+/** Standard underline on (SGR 4) - works on all terminals */
+export const UNDERLINE_STANDARD = "\x1b[4m"
+
+/** Standard underline off (SGR 24) */
+export const UNDERLINE_RESET_STANDARD = "\x1b[24m"
+
+// =============================================================================
+// Underline Color (SGR 58/59)
+// =============================================================================
+
+/**
+ * Reset underline color to default (SGR 59)
+ */
+export const UNDERLINE_COLOR_RESET = "\x1b[59m"
+
+/**
+ * Build underline color escape code for RGB values.
+ * Format: \x1b[58:2::r:g:bm (SGR 58 with RGB color space)
+ */
+export function buildUnderlineColorCode(r: number, g: number, b: number): string {
+  return `\x1b[58:2::${r}:${g}:${b}m`
+}
+
+// =============================================================================
+// Hyperlinks (OSC 8)
+// =============================================================================
+
+/** OSC 8 hyperlink start sequence */
+export const HYPERLINK_START = "\x1b]8;;"
+
+/** OSC 8 hyperlink end sequence (ST - String Terminator) */
+export const HYPERLINK_END = "\x1b\\"
+
+/**
+ * Build a hyperlink escape sequence.
+ * Format: \x1b]8;;<url>\x1b\\ <text> \x1b]8;;\x1b\\
+ */
+export function buildHyperlink(text: string, url: string): string {
+  return `${HYPERLINK_START}${url}${HYPERLINK_END}${text}${HYPERLINK_START}${HYPERLINK_END}`
+}