Add ptywright wait revisions and mode-aware special keys

Fix waitFor lost-wakeups with a revision counter, and encode
SpecialKey presses from Ghostty's live terminal modes without
changing press() raw-string behavior.

Author: rgarcia

packages/ptywright/README.md

@@ -304,7 +304,7 @@ Writes text followed by `Enter`.
 
 ##### `session.press(key)`
 
-Writes a key sequence, typically one of the exported key constants.
+Writes a raw key sequence. The exported `Key*` constants are those raw strings and stay pass-through.
 
 ```ts
 import { KeyArrowDown, KeyEnter } from "@onkernel/ptywright";
@@ -313,6 +313,16 @@ session.press(KeyArrowDown);
 session.press(KeyEnter);
 ```
 
+##### `session.pressKey(key)`
+
+Encodes a `SpecialKey` from the live terminal modes (for example DECCKM application cursor keys) and writes those bytes.
+
+```ts
+import { SpecialArrowUp } from "@onkernel/ptywright";
+
+session.pressKey(SpecialArrowUp);
+```
+
 #### Lifecycle and snapshots
 
 ##### `session.resize(cols, rows)`
@@ -438,6 +448,8 @@ The package exports common terminal key sequences as strings:
 - `KeyArrowLeft`
 - `KeyArrowRight`
 
+Those `Key*` values are raw bytes for `press()` / `send()`. For mode-aware arrows and the other specials, use `SpecialArrowUp` and `session.pressKey(...)`.
+
 You can also pass any raw sequence directly to `session.send(...)`.
 
 ## Examples

packages/ptywright/native/src/addon.cc

@@ -175,6 +175,40 @@ Napi::Value Snapshot(const Napi::CallbackInfo &info) {
 	return output;
 }
 
