feat(driver): add escape to the pressKey surface

escape is a key a spec has real use for and no platform could send it. android maps it to KEYCODE_ESCAPE, the ios companion to HID usage 41 and the in-simulator runner to XCUIKeyboardKey.escape, and the Key union accepts it so it can be written at all.

internal/driver/ioscompanion/driver.go

@@ -664,12 +664,15 @@ func (d *Driver) runnerTyper() transport.TextTyper {
 }
 
 // pressKeyUsage maps the logical key names mobile runs emit to a HID usage.
-// Only Return/Enter has a hardware-keyboard equivalent on the simulator; other
-// names (notably "back" and "home") have no HID key and report unsupported.
+// Return/Enter and Escape are the hardware-keyboard keys the simulator has;
+// other names (notably "back" and "home") have no HID key and report
+// unsupported.
 func pressKeyUsage(key string) (uint32, bool) {
 	switch key {
 	case "enter", "return", "Enter", "Return":
 		return usageReturn, true
+	case "escape", "Escape":
+		return usageEscape, true
 	default:
 		return 0, false
 	}

internal/driver/ioscompanion/keymap.go

@@ -9,6 +9,7 @@ const (
 	usage1            = 30
 	usage0            = 39
 	usageReturn       = 40
+	usageEscape       = 41
 	usageTab          = 43
 	usageSpace        = 44
 	usageBackspace    = 42

internal/driver/ioscompanion/presskey_test.go

@@ -0,0 +1,47 @@
+package ioscompanion
+
+import (
+	"context"
+	"testing"
+
+	"github.com/priyanshujain/sanderling/internal/driver/ioscompanion/transport"
+)
+
+// keyRecordingCompanion keeps the HID events a press produced, so the assertion
+// is over what reached the transport rather than over the lookup that built it.
+type keyRecordingCompanion struct {
+	fakeCompanion
+	events []transport.HIDEvent
+}
+
+func (c *keyRecordingCompanion) SendHID(
+	_ context.Context,
+	events ...transport.HIDEvent,
+) error {
+	c.events = append(c.events, events...)
+	return nil
+}
+
+// docs/manual/spec-language.md documents escape, and the simulator's HID stream
+// carries it: usage 41 is the keyboard escape. Without it a spec clause over
+// escape reports unsupported on iOS while the same clause runs on web.
+func TestPressKeyEscapeReachesTheHIDStream(t *testing.T) {
+	companion := &keyRecordingCompanion{}
+	d := newTestDriver(companion)
+
+	if err := d.PressKey(context.Background(), "escape"); err != nil {
+		t.Fatalf("PressKey escape: %v", err)
+	}
+
+	// 41 is the USB HID keyboard escape usage, stated here rather than read
+	// from the production table so a wrong table entry cannot agree with itself.
+	want := []transport.HIDEvent{transport.KeyDown(41), transport.KeyUp(41)}
+	if len(companion.events) != len(want) {
+		t.Fatalf("sent %v, want %v", companion.events, want)
+	}
+	for index, event := range companion.events {
+		if event != want[index] {
+			t.Fatalf("sent %v, want %v", companion.events, want)
+		}
+	}
+}

internal/driver/ioscompanion/transport/runner.go

@@ -336,7 +336,13 @@ func (c *runnerCompanion) PressKey(ctx context.Context, key string) error {
 	case "enter", "return", "Enter", "Return":
 		_, err := c.call(ctx, "pressKey", map[string]any{"key": "return"})
 		return err
+	case "escape", "Escape":
+		_, err := c.call(ctx, "pressKey", map[string]any{"key": "escape"})
+		return err
 	default:
-		return fmt.Errorf("runner companion cannot press key %q; only return is supported", key)
+		return fmt.Errorf(
+			"runner companion cannot press key %q; only return and escape are supported",
+			key,
+		)
 	}
 }

internal/driver/ioscompanion/transport/transport.go

@@ -58,7 +58,7 @@ type TextEditor interface {
 	// EraseText deletes characterCount characters from the focused field.
 	EraseText(ctx context.Context, characterCount int) error
 
-	// PressKey presses the named logical key (currently only return/enter).
+	// PressKey presses the named logical key (return/enter and escape).
 	PressKey(ctx context.Context, key string) error
 }