tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/tui/mirror/blit.ts

@@ -0,0 +1,186 @@
+/**
+ * Pure cell → framebuffer writers for the framebuffer pane-blit path (M21.3).
+ *
+ * These map a mirror grid straight into an OpenTUI `OptimizedBuffer`'s typed
+ * arrays — no `StyledRun[]` intermediary, no per-run `RGBA` allocation, no Solid
+ * subtree. One packed cell is `char[i]` (a codepoint), four `fg`/`bg` channels
+ * (`r,g,b,a`, 0–255) at `i*4`, and one `attributes[i]` bitmask — the exact layout
+ * `OptimizedBuffer.buffers` exposes.
+ *
+ * Kept dependency-free (plain typed arrays) so the packing is unit-testable
+ * without the native render lib; {@link PaneMirror.blit} does the xterm walk and
+ * feeds these.
+ */
+
+/** The spacer (second) half of a wide glyph: char `0`. The native renderer knows
+ *  a cell is wide by MEASURING the lead cell's codepoint width and skips the
+ *  spacer, so the spacer's char just needs to be empty — this is exactly what
+ *  `OptimizedBuffer.setCell` writes for the trailing half (verified: a wide
+ *  glyph → `char[i]=codepoint, char[i+1]=0`). NB the `0xC0000000`
+ *  `CHAR_FLAG_CONTINUATION` seen in OptimizedBuffer is a DIFFERENT consumer (the
+ *  JS `getSpanLines`/`getRealCharBytes` text reader, off our render path);
+ *  writing it here blanks wide glyphs on screen (measured). */
+export const CHAR_CONTINUATION = 0;
+
+/** The space codepoint — the fill for blank / out-of-range cells. */
+export const SPACE_CODE = 0x20;
+
+/**
+ * INVERSE is rendered by SWAPPING fg/bg, not by the OpenTUI INVERSE attribute
+ * bit: a framebuffer cell carrying that bit composites (drawFrameBuffer preserves
+ * it) but does NOT flush as reverse-video — the direct `<text>` path does, the
+ * framebuffer path doesn't (measured). Swapping colors always renders (truecolor
+ * channels propagate cleanly), and covers app-driven reverse (vim status line),
+ * the cursor cell, and the drag selection uniformly. Swaps compose like the old
+ * XOR: two swaps on a cell (selection over the cursor) return it to normal.
+ */
+
+/** The four packed arrays behind an `OptimizedBuffer` (or a plain-array stand-in
+ *  for tests). `fg`/`bg` hold four `u16` channels (0–255) per cell at `i*4`. */
+export interface CellArrays {
+  char: Uint32Array;
+  fg: Uint16Array;
+  bg: Uint16Array;
+  attributes: Uint32Array;
+}
+
+/**
+ * A cell whose grapheme is more than one codepoint (ZWJ/flag emoji, combining
+ * marks) — a single `char[i]` u32 can't hold it. The fast blit writes its base
+ * codepoint; the caller (which owns the native `OptimizedBuffer`) re-writes these
+ * few cells with the full string via `setCell`, keeping full parity for the rare
+ * case without an allocation on the common path.
+ */
+export interface GraphemeOverride {
+  x: number;
+  y: number;
+  chars: string;
+  /** Packed `0xRRGGBB` or null (terminal default). */
+  fg: number | null;
+  bg: number | null;
+  attrs: number;
+}
+
+/**
+ * Write one styled cell at flat index `idx`. `fg`/`bg` are packed `0xRRGGBB` or
+ * `null` for the terminal default (→ the supplied `d*` channels); alpha is always
+ * opaque (panes never blend). No allocation — just eight typed-array stores.
+ */
+export function writeCell(
+  buf: CellArrays,
+  idx: number,
+  codepoint: number,
+  fg: number | null,
+  bg: number | null,
+  attrs: number,
+  dfR: number,
+  dfG: number,
+  dfB: number,
+  dbR: number,
+  dbG: number,
+  dbB: number,
+): void {
+  buf.char[idx] = codepoint;
+  const o = idx * 4;
+  if (fg === null) {
+    buf.fg[o] = dfR;
+    buf.fg[o + 1] = dfG;
+    buf.fg[o + 2] = dfB;
+  } else {
+    buf.fg[o] = (fg >> 16) & 0xff;
+    buf.fg[o + 1] = (fg >> 8) & 0xff;
+    buf.fg[o + 2] = fg & 0xff;
+  }
+  buf.fg[o + 3] = 255;
+  if (bg === null) {
+    buf.bg[o] = dbR;
+    buf.bg[o + 1] = dbG;
+    buf.bg[o + 2] = dbB;
+  } else {
+    buf.bg[o] = (bg >> 16) & 0xff;
+    buf.bg[o + 1] = (bg >> 8) & 0xff;
+    buf.bg[o + 2] = bg & 0xff;
+  }
+  buf.bg[o + 3] = 255;
+  buf.attributes[idx] = attrs;
+}
+
+/**
+ * Mark cell `idx` as the continuation (spacer) half of the wide glyph at `idx-1`,
+ * inheriting the glyph's colors so a colored wide glyph's background spans both
+ * cells. The renderer emits nothing for a continuation cell but still paints its
+ * background.
+ */
+export function writeContinuation(buf: CellArrays, idx: number): void {
+  buf.char[idx] = CHAR_CONTINUATION;
+  const o = idx * 4;
+  const p = (idx - 1) * 4;
+  buf.fg[o] = buf.fg[p]!;
+  buf.fg[o + 1] = buf.fg[p + 1]!;
+  buf.fg[o + 2] = buf.fg[p + 2]!;
+  buf.fg[o + 3] = buf.fg[p + 3]!;
+  buf.bg[o] = buf.bg[p]!;
+  buf.bg[o + 1] = buf.bg[p + 1]!;
+  buf.bg[o + 2] = buf.bg[p + 2]!;
+  buf.bg[o + 3] = buf.bg[p + 3]!;
+  buf.attributes[idx] = buf.attributes[idx - 1]!;
+}
+
+/**
+ * Swap fg/bg across cells `[from,to]` (inclusive, clamped to the row) of row `y`
+ * — the drag-selection reverse-video post-pass. A swap over the cursor cell (also
+ * swapped in the blit) returns it to normal, matching the run path's XOR.
+ */
+export function swapCells(
+  buf: CellArrays,
+  width: number,
+  y: number,
+  from: number,
+  to: number,
+): void {
+  const lo = Math.max(0, from);
+  const hi = Math.min(width - 1, to);
+  const base = y * width;
+  for (let x = lo; x <= hi; x++) {
+    const o = (base + x) * 4;
+    const r = buf.fg[o]!;
+    const g = buf.fg[o + 1]!;
+    const b = buf.fg[o + 2]!;
+    const a = buf.fg[o + 3]!;
+    buf.fg[o] = buf.bg[o]!;
+    buf.fg[o + 1] = buf.bg[o + 1]!;
+    buf.fg[o + 2] = buf.bg[o + 2]!;
+    buf.fg[o + 3] = buf.bg[o + 3]!;
+    buf.bg[o] = r;
+    buf.bg[o + 1] = g;
+    buf.bg[o + 2] = b;
+    buf.bg[o + 3] = a;
+  }
+}
+
+/**
+ * Paint the background of cells `[from,to]` (inclusive, clamped) of row `y` to
+ * packed `bg` — the scrollback-search highlight post-pass (the twin of
+ * {@link invertCells}; distinct treatment so a match and the selection coexist).
+ */
+export function paintBg(
+  buf: CellArrays,
+  width: number,
+  y: number,
+  from: number,
+  to: number,
+  bg: number,
+): void {
+  const lo = Math.max(0, from);
+  const hi = Math.min(width - 1, to);
+  const r = (bg >> 16) & 0xff;
+  const g = (bg >> 8) & 0xff;
+  const b = bg & 0xff;
+  for (let x = lo; x <= hi; x++) {
+    const o = (y * width + x) * 4;
+    buf.bg[o] = r;
+    buf.bg[o + 1] = g;
+    buf.bg[o + 2] = b;
+    buf.bg[o + 3] = 255;
+  }
+}

