@visual-z/xeno 0.2.1 → 0.4.0

package/src/tui/keys.ts

@@ -1,378 +0,0 @@
-/**
- * Key decoding as a pure function: bytes in, events plus an unconsumed
- * prefix out.
- *
- * Escape sequences are split by pty and TCP buffering at arbitrary
- * boundaries -- `\x1b[A` (up-arrow) can arrive as `\x1b[` then `A`. A
- * callback state machine can only be shown to survive that by luck; a
- * function that returns the leftover prefix can be shown by a test.
- */
-
-import { assertNever } from "./exhaustive.ts";
-
-/**
- * xterm ctlseqs modifiers, attached only when a recognised bit is set.
- * Absent means unmodified -- `{ type: "left" }` stays that shape so
- * existing matches keep working. Meta (bit 3) is not modelled.
- */
-export interface KeyMods {
-  readonly shift?: boolean;
-  readonly alt?: boolean;
-  readonly ctrl?: boolean;
-}
-
-export type Key =
-  | { type: "char"; grapheme: string }
-  | { type: "enter"; shift: boolean }
-  | { type: "backspace" }
-  | { type: "delete"; mods?: KeyMods }
-  | { type: "tab"; shift?: boolean }
-  | { type: "escape" }
-  | { type: "up"; mods?: KeyMods }
-  | { type: "down"; mods?: KeyMods }
-  | { type: "left"; mods?: KeyMods }
-  | { type: "right"; mods?: KeyMods }
-  | { type: "home"; mods?: KeyMods }
-  | { type: "end"; mods?: KeyMods }
-  | { type: "pageup"; mods?: KeyMods }
-  | { type: "pagedown"; mods?: KeyMods }
-  | { type: "ctrl"; key: string; shift?: boolean }
-  | { type: "alt"; key: string };
-
-export interface DecodeResult {
-  events: Key[];
-  rest: Uint8Array;
-}
-
-/**
- * 50ms. Measured convention, not a standard: xterm, libuv and readline all
- * pick a few tens of milliseconds to decide that a lone ESC is the Escape
- * key rather than the start of a CSI. Too short and a slow CSI is split into
- * Escape plus junk; too long and Escape-to-interrupt feels sticky. The
- * decoder itself is still a pure function -- the caller passes `escTimedOut`
- * after it has waited, because a timeout is a clock and a clock is not pure.
- */
-export const ESCAPE_TIMEOUT_MS = 50;
-
-type Seq =
-  | { kind: "csi"; params: number[]; final: string }
-  | { kind: "ss3"; final: string }
-  | { kind: "alt"; grapheme: string };
-
-type Taken = { key: Key | null; next: number };
-
-/**
- * Stable chord spelling for the keymap (`ctrl+shift+x`). Alt+Enter arrives
- * as `{ type: "alt", key: "\\r" }` on some terminals; that must still be
- * `alt+enter` or a rebound follow-up never matches.
- */
-export function formatTuiKey(key: Key): string {
-  switch (key.type) {
-    case "char":
-      return key.grapheme.length === 1 ? key.grapheme.toLowerCase() : key.grapheme;
-    case "enter":
-      return key.shift ? "shift+enter" : "enter";
-    case "backspace":
-      return "backspace";
-    case "delete":
-      return withMods(key.mods, "delete");
-    case "tab":
-      return key.shift === true ? "shift+tab" : "tab";
-    case "escape":
-      return "escape";
-    case "up":
-    case "down":
-    case "left":
-    case "right":
-    case "home":
-    case "end":
-      return withMods(key.mods, key.type);
-    case "pageup":
-      return withMods(key.mods, "pageup");
-    case "pagedown":
-      return withMods(key.mods, "pagedown");
-    case "ctrl":
-      return key.shift === true
-        ? `ctrl+shift+${key.key.toLowerCase()}`
-        : `ctrl+${key.key.toLowerCase()}`;
-    case "alt": {
-      const k = key.key === "\r" || key.key === "\n" ? "enter" : key.key.toLowerCase();
-      return `alt+${k}`;
-    }
-    default:
-      return assertNever(key, "formatTuiKey");
-  }
-}
-
-function withMods(mods: KeyMods | undefined, key: string): string {
-  const parts: string[] = [];
-  if (mods?.ctrl === true) parts.push("ctrl");
-  if (mods?.alt === true) parts.push("alt");
-  if (mods?.shift === true) parts.push("shift");
-  parts.push(key);
-  return parts.join("+");
-}
-
-export function decodeKeys(bytes: Uint8Array, opts: { escTimedOut?: boolean } = {}): DecodeResult {
-  const events: Key[] = [];
-  let i = 0;
-  const timedOut = opts.escTimedOut === true;
-  while (i < bytes.length) {
-    const taken = take(bytes, i, timedOut);
-    if (taken === null) break;
-    if (taken.key !== null) events.push(taken.key);
-    i = taken.next;
-  }
-  return { events, rest: bytes.slice(i) };
-}
-
-function take(bytes: Uint8Array, i: number, timedOut: boolean): Taken | null {
-  const b = bytes[i]!;
-
-  if (b === 0x1b) {
-    if (i + 1 >= bytes.length) {
-      return timedOut ? { key: { type: "escape" }, next: i + 1 } : null;
-    }
-    const next = bytes[i + 1]!;
-    if (next === 0x5b) return takeCsi(bytes, i);
-    if (next === 0x4f) return takeSs3(bytes, i);
-    const utf = takeUtf8(bytes, i + 1);
-    if (utf === null) return null;
-    return seqToTaken({ kind: "alt", grapheme: utf.grapheme }, utf.next);
-  }
-
-  if (b === 0x0d || b === 0x0a) return { key: { type: "enter", shift: false }, next: i + 1 };
-  if (b === 0x09) return { key: { type: "tab" }, next: i + 1 };
-  if (b === 0x7f) return { key: { type: "backspace" }, next: i + 1 };
-  if (b < 0x20) {
-    // C0 minus ESC/CR/LF/TAB, already handled. 0x01..0x1A are Ctrl+a..z
-    // (Ctrl+H is 0x08, distinct from DEL-as-Backspace).
-    if (b >= 0x01 && b <= 0x1a) {
-      return { key: { type: "ctrl", key: String.fromCharCode(b + 96) }, next: i + 1 };
-    }
-    // Ctrl+_ is US (0x1f), not in a-z. Without this the advertised undo
-    // chord never arrives from a real tty — applyKey would only see it
-    // from tests constructing the event by hand.
-    if (b === 0x1f) return { key: { type: "ctrl", key: "_" }, next: i + 1 };
-    return { key: null, next: i + 1 };
-  }
-
-  const utf = takeUtf8(bytes, i);
-  if (utf === null) return null;
-  return { key: { type: "char", grapheme: utf.grapheme }, next: utf.next };
-}
-
-/**
- * CSI: ESC [ ... final. ECMA-48 §5.4. Parameter bytes 0x30-0x3F,
- * intermediate 0x20-0x2F, final 0x40-0x7E. Running out of bytes before a
- * final is the split-read case and must leave the prefix in `rest`.
- */
-function takeCsi(bytes: Uint8Array, i: number): Taken | null {
-  let j = i + 2;
-  while (j < bytes.length) {
-    const c = bytes[j]!;
-    if (c >= 0x40 && c <= 0x7e) {
-      const params = decodeParams(bytes.subarray(i + 2, j));
-      const final = String.fromCharCode(c);
-      return seqToTaken({ kind: "csi", params, final }, j + 1);
-    }
-    if (c >= 0x20 && c <= 0x3f) {
-      j++;
-      continue;
-    }
-    // Not a CSI parameter. Consume the ESC alone as Escape so we do not
-    // stall on garbage; the rest of the buffer is decoded on the next loop.
-    return { key: { type: "escape" }, next: i + 1 };
-  }
-  return null;
-}
-
-/**
- * SS3: ESC O X. ECMA-48 SS3 / xterm DECCKM application-cursor mode.
- * Without this, arrow keys in a terminal that has sent SM ?1 become
- * unrecognised (ESC O A rather than ESC [ A).
- */
-function takeSs3(bytes: Uint8Array, i: number): Taken | null {
-  if (i + 2 >= bytes.length) return null;
-  const final = String.fromCharCode(bytes[i + 2]!);
-  return seqToTaken({ kind: "ss3", final }, i + 3);
-}
-
-function seqToTaken(seq: Seq, next: number): Taken {
-  return { key: seqToKey(seq), next };
-}
-
-function seqToKey(seq: Seq): Key | null {
-  switch (seq.kind) {
-    case "csi":
-      return csiToKey(seq.params, seq.final);
-    case "ss3":
-      return ss3ToKey(seq.final);
-    case "alt":
-      return { type: "alt", key: seq.grapheme };
-    default:
-      return assertNever(seq, "seqToKey");
-  }
-}
-
-function ss3ToKey(final: string): Key | null {
-  switch (final) {
-    case "A": return { type: "up" };
-    case "B": return { type: "down" };
-    case "C": return { type: "right" };
-    case "D": return { type: "left" };
-    case "H": return { type: "home" };
-    case "F": return { type: "end" };
-    default: return null;
-  }
-}
-
-function csiToKey(params: number[], final: string): Key | null {
-  const mods = xtermMods(params[1]);
-  switch (final) {
-    case "A": return navKey("up", mods);
-    case "B": return navKey("down", mods);
-    case "C": return navKey("right", mods);
-    case "D": return navKey("left", mods);
-    case "H": return navKey("home", mods);
-    case "F": return navKey("end", mods);
-    case "Z": return { type: "tab", shift: true };
-    case "u": return kittyKey(params);
-    case "~": return tildeKey(params);
-    default: return null;
-  }
-}
-
-/**
- * Kitty keyboard protocol CSI unicode ; modifier u.
- * https://sw.kovidgoyal.net/kitty/keyboard-protocol/
- * Shift+Enter is not in ECMA-48; terminals that can report it use this
- * (or xterm modifyOtherKeys below). Without it, Shift+Enter is just Enter
- * and a multi-line editor cannot exist.
- */
-function kittyKey(params: number[]): Key | null {
-  const cp = params[0] ?? 0;
-  const shift = hasShift(params[1]);
-  if (cp === 13) return { type: "enter", shift };
-  if (cp === 27) return { type: "escape" };
-  if (cp === 127) return { type: "backspace" };
-  if (cp === 9) return hasShift(params[1]) ? { type: "tab", shift: true } : { type: "tab" };
-  if (cp >= 32) return { type: "char", grapheme: String.fromCodePoint(cp) };
-  return null;
-}
-
-/**
- * xterm CSI n~  (vt sequences) and CSI 27 ; mod ; key ~ (modifyOtherKeys).
- * https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
- */
-function tildeKey(params: number[]): Key | null {
-  const a = params[0] ?? 0;
-  if (a === 27) {
-    const key = params[2] ?? 0;
-    if (key === 13) return { type: "enter", shift: hasShift(params[1]) };
-    return null;
-  }
-  const mods = xtermMods(params[1]);
-  switch (a) {
-    case 1:
-    case 7: return navKey("home", mods);
-    case 3: return navKey("delete", mods);
-    case 4:
-    case 8: return navKey("end", mods);
-    case 5: return navKey("pageup", mods);
-    case 6: return navKey("pagedown", mods);
-    case 13: return { type: "enter", shift: hasShift(params[1]) };
-    default: return null;
-  }
-}
-
-type NavType =
-  | "up"
-  | "down"
-  | "left"
-  | "right"
-  | "home"
-  | "end"
-  | "pageup"
-  | "pagedown"
-  | "delete";
-
-function navKey(type: NavType, mods: KeyMods | undefined): Key {
-  return mods === undefined ? { type } : { type, mods };
-}
-
-/**
- * xterm ctlseqs (modified cursor keys / modifyOtherKeys): the CSI
- * modifier parameter is `1 + bitmask`. Bit 0 is Shift, bit 1 Alt, bit
- * 2 Ctrl; they combine (CSI 1;7D is Ctrl+Alt+Left).
- * https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
- * Without these, CSI 1;3D (Alt+Left) and CSI 1;5D (Ctrl+Left) collapse
- * onto CSI D, and the editor's word-motion bindings can never fire.
- */
-const XTERM_MOD_SHIFT = 1;
-const XTERM_MOD_ALT = 2;
-const XTERM_MOD_CTRL = 4;
-
-/**
- * Decode the xterm modifier parameter. Omitted or 1 means unmodified.
- * Values below 1 are not in the encoding -- treating them as a bitmask
- * would sign-extend (`0 - 1` is -1, every bit set). Unrecognised bits
- * (Meta = 8, CSI 1;9D) are ignored rather than dropping the key: a
- * dead key looks like a stuck terminal, an unbound shortcut does not.
- */
-function xtermMods(mod: number | undefined): KeyMods | undefined {
-  if (mod === undefined || mod < 2) return undefined;
-  const bits = mod - 1;
-  const shift = (bits & XTERM_MOD_SHIFT) !== 0;
-  const alt = (bits & XTERM_MOD_ALT) !== 0;
-  const ctrl = (bits & XTERM_MOD_CTRL) !== 0;
-  if (!shift && !alt && !ctrl) return undefined;
-  return {
-    ...(shift ? { shift: true } : {}),
-    ...(alt ? { alt: true } : {}),
-    ...(ctrl ? { ctrl: true } : {}),
-  };
-}
-
-/** xterm/Kitty modifier encoding: 1 + bitfield, bit 0 is Shift. */
-function hasShift(mod: number | undefined): boolean {
-  return xtermMods(mod)?.shift === true;
-}
-
-function decodeParams(buf: Uint8Array): number[] {
-  if (buf.length === 0) return [];
-  let s = new TextDecoder().decode(buf);
-  if (s.startsWith("?") || s.startsWith(">")) s = s.slice(1);
-  if (s.length === 0) return [];
-  const out: number[] = [];
-  for (const part of s.split(";")) {
-    const n = part === "" ? 0 : Number.parseInt(part, 10);
-    out.push(Number.isFinite(n) ? n : 0);
-  }
-  return out;
-}
-
-function utf8Need(lead: number): number {
-  if (lead < 0x80) return 1;
-  if ((lead & 0xe0) === 0xc0) return 2;
-  if ((lead & 0xf0) === 0xe0) return 3;
-  if ((lead & 0xf8) === 0xf0) return 4;
-  return 1;
-}
-
-function takeUtf8(bytes: Uint8Array, i: number): { grapheme: string; next: number } | null {
-  const lead = bytes[i]!;
-  const need = utf8Need(lead);
-  if (i + need > bytes.length) return null;
-  if (need > 1) {
-    for (let k = 1; k < need; k++) {
-      if ((bytes[i + k]! & 0xc0) !== 0x80) {
-        return { grapheme: "\uFFFD", next: i + 1 };
-      }
-    }
-  } else if (lead >= 0x80) {
-    return { grapheme: "\uFFFD", next: i + 1 };
-  }
-  const grapheme = new TextDecoder().decode(bytes.subarray(i, i + need));
-  return { grapheme, next: i + need };
-}