+Napi::Value EncodeSpecialKey(const Napi::CallbackInfo &info) {
+	Napi::Env env = info.Env();
+	TerminalState *state = GetState(info);
+	if (!EnsureOpen(env, state)) {
+		return env.Undefined();
+	}
+	if (info.Length() < 1 || !info[0].IsString()) {
+		Napi::TypeError::New(env, "encodeSpecialKey expects a key name").ThrowAsJavaScriptException();
+		return env.Undefined();
+	}
+
+	std::string name = info[0].As<Napi::String>().Utf8Value();
+	uint8_t *bytes = nullptr;
+	size_t len = 0;
+	int result = ptywright_ghostty_terminal_encode_special_key(
+		state->terminal,
+		name.c_str(),
+		&bytes,
+		&len);
+	if (result != 0) {
+		ThrowGhosttyError(env, "ptywright_ghostty_terminal_encode_special_key", result);
+		ptywright_ghostty_free_bytes(bytes);
+		return env.Undefined();
+	}
+	if (bytes == nullptr || len == 0) {
+		ptywright_ghostty_free_bytes(bytes);
+		return env.Undefined();
+	}
+
+	Napi::Buffer<uint8_t> output = Napi::Buffer<uint8_t>::Copy(env, bytes, len);
+	ptywright_ghostty_free_bytes(bytes);
+	return output;
+}
+
 Napi::Value Dispose(const Napi::CallbackInfo &info) {
 	TerminalState *state = GetState(info);
 	if (state && state->terminal) {
@@ -211,6 +245,7 @@ Napi::Value CreateTerminal(const Napi::CallbackInfo &info) {
 	object.Set("feed", Napi::Function::New(env, Feed, "feed", state));
 	object.Set("resize", Napi::Function::New(env, Resize, "resize", state));
 	object.Set("snapshot", Napi::Function::New(env, Snapshot, "snapshot", state));
+	object.Set("encodeSpecialKey", Napi::Function::New(env, EncodeSpecialKey, "encodeSpecialKey", state));
 	object.Set("dispose", Napi::Function::New(env, Dispose, "dispose", state));
 	return object;
 }

packages/ptywright/native/src/ghostty_bridge.c

@@ -17,6 +17,7 @@ enum {
 
 struct PtywrightGhosttyTerminal {
 	GhosttyTerminal handle;
+	GhosttyKeyEncoder encoder;
 	uint8_t *reply_buf;
 	size_t reply_len;
 	size_t reply_cap;
@@ -27,6 +28,44 @@ struct PtywrightGhosttyTerminal {
 	int reply_error;
 };
 
+static int ptywright_ghostty_special_key(const char *name, GhosttyKey *out_key,
+					 GhosttyMods *out_mods) {
+	if (name == NULL || out_key == NULL || out_mods == NULL) {
+		return GHOSTTY_INVALID_VALUE;
+	}
+
+	*out_mods = 0;
+	if (strcmp(name, "arrow_up") == 0) {
+		*out_key = GHOSTTY_KEY_ARROW_UP;
+	} else if (strcmp(name, "arrow_down") == 0) {
+		*out_key = GHOSTTY_KEY_ARROW_DOWN;
+	} else if (strcmp(name, "arrow_left") == 0) {
+		*out_key = GHOSTTY_KEY_ARROW_LEFT;
+	} else if (strcmp(name, "arrow_right") == 0) {
+		*out_key = GHOSTTY_KEY_ARROW_RIGHT;
+	} else if (strcmp(name, "home") == 0) {
+		*out_key = GHOSTTY_KEY_HOME;
+	} else if (strcmp(name, "end") == 0) {
+		*out_key = GHOSTTY_KEY_END;
+	} else if (strcmp(name, "page_up") == 0) {
+		*out_key = GHOSTTY_KEY_PAGE_UP;
+	} else if (strcmp(name, "page_down") == 0) {
+		*out_key = GHOSTTY_KEY_PAGE_DOWN;
+	} else if (strcmp(name, "insert") == 0) {
+		*out_key = GHOSTTY_KEY_INSERT;
+	} else if (strcmp(name, "delete") == 0) {
+		*out_key = GHOSTTY_KEY_DELETE;
+	} else if (strcmp(name, "escape") == 0) {
+		*out_key = GHOSTTY_KEY_ESCAPE;
+	} else if (strcmp(name, "backtab") == 0) {
+		*out_key = GHOSTTY_KEY_TAB;
+		*out_mods = GHOSTTY_MODS_SHIFT;
+	} else {
+		return GHOSTTY_INVALID_VALUE;
+	}
+	return GHOSTTY_SUCCESS;
+}
+
 static int ptywright_ghostty_reserve_buffer(uint8_t **buf,
 					    size_t *cap,
 					    size_t needed) {
@@ -218,6 +257,13 @@ int ptywright_ghostty_terminal_create(uint16_t cols, uint16_t rows, size_t scrol
 		return result;
 	}
 
+	result = ghostty_key_encoder_new(NULL, &terminal->encoder);
+	if (result != GHOSTTY_SUCCESS) {
+		ghostty_terminal_free(terminal->handle);
+		free(terminal);
+		return result;
+	}
+
 	*out_terminal = terminal;
 	return GHOSTTY_SUCCESS;
 }
@@ -263,6 +309,78 @@ int ptywright_ghostty_terminal_resize(PtywrightGhosttyTerminal *terminal,
 	return ghostty_terminal_resize(terminal->handle, cols, rows, kCellWidthPx, kCellHeightPx);
 }
 
+int ptywright_ghostty_terminal_encode_special_key(PtywrightGhosttyTerminal *terminal,
+						 const char *name,
+						 uint8_t **out_bytes,
+						 size_t *out_len) {
+	if (terminal == NULL || terminal->handle == NULL || terminal->encoder == NULL ||
+	    name == NULL || out_bytes == NULL || out_len == NULL) {
+		return GHOSTTY_INVALID_VALUE;
+	}
+
+	*out_bytes = NULL;
+	*out_len = 0;
+
+	GhosttyKey key = GHOSTTY_KEY_UNIDENTIFIED;
+	GhosttyMods mods = 0;
+	int mapped = ptywright_ghostty_special_key(name, &key, &mods);
+	if (mapped != GHOSTTY_SUCCESS) {
+		return mapped;
+	}
+
+	GhosttyKeyEvent event = NULL;
+	GhosttyResult result = ghostty_key_event_new(NULL, &event);
+	if (result != GHOSTTY_SUCCESS) {
+		return result;
+	}
+
+	ghostty_key_event_set_action(event, GHOSTTY_KEY_ACTION_PRESS);
+	ghostty_key_event_set_key(event, key);
+	ghostty_key_event_set_mods(event, mods);
+	ghostty_key_encoder_setopt_from_terminal(terminal->encoder, terminal->handle);
+
+	char stack[128];
+	size_t written = 0;
+	result = ghostty_key_encoder_encode(terminal->encoder, event, stack, sizeof(stack), &written);
+	if (result == GHOSTTY_OUT_OF_SPACE) {
+		char *dynamic = malloc(written > 0 ? written : 1);
+		if (dynamic == NULL) {
+			ghostty_key_event_free(event);
+			return GHOSTTY_OUT_OF_MEMORY;
+		}
+		result = ghostty_key_encoder_encode(terminal->encoder, event, dynamic, written, &written);
+		if (result != GHOSTTY_SUCCESS) {
+			free(dynamic);
+			ghostty_key_event_free(event);
+			return result;
+		}
+		*out_bytes = (uint8_t *)dynamic;
+		*out_len = written;
+		ghostty_key_event_free(event);
+		return GHOSTTY_SUCCESS;
+	}
+	if (result != GHOSTTY_SUCCESS) {
+		ghostty_key_event_free(event);
+		return result;
+	}
+
+	if (written == 0) {
+		ghostty_key_event_free(event);
+		return GHOSTTY_SUCCESS;
+	}
+
+	uint8_t *copy = malloc(written);
+	if (copy == NULL) {
+		ghostty_key_event_free(event);
+		return GHOSTTY_OUT_OF_MEMORY;
+	}
+	memcpy(copy, stack, written);
+	*out_bytes = copy;
+	*out_len = written;
+	ghostty_key_event_free(event);
+	return GHOSTTY_SUCCESS;
+}
+
 int ptywright_ghostty_terminal_snapshot(PtywrightGhosttyTerminal *terminal,
 					int trim, int unwrap,
 					PtywrightGhosttySnapshot *out_snapshot) {
@@ -416,6 +534,10 @@ void ptywright_ghostty_terminal_destroy(PtywrightGhosttyTerminal *terminal) {
 		return;
 	}
 
+	if (terminal->encoder != NULL) {
+		ghostty_key_encoder_free(terminal->encoder);
+		terminal->encoder = NULL;
+	}
 	if (terminal->handle != NULL) {
 		ghostty_terminal_free(terminal->handle);
 		terminal->handle = NULL;

packages/ptywright/native/src/ghostty_bridge.h

@@ -36,6 +36,11 @@ int ptywright_ghostty_terminal_feed(PtywrightGhosttyTerminal *terminal,
 int ptywright_ghostty_terminal_resize(PtywrightGhosttyTerminal *terminal,
 				      uint16_t cols, uint16_t rows);
 
+int ptywright_ghostty_terminal_encode_special_key(PtywrightGhosttyTerminal *terminal,
+						 const char *name,
+						 uint8_t **out_bytes,
+						 size_t *out_len);
+
 int ptywright_ghostty_terminal_snapshot(PtywrightGhosttyTerminal *terminal,
 					int trim, int unwrap,
 					PtywrightGhosttySnapshot *out_snapshot);

packages/ptywright/src/keys.ts

@@ -17,3 +17,41 @@ export const KeyArrowUp: Key = "\x1b[A";
 export const KeyArrowDown: Key = "\x1b[B";
 export const KeyArrowLeft: Key = "\x1b[D";
 export const KeyArrowRight: Key = "\x1b[C";
+
+export const SPECIAL_KEY_KIND = "special" as const;
+
+export type SpecialKeyName =
+	| "arrow_up"
+	| "arrow_down"
+	| "arrow_left"
+	| "arrow_right"
+	| "home"
+	| "end"
+	| "page_up"
+	| "page_down"
+	| "insert"
+	| "delete"
+	| "escape"
+	| "backtab";
+
+export interface SpecialKey {
+	readonly kind: typeof SPECIAL_KEY_KIND;
+	readonly name: SpecialKeyName;
+}
+
+export function specialKey(name: SpecialKeyName): SpecialKey {
+	return { kind: SPECIAL_KEY_KIND, name };
+}
+
+export const SpecialArrowUp = specialKey("arrow_up");
+export const SpecialArrowDown = specialKey("arrow_down");
+export const SpecialArrowLeft = specialKey("arrow_left");
+export const SpecialArrowRight = specialKey("arrow_right");
+export const SpecialHome = specialKey("home");
+export const SpecialEnd = specialKey("end");
+export const SpecialPageUp = specialKey("page_up");
+export const SpecialPageDown = specialKey("page_down");
+export const SpecialInsert = specialKey("insert");
+export const SpecialDelete = specialKey("delete");
+export const SpecialEscape = specialKey("escape");
+export const SpecialBacktab = specialKey("backtab");

packages/ptywright/src/native-loader.ts

@@ -26,6 +26,7 @@ export interface NativeTerminalHandle {
 	feed(data: string | Uint8Array): Uint8Array | undefined;
 	resize(cols: number, rows: number): void;
 	snapshot(options?: { trim?: boolean; unwrap?: boolean }): NativeSnapshot;
+	encodeSpecialKey(name: string): Uint8Array | undefined;
 	dispose(): void;
 }