OSC 22 cursor support

.changeset/pointer-shape-osc22.md

@@ -0,0 +1,11 @@
+---
+"@bomb.sh/tty": minor
+---
+
+Adds a `cursor` property to `open()`, so the mouse pointer changes shape (OSC 22) as it moves over elements
+
+When the terminal confirms support through the probe (`term.capabilities.pointerShape`), `render()` appends the shape change to `output`, so writing `output` keeps the pointer in sync. The shape resets to `default` when the pointer leaves, when a frame renders without `pointer`, or when `update()` withdraws the capability. `detectTerminal()` also seeds the capability from a known-support table for terminals that set shapes without answering the query (ghostty, kitty, foot, xterm ≥ 367), so those work out of the box. For anything the table misses, assert support with `term.update([{ type: "capability", key: "pointer-shape", value: true }])`.
+
+```ts
+term.render([open("link", { cursor: "pointer" }), text("Docs"), close()], { pointer });
+```

AGENTS.md

@@ -33,7 +33,9 @@ Do not include any agent marketing material (e.g. "Generated with...",
 - The renderer MUST NOT manage terminal state (alternate buffer, mouse
   reporting, keyboard protocol modes). Cursor visibility and positioning are
   renderer-managed only when a `caret` declaration is present on a `text()`
-  directive (see renderer-spec.md §7.6).
+  directive (see renderer-spec.md §7.6). The mouse pointer shape is
+  renderer-managed only while the `pointerShape` capability is true (see
+  renderer-spec.md §7.9).
 
 - Each frame is a complete snapshot. The renderer carries no UI tree state
   between frames — only cell buffers for diffing.

debug-terminfo.ts

@@ -0,0 +1,185 @@
+// debug-terminfo.ts — pinpoint where the terminfo capability chain breaks.
+// Run directly in the terminal you are testing, from the repo root:
+//
+//   deno run -A debug-terminfo.ts
+//   node debug-terminfo.ts
+//
+// Walks the full chain and reports which link fails: environment identity,
+// detection (static Capabilities), the probe round-trip with a per-query
+// ✓/✗ breakdown, the parser's CapabilityEvents, and the term's merged
+// RuntimeCapabilities. The pointer shape section at the end exercises the
+// one capability render() consumes today; if no OSC 22 reply arrives, a
+// set-only check flashes the hand cursor so query-less terminals (ghostty)
+// can be told apart from terminals without OSC 22 at all.
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import {
+  type CapabilityEvent,
+  close,
+  createInput,
+  createTerm,
+  detectTerminal,
+  open,
+  text,
+} from "./mod.ts";
+
+const decode = new TextDecoder();
+const esc = (b: Uint8Array) => JSON.stringify(decode.decode(b)).slice(1, -1);
+const json = (v: unknown) => JSON.stringify(v);
+
+console.log("── environment");
+console.log("  TERM:", process.env.TERM ?? "(unset)");
+console.log(
+  "  TERM_PROGRAM:",
+  process.env.TERM_PROGRAM ?? "(unset)",
+  process.env.TERM_PROGRAM_VERSION ?? "",
+);
+console.log("  COLORTERM:", process.env.COLORTERM ?? "(unset)");
+if (process.env.TMUX) {
+  console.log("  ⚠ running inside tmux — queries may not pass through");
+}
+
+const info = await detectTerminal();
+console.log("── detection");
+console.log("  probe bytes:", info.probe.length);
+console.log("  static capabilities:", json(info.capabilities));
+
+if (!process.stdin.isTTY) {
+  console.log("  ✗ stdin is not a TTY; run this directly in your terminal");
+  process.exit(1);
+}
+
+console.log("── probing (2s window, raw mode on; type nothing)…");
+if (typeof process.stdin.setRawMode === "function") {
+  process.stdin.setRawMode(true);
+}
+process.stdout.write(info.probe);
+
+const chunks: Buffer[] = [];
+const onData = (chunk: Buffer) => chunks.push(chunk);
+process.stdin.on("data", onData);
+await new Promise((r) => setTimeout(r, 2000));
+process.stdin.removeListener("data", onData);
+
+const reply = Buffer.concat(chunks);
+console.log("── raw reply");
+console.log("  bytes:", reply.length);
+console.log(
+  "  escaped:",
+  reply.length ? esc(reply) : "(nothing — the terminal answered nothing)",
+);
+
+console.log("── which queries were answered");
+const replyText = decode.decode(reply);
+const markers: [string, string][] = [
+  ["foreground (OSC 10)", "\x1b]10;"],
+  ["background (OSC 11)", "\x1b]11;"],
+  ["cursor color (OSC 12)", "\x1b]12;"],
+  ["colors (OSC 21)", "\x1b]21;"],
+  ["POINTER SHAPE (OSC 22)", "\x1b]22;"],
+  ["XTGETTCAP (DCS)", "\x1bP"],
+  ["sync output (DECRPM 2026)", "?2026"],
+  ["kitty keyboard (?u)", "?u"],
+  ["kitty graphics (APC)", "\x1b_G"],
+];
+for (const [name, marker] of markers) {
+  console.log(`  ${replyText.includes(marker) ? "✓" : "✗"} ${name}`);
+}
+
+// The query tells us about reply support, not set support. Ghostty sets
+// shapes since 1.0 but never answers the query, so give the terminal a
+// chance to show what it can do: set the hand for 1.5s, then restore.
+if (!replyText.includes("\x1b]22;")) {
+  console.log("── set-only check (watch your cursor)");
+  process.stdout.write("\x1b]22;pointer\x1b\\");
+  await new Promise((r) => setTimeout(r, 1500));
+  process.stdout.write("\x1b]22;default\x1b\\");
+  console.log(
+    "  the cursor should have flashed to a hand just now. If it did," +
+      " this terminal can SET shapes but never answers the query" +
+      " (ghostty behaves exactly like this) — detectTerminal()'s" +
+      " known-support table should already cover it. If it did not" +
+      " change, OSC 22 is not supported at all.",
+  );
+}
+
+if (typeof process.stdin.setRawMode === "function") {
+  process.stdin.setRawMode(false);
+}
+
+console.log("── parser");
+const input = await createInput({ terminfo: info });
+let events = input.scan(new Uint8Array(reply)).events;
+events = [...events, ...input.scan(new Uint8Array(0)).events];
+const caps = events.filter((e): e is CapabilityEvent =>
+  e.type === "capability"
+);
+if (caps.length === 0) {
+  console.log("  (no capability events parsed)");
+}
+for (const c of caps) {
+  console.log(`  capability: ${c.key} = ${json(c.value)}`);
+}
+
+console.log("── term (merged view)");
+const term = await createTerm({ width: 40, height: 6, terminfo: info });
+term.update(caps);
+console.log("  merged capabilities:", json(term.capabilities));
+const staticCaps = info.capabilities as unknown as Record<string, unknown>;
+const mergedCaps = term.capabilities as unknown as Record<string, unknown>;
+const raised = Object.keys(mergedCaps).filter((k) =>
+  json(mergedCaps[k]) !== json(staticCaps[k])
+);
+console.log(
+  "  raised by the probe:",
+  raised.length > 0 ? raised.join(", ") : "(nothing — probe added no evidence)",
+);
+
+// Pointer shape is the one capability render() consumes today, so it doubles
+// as the end-to-end emission check.
+console.log("── pointer shape (renderer-spec §7.9)");
+const result = term.render(
+  [open("box", { cursor: "pointer" }), text("hover"), close()],
+  { pointer: { x: 2, y: 2, down: false } },
+);
+const emitted = decode
+  .decode(result.output)
+  .includes("\x1b]22;pointer\x1b\\");
+console.log("  OSC 22 in render output:", emitted);
+
+console.log("── verdict");
+if (emitted) {
+  console.log(
+    "  ✓ render emits OSC 22" +
+      (info.capabilities.pointerShape && !replyText.includes("\x1b]22;")
+        ? " — statically granted by the known-support table (no query reply," +
+          " which is expected for set-only terminals like ghostty)"
+        : " — the probe confirmed support and the parser folded it in") +
+      ". If the demos still show nothing, hover a key/button — and note the" +
+      " shape only changes while the pointer is over an element that" +
+      " declares one.",
+  );
+} else if (!replyText.includes("\x1b]22;")) {
+  console.log(
+    info.capabilities.pointerShape
+      ? "  ✗ no OSC 22 reply and no emission despite a static grant — please" +
+        " report this with the escaped reply above."
+      : "  ✗ your terminal did not answer the OSC 22 query and it is not on" +
+        " the known-support table. If the set-only check above moved your" +
+        " cursor, it can set shapes but we cannot detect it — run the demos" +
+        " with TTY_POINTER_SHAPES=1 (or nominate the terminal for the" +
+        " table). If the cursor never changed, OSC 22 is not supported at" +
+        " all (iTerm2, Terminal.app, VS Code, tmux without passthrough).",
+  );
+} else if (caps.length === 0) {
+  console.log(
+    "  ✗ the terminal replied but the parser produced no capability events." +
+      " Please report this with the escaped reply above.",
+  );
+} else {
+  console.log(
+    "  ✗ capability recognized but render did not emit OSC 22. Please report" +
+      " this with the escaped reply above.",
+  );
+}
+process.exit(0);

ops.ts

@@ -1,3 +1,7 @@
+import type { PointerShape } from "./pointer-shape.ts";
+
+export type { PointerShape };
+
 export type TransitionProperty =
   | "x"
   | "y"
@@ -410,6 +414,7 @@ export interface OpenElement {
     zIndex?: number;
   };
   transition?: Transition;
+  cursor?: PointerShape;
 }
 
 export type AttachPoint =
