✨ parse DSR cursor position and rename row offset to top

Add CursorEvent with 0-based top/left coords by parsing the terminal's
DSR response (\x1b[row;colR). Rename createTerm's row option to top
so cursor.top feeds directly into createTerm({ top: cursor.top }).

Author: cowboyd

input-native.ts

@@ -1,6 +1,7 @@
 export const EVENT_KEY = 1;
 export const EVENT_MOUSE = 2;
 export const EVENT_RESIZE = 3;
+export const EVENT_CURSOR = 4;
 
 export const MOD_ALT = 1;
 export const MOD_CTRL = 2;

input.ts

@@ -8,6 +8,7 @@
 
 import {
   createInputNative,
+  EVENT_CURSOR,
   EVENT_KEY,
   EVENT_MOUSE,
   EVENT_RESIZE,
@@ -350,6 +351,26 @@ export interface ResizeEvent {
   height: number;
 }
 
+/**
+ * Cursor position report (DSR response).
+ *
+ * Emitted when the terminal responds to a Device Status Report
+ * query (`\x1b[6n`) with the current cursor position.
+ */
+export interface CursorEvent {
+  type: "cursor";
+
+  /**
+   * Cursor row (0-based).
+   */
+  top: number;
+
+  /**
+   * Cursor column (0-based).
+   */
+  left: number;
+}
+
 import type { PointerEvent } from "./term.ts";
 
 export type InputEvent =
@@ -359,6 +380,7 @@ export type InputEvent =
   | MouseMoveEvent
   | WheelEvent
   | ResizeEvent
+  | CursorEvent
   | PointerEvent;
 
 /**
@@ -659,6 +681,9 @@ function mapEvent(native: NativeInputEvent): InputEvent {
     case EVENT_RESIZE: {
       return { type: "resize", width: native.w, height: native.h };
     }
+    case EVENT_CURSOR: {
+      return { type: "cursor", top: native.y, left: native.x };
+    }
     default: {
       return mapKeyEvent(native);
     }

src/input.c

@@ -573,6 +573,49 @@ static uint16_t csi_legacy_key(char term, int number) {
   }
 }
 
+/* Parse DSR cursor position response: CSI row ; col R */
+static int parse_cursor(struct InputState *st, struct InputEvent *ev) {
+  if (st->len < 2)
+    return PARSE_NEED_MORE;
+  if (st->buf[0] != '\x1b' || st->buf[1] != '[')
+    return PARSE_ERR;
+  if (st->len < 3)
+    return PARSE_NEED_MORE;
+
+  int row = 0;
+  int col = 0;
+  int param = 0;
+  int i = 2;
+
+  while (i < st->len) {
+    char c = st->buf[i];
+    if (c >= '0' && c <= '9') {
+      if (param == 0) {
+        row = row * 10 + (c - '0');
+      } else {
+        col = col * 10 + (c - '0');
+      }
+    } else if (c == ';') {
+      if (param > 0)
+        return PARSE_ERR;
+      param++;
+    } else if (c == 'R') {
+      if (param != 1)
+        return PARSE_ERR;
+      i++;
+      ev->type = EVENT_CURSOR;
+      ev->y = row - 1;
+      ev->x = col - 1;
+      shift(st, i);
+      return PARSE_OK;
+    } else {
+      return PARSE_ERR;
+    }
+    i++;
+  }
+  return PARSE_NEED_MORE;
+}
+
 /* Parse Kitty-enhanced legacy CSI sequences (non-u terminators).
  * Format: CSI [number] [; mod[:action]] terminator
  * Handles A-D, F, H, P, Q, S, ~ terminators with optional :action */
@@ -986,6 +1029,22 @@ int input_scan(struct InputState *st, const char *buf, int len, double now) {
         }
       }
 
+      /* try DSR cursor position response */
+      {
+        struct InputEvent kev;
+        memset(&kev, 0, sizeof(kev));
+        int rv = parse_cursor(st, &kev);
+        if (rv == PARSE_OK) {
+          struct InputEvent *ev = emit(st);
+          *ev = kev;
+          st->esc_time = 0;
+          continue;
+        }
+        if (rv == PARSE_NEED_MORE) {
+          return accepted;
+        }
+      }
+
       /* try Kitty-enhanced legacy CSI (arrows, fn keys, etc.) */
       {
         struct InputEvent kev;

src/input.h

@@ -58,6 +58,7 @@
 #define EVENT_KEY 1
 #define EVENT_MOUSE 2
 #define EVENT_RESIZE 3
+#define EVENT_CURSOR 4
 
 /* ── Modifier flags (bitwise) ─────────────────────────────────────── */
 

term.ts

@@ -4,7 +4,7 @@ import { createTermNative } from "./term-native.ts";
 export interface TermOptions {
   height: number;
   width: number;
-  row?: number;
+  top?: number;
 }
 
 export interface RenderOptions {
@@ -30,8 +30,8 @@ export interface Term {
 }
 
 export async function createTerm(options: TermOptions): Promise<Term> {
-  let { width, height, row = 0 } = options;
-  let native = await createTermNative(width, height, row);
+  let { width, height, top = 0 } = options;
+  let native = await createTermNative(width, height, top);
   let { memory, statePtr, opsBuf } = native;
 
   let prev = new Set<string>();

test/input.test.ts

@@ -681,6 +681,40 @@ describe("input", () => {
     });
   });
 
+  describe("cursor position (DSR response)", () => {
+    it("parses cursor position report", () => {
+      let result = input.scan(str("\x1b[24;80R"));
+      expect(result.events.length).toBe(1);
+      expect(result.events[0]).toMatchObject({
+        type: "cursor",
+        top: 23,
+        left: 79,
+      });
+    });
+
+    it("parses cursor at origin", () => {
+      let result = input.scan(str("\x1b[1;1R"));
+      expect(result.events.length).toBe(1);
+      expect(result.events[0]).toMatchObject({
+        type: "cursor",
+        top: 0,
+        left: 0,
+      });
+    });
+
+    it("parses cursor interleaved with other input", () => {
+      let result = input.scan(str("a\x1b[10;5Rb"));
+      expect(result.events.length).toBe(3);
+      expect(result.events[0]).toMatchObject({ type: "keydown", key: "a" });
+      expect(result.events[1]).toMatchObject({
+        type: "cursor",
+        top: 9,
+        left: 4,
+      });
+      expect(result.events[2]).toMatchObject({ type: "keydown", key: "b" });
+    });
+  });
+
   describe("UTF-8", () => {
     it("parses 2-byte UTF-8 (é)", () => {
       let result = input.scan(bytes(0xc3, 0xa9));

test/term.test.ts

@@ -91,7 +91,7 @@ describe("term", () => {
 
   describe("row offset", () => {
     it("renders two frames at the offset position", async () => {
-      let term = await createTerm({ width: 20, height: 5, row: 5 });
+      let term = await createTerm({ width: 20, height: 5, top: 5 });
       let box = (msg: string) => [
         open("root", {
           layout: { width: grow(), height: grow(), direction: "ttb" },