package/packages/daemon/src/tui/mirror/control-client.ts

@@ -0,0 +1,214 @@
+/**
+ * A tmux control-mode client.
+ *
+ * Spawns `tmux -C attach -t <target>` and speaks the control protocol over
+ * stdio: commands written to stdin get their replies back wrapped in
+ * `%begin`/`%end` blocks (FIFO order), while live pane bytes stream in as
+ * `%output` notifications between blocks. This is the same integration
+ * surface iTerm2 uses for its native tmux mode — tmux stays the multiplexer
+ * and persistence layer; the caller renders.
+ *
+ * stdout is read as latin1 (one JS char per byte) so pane bytes survive
+ * intact; `parseControlLine`/`decodeControlBytes` do the pure protocol work.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { appendFileSync } from "node:fs";
+import { parseControlLine, textToHexKeys } from "./control.ts";
+
+interface PendingReply {
+  discard?: false;
+  resolve: (lines: string[]) => void;
+  reject: (err: Error) => void;
+  lines: string[];
+}
+
+/** A fire-and-forget command's FIFO placeholder: its reply block is consumed
+ *  and dropped (errors counted). `lines` collects the error body only when
+ *  TMUX_IDE_MIRROR_DEBUG asks for it. */
+interface DiscardedReply {
+  discard: true;
+  lines?: string[];
+}
+
+type Pending = PendingReply | DiscardedReply;
+
+/** The shared no-debug placeholder — fire-and-forget input allocates NOTHING. */
+const DISCARDED: DiscardedReply = { discard: true };
+
+export interface ControlClientOptions {
+  /** Session (or other tmux target) to attach the control client to. */
+  attachTarget: string;
+  /** Live pane bytes: `%output` events, decoded. */
+  onOutput?: (pane: string, data: Uint8Array) => void;
+  /** Non-output notifications (layout-change, window-add, …). */
+  onNotify?: (name: string, rest: string) => void;
+  /** Control client ended (tmux exited or detached us). */
+  onExit?: (reason: string | null) => void;
+}
+
+export class ControlModeClient {
+  private proc: ChildProcess | null = null;
+  private readonly pending: Pending[] = [];
+  private inReply = false;
+  private buffer = "";
+  private discardedErrors = 0;
+  private readonly opts: ControlClientOptions;
+
+  constructor(opts: ControlClientOptions) {
+    this.opts = opts;
+  }
+
+  /** Spawn the control client and resolve once tmux's greeting block passed. */
+  start(): Promise<void> {
+    const proc = spawn("tmux", ["-C", "attach", "-t", this.opts.attachTarget], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, TMUX: "" },
+    });
+    this.proc = proc;
+    proc.stdout!.setEncoding("latin1");
+    proc.stdout!.on("data", (chunk: string) => this.feed(chunk));
+    proc.on("exit", () => this.opts.onExit?.(null));
+
+    // tmux opens the conversation with an unsolicited %begin/%end greeting
+    // block; queue a resolver for it so `start()` settles when the protocol
+    // is actually live (and so the pending queue stays aligned).
+    return new Promise((resolve, reject) => {
+      this.pending.push({ resolve: () => resolve(), reject, lines: [] });
+      proc.on("error", reject);
+    });
+  }
+
+  /** Run a tmux command over the control channel, resolving its reply body. */
+  command(cmd: string): Promise<string[]> {
+    const proc = this.proc;
+    if (!proc?.stdin?.writable) return Promise.reject(new Error("control client not running"));
+    return new Promise((resolve, reject) => {
+      this.pending.push({ resolve, reject, lines: [] });
+      proc.stdin!.write(`${cmd}\n`);
+    });
+  }
+
+  /**
+   * The INPUT FAST PATH (M21.5): write a command fire-and-forget. The bytes
+   * hit tmux's stdin exactly as immediately as `command()`'s do, but no
+   * Promise/resolver is allocated and nothing ever waits on the reply. Every
+   * control-mode command still produces exactly one `%begin/%end` block, so a
+   * placeholder is pushed onto the SAME pending FIFO — reply matching for
+   * reply-carrying commands (list-panes, capture-pane, …) stays aligned by
+   * construction. Errors are swallowed but counted ({@link inputErrorCount});
+   * with TMUX_IDE_MIRROR_DEBUG set the error body is appended to
+   * /tmp/zz-input-errors.log.
+   */
+  send(cmd: string): void {
+    const proc = this.proc;
+    if (!proc?.stdin?.writable) return;
+    this.pending.push(process.env.TMUX_IDE_MIRROR_DEBUG ? { discard: true, lines: [] } : DISCARDED);
+    proc.stdin.write(`${cmd}\n`);
+  }
+
+  /** Type literal text into a pane (UTF-8, sent as hex bytes — quote-proof).
+   *  Fire-and-forget: input never queues behind a slow structural reply. */
+  sendText(pane: string, text: string): void {
+    this.send(`send-keys -t ${pane} -H ${textToHexKeys(text).join(" ")}`);
+  }
+
+  /** Send a named tmux key (Enter, Escape, Up, C-c, …) to a pane. Fire-and-forget. */
+  sendKey(pane: string, key: string): void {
+    this.send(`send-keys -t ${pane} ${key}`);
+  }
+
+  /** How many fire-and-forget commands came back `%error` (debug/tests). */
+  get inputErrorCount(): number {
+    return this.discardedErrors;
+  }
+
+  dispose(): void {
+    const proc = this.proc;
+    this.proc = null;
+    if (!proc) return;
+    try {
+      proc.stdin?.write("detach-client\n");
+    } catch {
+      // already gone
+    }
+    setTimeout(() => {
+      if (proc.exitCode === null) proc.kill();
+    }, 250).unref?.();
+  }
+
+  private feed(chunk: string): void {
+    const t0 = process.env.TMUX_IDE_ZZ_PERF ? performance.now() : 0;
+    this.buffer += chunk;
+    let nl: number;
+    while ((nl = this.buffer.indexOf("\n")) !== -1) {
+      // tmux terminates lines with \r\n in control mode; strip both.
+      let line = this.buffer.slice(0, nl);
+      if (line.endsWith("\r")) line = line.slice(0, -1);
+      this.buffer = this.buffer.slice(nl + 1);
+      this.handleLine(line);
+    }
+    if (t0) {
+      try {
+        appendFileSync(
+          "/tmp/zz-feed.log",
+          `${chunk.length} ${(performance.now() - t0).toFixed(2)}\n`,
+        );
+      } catch {
+        /* perf tap */
+      }
+    }
+  }
+
+  private handleLine(line: string): void {
+    const event = parseControlLine(line, this.inReply);
+    switch (event.kind) {
+      case "begin":
+        this.inReply = true;
+        break;
+      case "reply-line": {
+        const head = this.pending[0];
+        // Discarded (fire-and-forget) replies skip body collection entirely —
+        // unless the debug placeholder brought its own lines buffer.
+        if (head) head.lines?.push(event.line);
+        break;
+      }
+      case "end":
+      case "error": {
+        this.inReply = false;
+        const reply = this.pending.shift();
+        if (!reply) break; // unsolicited block (e.g. greeting after a race)
+        if (reply.discard) {
+          if (event.kind === "error") {
+            this.discardedErrors++;
+            if (process.env.TMUX_IDE_MIRROR_DEBUG) {
+              try {
+                appendFileSync(
+                  "/tmp/zz-input-errors.log",
+                  `#${this.discardedErrors} ${reply.lines?.join(" | ") ?? ""}\n`,
+                );
+              } catch {
+                // debug tap only
+              }
+            }
+          }
+          break;
+        }
+        if (event.kind === "error") {
+          reply.reject(new Error(reply.lines.join("\n") || "tmux command failed"));
+        } else {
+          reply.resolve(reply.lines);
+        }
+        break;
+      }
+      case "output":
+        this.opts.onOutput?.(event.pane, event.data);
+        break;
+      case "exit":
+        this.opts.onExit?.(event.reason);
+        break;
+      case "notify":
+        this.opts.onNotify?.(event.name, event.rest);
+        break;
+    }
+  }
+}