@@ -491,6 +496,7 @@ export interface Text {
 interface Snapshot {
   directive: typeof OP_SNAPSHOT;
   data: Uint8Array;
+  shapes?: readonly (readonly [id: string, shape: string])[];
 }
 
 export type Op = OpenElement | Text | CloseElement | Snapshot;
@@ -551,7 +557,19 @@ export function snapshot(ops: Op[]): Op {
   let size = packSize(ops);
   let buf = new ArrayBuffer(size);
   let words = pack(ops, buf, 0, size);
-  return { directive: OP_SNAPSHOT, data: new Uint8Array(buf, 0, words * 4) };
+  let data = new Uint8Array(buf, 0, words * 4);
+  let shapes: (readonly [string, string])[] = [];
+  for (let op of ops) {
+    if (op.directive === OP_SNAPSHOT) {
+      if (op.shapes) shapes.push(...op.shapes);
+    } else if (
+      op.directive === OP_OPEN_ELEMENT && op.cursor !== undefined
+    ) {
+      shapes.push([op.id, op.cursor]);
+    }
+  }
+  if (shapes.length === 0) return { directive: OP_SNAPSHOT, data };
+  return { directive: OP_SNAPSHOT, data, shapes };
 }
 
 const TP_X = 1;

pointer-shape.ts

@@ -0,0 +1,81 @@
+import type { Op } from "./ops.ts";
+
+export const POINTER_SHAPES = [
+  "default",
+  "none",
+  "context-menu",
+  "help",
+  "pointer",
+  "progress",
+  "wait",
+  "cell",
+  "crosshair",
+  "text",
+  "vertical-text",
+  "alias",
+  "copy",
+  "move",
+  "no-drop",
+  "not-allowed",
+  "grab",
+  "grabbing",
+  "e-resize",
+  "n-resize",
+  "ne-resize",
+  "nw-resize",
+  "s-resize",
+  "se-resize",
+  "sw-resize",
+  "w-resize",
+  "ew-resize",
+  "ns-resize",
+  "nesw-resize",
+  "nwse-resize",
+  "zoom-in",
+  "zoom-out",
+] as const;
+
+/**
+ * A mouse pointer shape, named with the CSS `cursor` keyword vocabulary used
+ * by the OSC 22 pointer shape protocol.
+ *
+ * @see {@link https://sw.kovidgoyal.net/kitty/pointer-shapes/ | kitty pointer shapes}
+ */
+export type PointerShape = typeof POINTER_SHAPES[number];
+
+const KNOWN: ReadonlySet<string> = new Set(POINTER_SHAPES);
+
+export function resolvePointerShape(
+  ops: readonly Op[],
+  over: readonly string[],
+): PointerShape {
+  let best = -1;
+  let shape: PointerShape = "default";
+  for (let op of ops) {
+    if ("data" in op) {
+      if (!op.shapes) continue;
+      for (let [id, value] of op.shapes) {
+        if (!KNOWN.has(value)) continue;
+        let i = over.lastIndexOf(id);
+        if (i > best) {
+          best = i;
+          shape = value as PointerShape;
+        }
+      }
+    } else if ("cursor" in op && op.cursor !== undefined) {
+      if (!KNOWN.has(op.cursor)) continue;
+      let i = over.lastIndexOf(op.id);
+      if (i > best) {
+        best = i;
+        shape = op.cursor;
+      }
+    }
+  }
+  return shape;
+}
+
+const encoder = new TextEncoder();
+
+export function osc22(shape: PointerShape): Uint8Array {
+  return encoder.encode(`\x1b]22;${shape}\x1b\\`);
+}