package/src/tui/markdown.ts

@@ -1,17 +0,0 @@
-/**
- * Markdown → terminal lines, via the vendored pi Markdown component.
- *
- * D19: the live UI is pi's renderer, which is built on `marked`. Our
- * previous subset parser lived here; the function signature stayed so
- * apps/render.ts and theming tests still call renderMarkdown(text, width,
- * style). Style is mapped onto pi's MarkdownTheme in host.ts.
- */
-import { renderMarkdownLines } from "./host.ts";
-import { IDENTITY, type Style } from "./style.ts";
-
-export { ANSI, IDENTITY } from "./style.ts";
-export type { Style } from "./style.ts";
-
-export function renderMarkdown(text: string, width: number, style: Style = IDENTITY): string[] {
-  return renderMarkdownLines(text, width, style);
-}

package/src/tui/render.ts

@@ -1,153 +0,0 @@
-/**
- * Line-level differential renderer.
- *
- * Cell-level diffing would need a full screen buffer of character-plus-attrs
- * per cell. Line-level diffing compares strings, and a terminal already
- * paints in rows. Unchanged neighbours are skipped even when they sit
- * between two changed rows -- the test that pins this would accept a
- * contiguous first-changed..last-changed rewrite, and that rewrite is how
- * a one-line spinner in a tall transcript becomes a full-region repaint.
- *
- * Main screen only. The live region sits at the bottom of the viewport;
- * history stays in the terminal's own scrollback. No alt-screen, so we
- * never own (and never have to reimplement) native scroll or search.
- */
-
-import { usableColumns, usableRows, type Terminal } from "./terminal.ts";
-import type { Component } from "./text.ts";
-import {
-  CR, LF, SYNC_BEGIN, SYNC_END, ERASE_DOWN, ERASE_LINE_TAIL,
-  cursorUp, cursorDown,
-} from "./ansi.ts";
-
-export class Renderer {
-  private readonly terminal: Terminal;
-  private previous: string[] = [];
-  /** Row within the live region where the hardware cursor sits, 0-based. */
-  private cursorRow = 0;
-  /**
-   * Overflow lines already written as scrollback. A count, not an identity:
-   * this matches paintStream, which only commits growth. Reset when the
-   * frame fits again so a later tall frame is not silently dropped.
-   */
-  private flushed = 0;
-
-  constructor(terminal: Terminal) {
-    this.terminal = terminal;
-  }
-
-  /** Rows currently occupying the live region, after overflow was committed. */
-  get liveRowCount(): number {
-    return this.previous.length;
-  }
-
-  render(root: Component): void {
-    const fitted = fitLive(
-      root.render(usableColumns(this.terminal.columns)),
-      usableRows(this.terminal.rows),
-    );
-    if (fitted.overflow.length > this.flushed) {
-      const fresh = fitted.overflow.slice(this.flushed);
-      this.eraseLive();
-      // Outside the sync pair, matching paintStream: these lines become
-      // real scrollback. Dropping them here is how L0–L2 vanished from a
-      // 5-row viewport even though fitLive had already split them off.
-      this.terminal.write(fresh.join("\n") + "\n");
-      this.flushed = fitted.overflow.length;
-    } else if (fitted.overflow.length === 0) {
-      this.flushed = 0;
-    }
-    const next = fitted.live;
-    const body = this.diff(next);
-    if (body === null) return;
-    // One write per frame. Two writes would let tmux flush the CSI 2026
-    // begin without the matching end, and the user would see the tear
-    // synchronized output exists to hide.
-    this.terminal.write(SYNC_BEGIN + body + SYNC_END);
-    this.previous = next;
-  }
-
-  /**
-   * Clear the live region so committed overflow is not painted on top of
-   * it. Same motion as Tui.dropLive; kept here so the generic render path
-   * (editor, select list) cannot forget it the way the first streaming
-   * pass did.
-   */
-  private eraseLive(): void {
-    if (this.previous.length === 0) return;
-    let out = CR;
-    if (this.cursorRow > 0) out += cursorUp(this.cursorRow);
-    out += ERASE_DOWN;
-    this.terminal.write(out);
-    this.previous = [];
-    this.cursorRow = 0;
-  }
-
-  private diff(next: string[]): string | null {
-    const prev = this.previous;
-    if (prev.length === next.length && prev.every((line, i) => line === next[i])) {
-      return null;
-    }
-
-    if (prev.length === 0) {
-      this.cursorRow = Math.max(0, next.length - 1);
-      return next.join(LF);
-    }
-
-    let out = "";
-    let row = this.cursorRow;
-
-    const go = (target: number): void => {
-      out += CR;
-      if (target < row) out += cursorUp(row - target);
-      else if (target > row) out += cursorDown(target - row);
-      row = target;
-    };
-
-    const shared = Math.min(prev.length, next.length);
-    for (let i = 0; i < shared; i++) {
-      if (prev[i] === next[i]) continue;
-      go(i);
-      out += next[i]!;
-      out += ERASE_LINE_TAIL;
-    }
-
-    if (next.length > prev.length) {
-      go(prev.length - 1);
-      for (let i = prev.length; i < next.length; i++) {
-        out += LF;
-        out += next[i]!;
-        row = i;
-      }
-    } else if (next.length < prev.length) {
-      go(next.length === 0 ? 0 : next.length);
-      out += ERASE_DOWN;
-    }
-
-    if (next.length === 0) {
-      this.cursorRow = 0;
-    } else {
-      if (row !== next.length - 1) go(next.length - 1);
-      this.cursorRow = next.length - 1;
-    }
-    return out;
-  }
-}
-
-/**
- * Split a frame so the live tail never exceeds the viewport.
- *
- * `diff` locates rows with cursorUp(row - target). A previous frame taller
- * than the screen has its cursor clamped at row 0 by the terminal, and every
- * later move is then off by the overflow. The head goes to the caller to
- * commit as scrollback; we only keep the tail.
- */
-export function fitLive(
-  lines: readonly string[],
-  maxRows: number,
-): { overflow: string[]; live: string[] } {
-  if (maxRows <= 0) return { overflow: [...lines], live: [] };
-  if (lines.length <= maxRows) return { overflow: [], live: [...lines] };
-  const cut = lines.length - maxRows;
-  return { overflow: lines.slice(0, cut), live: lines.slice(cut) };
-}