package/packages/daemon/src/tui/mirror/control.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure parsing for tmux control mode (`tmux -C`).
+ *
+ * In control mode tmux writes newline-terminated event lines: command replies
+ * arrive wrapped in `%begin`/`%end` (or `%error`) blocks, and asynchronous
+ * notifications (`%output`, `%layout-change`, `%exit`, …) arrive between
+ * blocks. Pane output bytes in `%output` are escaped — every C0 control byte
+ * and the backslash itself appear as three-digit octal escapes (`\015`,
+ * `\033`, `\134`) — so the decoder here resolves those back to raw BYTES.
+ *
+ * Everything in this module is pure so the protocol handling can be
+ * unit-tested without a live tmux. The client reads tmux's stdout with
+ * latin1 encoding (one JS char per byte); `decodeControlBytes` returns a
+ * Uint8Array that xterm's `write()` interprets as UTF-8, which keeps
+ * multi-byte characters intact end to end.
+ */
+
+export type ControlEvent =
+  | { kind: "begin"; num: number }
+  | { kind: "end"; num: number }
+  | { kind: "error"; num: number }
+  | { kind: "output"; pane: string; data: Uint8Array }
+  | { kind: "exit"; reason: string | null }
+  | { kind: "notify"; name: string; rest: string }
+  | { kind: "reply-line"; line: string };
+
+/** Decode a latin1 control-mode payload (with \ooo escapes) into raw bytes. */
+export function decodeControlBytes(escaped: string): Uint8Array {
+  const out = new Uint8Array(escaped.length);
+  let n = 0;
+  for (let i = 0; i < escaped.length; i++) {
+    const ch = escaped.charCodeAt(i);
+    if (
+      ch === 0x5c && // backslash
+      i + 3 < escaped.length + 1 &&
+      isOctal(escaped.charCodeAt(i + 1)) &&
+      isOctal(escaped.charCodeAt(i + 2)) &&
+      isOctal(escaped.charCodeAt(i + 3))
+    ) {
+      out[n++] = parseInt(escaped.slice(i + 1, i + 4), 8) & 0xff;
+      i += 3;
+    } else {
+      out[n++] = ch & 0xff;
+    }
+  }
+  return out.subarray(0, n);
+}
+
+function isOctal(code: number | undefined): boolean {
+  return code !== undefined && code >= 0x30 && code <= 0x37; // '0'..'7'
+}
+
+/**
+ * Parse one control-mode line into an event.
+ *
+ * `insideReply` matters because reply-block bodies are arbitrary command
+ * output — a line starting with `%` inside a block is still body text unless
+ * it's the block terminator itself.
+ */
+export function parseControlLine(line: string, insideReply: boolean): ControlEvent {
+  if (line.startsWith("%end ") || line.startsWith("%error ")) {
+    const isError = line.startsWith("%error ");
+    const num = Number(line.split(" ")[2] ?? -1);
+    return { kind: isError ? "error" : "end", num };
+  }
+  if (insideReply) return { kind: "reply-line", line };
+
+  if (line.startsWith("%begin ")) {
+    return { kind: "begin", num: Number(line.split(" ")[2] ?? -1) };
+  }
+  if (line.startsWith("%output ")) {
+    const rest = line.slice("%output ".length);
+    const space = rest.indexOf(" ");
+    const pane = space === -1 ? rest : rest.slice(0, space);
+    const payload = space === -1 ? "" : rest.slice(space + 1);
+    return { kind: "output", pane, data: decodeControlBytes(payload) };
+  }
+  if (line.startsWith("%exit")) {
+    const reason = line.length > "%exit ".length ? line.slice("%exit ".length) : null;
+    return { kind: "exit", reason };
+  }
+  if (line.startsWith("%")) {
+    const space = line.indexOf(" ");
+    const name = space === -1 ? line.slice(1) : line.slice(1, space);
+    return { kind: "notify", name, rest: space === -1 ? "" : line.slice(space + 1) };
+  }
+  // Shouldn't happen outside a reply block, but never throw on protocol noise.
+  return { kind: "reply-line", line };
+}
+
+/** Encode text as a `send-keys -H` hex-byte argv tail (UTF-8 bytes). */
+export function textToHexKeys(text: string): string[] {
+  const bytes = new TextEncoder().encode(text);
+  const hex: string[] = [];
+  for (const b of bytes) hex.push(b.toString(16).padStart(2, "0"));
+  return hex;
+}