poly-weaver 0.7.1 → 0.8.0

package/dist/terminal/input-router.d.ts

@@ -1,14 +1,19 @@
+import type { TerminalKey } from "../terminal-input.js";
 import type { PtyHandle } from "../pty/types.js";
 /**
- * Active parent UI mode (e.g. user-review prompt). When attached, raw
- * stdin chunks are routed to it BEFORE host shortcuts / mouse / interrupt
- * (but AFTER the global Ctrl+] dump detector). A host-backed prompt that
- * wants to own wheel/mouse input simply consumes the chunk by returning
+ * Active parent UI mode (e.g. user-review prompt). When attached, event
+ * arrays are routed to it BEFORE host shortcuts / wheel scroll (but
+ * AFTER the global dump hotkey check). A host-backed prompt that wants
+ * to own wheel/mouse input simply consumes the events by returning
  * `true` (the default).
  */
 export interface ParentUiMode {
-    /** Receive a chunk of raw input. Return true if consumed (don't forward). */
-    onInput(chunk: Buffer): boolean | void;
+    /**
+     * Receive a batch of `TerminalKey` events. Return `true` (or `void`)
+     * to consume the entire batch; return `false` to let the router fall
+     * through to its own shortcut/child routing for the same events.
+     */
+    onEvents(events: TerminalKey[]): boolean | void;
 }
 /**
  * Number of lines to scroll for a single mouse-wheel event. Small enough
@@ -18,7 +23,7 @@ export declare const WHEEL_LINES_PER_EVENT = 3;
 export interface InputRouterOptions {
     /** Trigger a dump capture when Ctrl+] is observed. */
     onDump?: () => void;
-    /** Host interrupt: invoked when raw Ctrl+C (byte 0x03) is observed and no parent UI consumes it. */
+    /** Host interrupt: invoked when Ctrl+C is observed and no parent UI consumes it. */
     onInterrupt?: () => void;
     /** Scroll back by N lines (older content). */
     onScrollBackLines?: (lines: number) => void;
@@ -32,115 +37,31 @@ export interface InputRouterOptions {
     onScrollToBottom?: () => void;
 }
 /**
- * Centralizes stdin ownership while the orchestration host is active.
- *
- * Routing order on each chunk:
+ * Event-based input router. Operates on `TerminalKey[]` produced by a
+ * `KeyEventSource`; the byte-level state machine is internal to
+ * `StdinByteSource`'s parser.
  *
- *   1. Dump hotkey detector (Ctrl+]) — strips dump bytes from forward.
- *      The detector also reassembles split CSI sequences for kitty /
- *      win32 dump variants, so when configured, downstream stages see
- *      whole sequences for those paths.
+ * Routing order on each event batch:
+ *   1. Dump hotkey check (Ctrl+]) — strips matching events before they
+ *      reach the parent UI or child.
  *   2. Active parent UI mode (if attached) — fully consumes by default.
- *      Parent UI receives Ctrl+C, mouse, and nav keys first and may
- *      handle them. Only when there is no parent UI, or it returns
- *      `false`, does routing fall through to the host's own handlers.
- *   3. SGR mouse-wheel parsing — consumes `CSI < 64/65 ; … M` for
- *      vertical wheel events and dispatches scroll callbacks. Non-wheel
- *      SGR mouse events flow through unchanged. A small first-class
- *      buffer reassembles SGR mouse sequences split across chunks so
- *      the routing works regardless of whether the dump detector is
- *      configured.
- *   4. Host shortcut routing on remaining bytes:
- *        - Ctrl+C (0x03)        → `onInterrupt()`
- *        - PageUp  (CSI 5~)     → `onScrollPages(-1)`
- *        - PageDown (CSI 6~)    → `onScrollPages(+1)`
- *        - Home    (CSI 1~/H)   → `onScrollToTop()`
- *        - End     (CSI 4~/F)   → `onScrollToBottom()`
- *   5. Attached child PTY when `gateOpen` is true — `handle.write(forward)`.
- *   6. Otherwise the chunk is dropped.
+ *   3. Wheel events → scrollback callbacks (consumed; never reach child).
+ *   4. Host shortcuts: Ctrl+C → onInterrupt; page/home/end → scrollback.
+ *   5. Remaining events → child PTY when `gateOpen` is true, encoded via
+ *      `encodeKeysToBytes`. Otherwise dropped.
  */
 export declare class InputRouter {
     private readonly options;
     private parentUiMode;
     private childHandle;
-    private dumpDetector;
-    /** Buffered head of a split SGR mouse sequence (`ESC [ < … `). */
-    private sgrPartial;
-    private sgrPartialTimer;
     constructor(options?: InputRouterOptions);
     attachChild(handle: PtyHandle): void;
     detachChild(handle?: PtyHandle): void;
     attachParentUi(mode: ParentUiMode): void;
     detachParentUi(mode?: ParentUiMode): void;
-    /** Process a stdin chunk. Returns true when at least one byte was consumed. */
-    handleChunk(chunk: Buffer): boolean;
+    /** Process a batch of `TerminalKey` events. */
+    handleEvents(events: TerminalKey[]): void;
     private forwardToChild;
-    /**
-     * Strip SGR mouse wheel events (`CSI < 64;…M` and `CSI < 65;…M`) from
-     * the chunk, dispatching scrollback callbacks. Non-wheel SGR mouse
-     * events (clicks, motion, releases) and other CSI sequences (Home,
-     * PageUp, etc.) are left in the chunk so callers can still forward
-     * them or run them through host shortcut routing.
-     *
-     * Sequences split across chunk boundaries are first-class. The buffer
-     * holds any incomplete CSI prefix — bare ESC, ESC `[`, ESC `[ < …` —
-     * and prepends it to the next chunk. This works even when the dump
-     * detector is not configured (the detector reassembles split CSI for
-     * its own purposes when it is configured, but mouse-wheel scrollback
-     * MUST NOT depend on it). A 50 ms safety timer flushes a stale
-     * partial through `consumeHostShortcuts` and the child gate so a
-     * bare Esc keypress eventually reaches the child even when there is
-     * no continuation, and so a stray ESC byte cannot permanently block
-     * future input.
-     */
-    private consumeSgrMouseWheel;
-    private savePartialSgr;
-    /**
-     * Stale-partial flush. Two distinct cases:
-     *
-     * - Bare `ESC` (1 byte): flush through host shortcuts and the child
-     *   gate. The user pressed Esc and there is no continuation; the
-     *   child must still receive the byte after the safety window
-     *   (matching the dump detector's bare-Esc deferred-flush).
-     *
-     * - Truncated CSI (`ESC [ …`, 2+ bytes): drop. The user pressed
-     *   Home/PageUp/wheel/etc. and the terminal failed to deliver the
-     *   rest within the window. Forwarding raw `ESC [ < 6 4 ;` would
-     *   inject random bytes into the child agent — much worse than
-     *   losing one stray nav event.
-     */
-    private flushPartialSgr;
-    private resetSgrPartialTimer;
-    private resetSgrPartial;
-    /**
-     * Consume host scrollback / interrupt shortcuts from the chunk. Returns
-     * the chunk with any consumed bytes removed.
-     *
-     * Recognized sequences (single-chunk only — split CSI across two
-     * chunks falls through to the child unchanged, which is acceptable
-     * because real terminals deliver these in one chunk):
-     *
-     * - 0x03                 Ctrl+C            → onInterrupt()
-     * - ESC [ 5 ~            PageUp            → onScrollPages(-1)
-     * - ESC [ 6 ~            PageDown          → onScrollPages(+1)
-     * - ESC [ 1 ~ / ESC [ H  Home              → onScrollToTop()
-     * - ESC [ 4 ~ / ESC [ F  End               → onScrollToBottom()
-     *
-     * Modifier-prefixed variants (e.g. `ESC [ 1;5 H` for Ctrl+Home) match
-     * the same callback as their unmodified form.
-     */
-    private consumeHostShortcuts;
-    private dispatchCsi;
-    /**
-     * Route a deferred buffer (produced by `DumpHotkeyDetector` when a
-     * pending escape sequence times out). The deferred bytes have already
-     * been screened for the dump hotkey — they must NOT pass through the
-     * detector again. They DO continue through the parent UI mode, the
-     * SGR mouse parser, host shortcuts, and the child gate so a bare Esc
-     * reaches host-backed prompts and a deferred mouse sequence is still
-     * correctly classified.
-     */
-    private routeDeferred;
     destroy(): void;
 }
 //# sourceMappingURL=input-router.d.ts.map

package/dist/terminal/input-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"input-router.d.ts","sourceRoot":"","sources":["../../src/terminal/input-router.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACxC;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,8EAA8E;IAC9E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,sCAAsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,WAAW;IAQV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,YAAY,CAA2B;IAC/C,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,YAAY,CAAiC;IACrD,kEAAkE;IAClE,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,eAAe,CAA4C;gBAEtC,OAAO,GAAE,kBAAuB;IAmB7D,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAIpC,WAAW,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAKrC,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAIxC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI;IAKzC,+EAA+E;IAC/E,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAmCnC,OAAO,CAAC,cAAc;IAOtB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,oBAAoB;IAsF5B,OAAO,CAAC,cAAc;IAMtB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,eAAe;IAOvB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,oBAAoB;IAmD5B,OAAO,CAAC,WAAW;IAqDnB;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAgBrB,OAAO,IAAI,IAAI;CAOhB"}
+{"version":3,"file":"input-router.d.ts","sourceRoot":"","sources":["../../src/terminal/input-router.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,GAAG,IAAI,CAAC;CACjD;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,8EAA8E;IAC9E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,sCAAsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,YAAY,CAA2B;IAC/C,OAAO,CAAC,WAAW,CAAwB;gBAEd,OAAO,GAAE,kBAAuB;IAE7D,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAIpC,WAAW,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAKrC,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAIxC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI;IAKzC,+CAA+C;IAC/C,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI;IA4DzC,OAAO,CAAC,cAAc;IAatB,OAAO,IAAI,IAAI;CAIhB"}

package/dist/terminal/input-router.js

@@ -1,67 +1,30 @@
-import { DumpHotkeyDetector } from "../dump/hotkey.js";
+import { isDumpHotkey } from "../dump/hotkey.js";
+import { encodeKeysToBytes } from "./key-to-bytes.js";
 /**
  * Number of lines to scroll for a single mouse-wheel event. Small enough
  * to feel precise while still moving meaningfully on every notch.
  */
 export const WHEEL_LINES_PER_EVENT = 3;
-const ETX = 0x03; // Ctrl+C
-const ESC = 0x1b;
-const LBRACKET = 0x5b; // '['
-const LT = 0x3c; // '<'
-const TILDE = 0x7e; // '~'
-/** Maximum dwell for a buffered partial SGR mouse sequence before we drop it. */
-const SGR_MOUSE_PARTIAL_TIMEOUT_MS = 50;
 /**
- * Centralizes stdin ownership while the orchestration host is active.
+ * Event-based input router. Operates on `TerminalKey[]` produced by a
+ * `KeyEventSource`; the byte-level state machine is internal to
+ * `StdinByteSource`'s parser.
  *
- * Routing order on each chunk:
- *
- *   1. Dump hotkey detector (Ctrl+]) — strips dump bytes from forward.
- *      The detector also reassembles split CSI sequences for kitty /
- *      win32 dump variants, so when configured, downstream stages see
- *      whole sequences for those paths.
+ * Routing order on each event batch:
+ *   1. Dump hotkey check (Ctrl+]) — strips matching events before they
+ *      reach the parent UI or child.
  *   2. Active parent UI mode (if attached) — fully consumes by default.
- *      Parent UI receives Ctrl+C, mouse, and nav keys first and may
- *      handle them. Only when there is no parent UI, or it returns
- *      `false`, does routing fall through to the host's own handlers.
- *   3. SGR mouse-wheel parsing — consumes `CSI < 64/65 ; … M` for
- *      vertical wheel events and dispatches scroll callbacks. Non-wheel
- *      SGR mouse events flow through unchanged. A small first-class
- *      buffer reassembles SGR mouse sequences split across chunks so
- *      the routing works regardless of whether the dump detector is
- *      configured.
- *   4. Host shortcut routing on remaining bytes:
- *        - Ctrl+C (0x03)        → `onInterrupt()`
- *        - PageUp  (CSI 5~)     → `onScrollPages(-1)`
- *        - PageDown (CSI 6~)    → `onScrollPages(+1)`
- *        - Home    (CSI 1~/H)   → `onScrollToTop()`
- *        - End     (CSI 4~/F)   → `onScrollToBottom()`
- *   5. Attached child PTY when `gateOpen` is true — `handle.write(forward)`.
- *   6. Otherwise the chunk is dropped.
+ *   3. Wheel events → scrollback callbacks (consumed; never reach child).
+ *   4. Host shortcuts: Ctrl+C → onInterrupt; page/home/end → scrollback.
+ *   5. Remaining events → child PTY when `gateOpen` is true, encoded via
+ *      `encodeKeysToBytes`. Otherwise dropped.
  */
 export class InputRouter {
     options;
     parentUiMode;
     childHandle;
-    dumpDetector;
-    /** Buffered head of a split SGR mouse sequence (`ESC [ < … `). */
-    sgrPartial = [];
-    sgrPartialTimer;
     constructor(options = {}) {
         this.options = options;
-        if (this.options.onDump) {
-            const onDump = this.options.onDump;
-            this.dumpDetector = new DumpHotkeyDetector(() => onDump(), (deferred) => {
-                // Deferred flush — fires when DumpHotkeyDetector buffered an
-                // ESC (or partial CSI) and the timeout expired without a final
-                // byte arriving. Re-enter the routing pipeline so a bare ESC
-                // reaches an active parent UI mode (HostBackedCuratePrompt
-                // uses Esc to cancel comment editing). Only when there is no
-                // parent UI and the child gate is open does the bytes reach
-                // the child.
-                this.routeDeferred(deferred);
-            });
-        }
     }
     attachChild(handle) {
         this.childHandle = handle;
@@ -79,346 +42,82 @@ export class InputRouter {
             return;
         this.parentUiMode = undefined;
     }
-    /** Process a stdin chunk. Returns true when at least one byte was consumed. */
-    handleChunk(chunk) {
-        // Global parent shortcuts run FIRST so Ctrl+] reliably triggers a
-        // dump regardless of which UI mode currently owns input. The detector
-        // strips the hotkey bytes from the forward buffer; everything else
-        // continues down the routing pipeline.
-        let forward = chunk;
-        if (this.dumpDetector) {
-            forward = this.dumpDetector.process(chunk);
-        }
-        if (forward.length === 0)
-            return true;
-        // Parent UI gets first crack at every byte that isn't the dump
-        // hotkey — including mouse events and nav keys. A host-backed
-        // prompt that wants to own wheel input simply consumes the chunk.
-        if (this.parentUiMode) {
-            const consumed = this.parentUiMode.onInput(forward);
-            // Default behaviour: parent UI swallows everything until detached.
-            if (consumed !== false) {
-                // The parent UI took ownership. Any partial SGR mouse sequence
-                // we previously buffered no longer applies — clear the buffer.
-                this.resetSgrPartial();
-                return true;
+    /** Process a batch of `TerminalKey` events. */
+    handleEvents(events) {
+        if (events.length === 0)
+            return;
+        // Pre-filter: dump hotkey runs ahead of everything and is stripped.
+        const filtered = [];
+        for (const ev of events) {
+            if (isDumpHotkey(ev)) {
+                this.options.onDump?.();
+                continue;
             }
+            filtered.push(ev);
         }
-        // Host owns the bytes. SGR mouse-wheel parsing comes BEFORE host
-        // shortcuts so wheel events don't accidentally match nav keys.
-        forward = this.consumeSgrMouseWheel(forward);
-        if (forward.length === 0)
-            return true;
-        const afterShortcuts = this.consumeHostShortcuts(forward);
-        if (afterShortcuts.length === 0)
-            return true;
-        return this.forwardToChild(afterShortcuts);
-    }
-    forwardToChild(buf) {
-        const child = this.childHandle;
-        if (!child || !child.gateOpen)
-            return false;
-        child.write(buf.toString());
-        return true;
-    }
-    /**
-     * Strip SGR mouse wheel events (`CSI < 64;…M` and `CSI < 65;…M`) from
-     * the chunk, dispatching scrollback callbacks. Non-wheel SGR mouse
-     * events (clicks, motion, releases) and other CSI sequences (Home,
-     * PageUp, etc.) are left in the chunk so callers can still forward
-     * them or run them through host shortcut routing.
-     *
-     * Sequences split across chunk boundaries are first-class. The buffer
-     * holds any incomplete CSI prefix — bare ESC, ESC `[`, ESC `[ < …` —
-     * and prepends it to the next chunk. This works even when the dump
-     * detector is not configured (the detector reassembles split CSI for
-     * its own purposes when it is configured, but mouse-wheel scrollback
-     * MUST NOT depend on it). A 50 ms safety timer flushes a stale
-     * partial through `consumeHostShortcuts` and the child gate so a
-     * bare Esc keypress eventually reaches the child even when there is
-     * no continuation, and so a stray ESC byte cannot permanently block
-     * future input.
-     */
-    consumeSgrMouseWheel(buf) {
-        // Prepend any buffered partial to this chunk before parsing.
-        if (this.sgrPartial.length > 0) {
-            const merged = Buffer.allocUnsafe(this.sgrPartial.length + buf.length);
-            for (let k = 0; k < this.sgrPartial.length; k++)
-                merged[k] = this.sgrPartial[k];
-            buf.copy(merged, this.sgrPartial.length);
-            buf = merged;
-            this.resetSgrPartialTimer();
-            this.sgrPartial = [];
+        if (filtered.length === 0)
+            return;
+        // Parent UI gets the remainder first.
+        if (this.parentUiMode) {
+            const consumed = this.parentUiMode.onEvents(filtered);
+            if (consumed !== false)
+                return;
         }
-        if (buf.length === 0)
-            return buf;
-        const out = [];
-        let i = 0;
-        while (i < buf.length) {
-            const b = buf[i];
-            if (b !== ESC) {
-                out.push(b);
-                i++;
-                continue;
-            }
-            // ESC byte. The chunk ends here, after `[`, or after `[ < …`
-            // — buffer the partial in every case so a split mouse sequence
-            // never leaks to the child as half-bytes.
-            if (i + 1 >= buf.length) {
-                // Bare ESC at end-of-chunk. Could be (a) the Esc key, (b) the
-                // start of an Alt+key combo, or (c) the start of any CSI
-                // including SGR mouse. Buffering all three for 50 ms costs a
-                // small delay on the Esc key (matching the dump detector's
-                // own delay) but is the price of not forwarding partial mouse
-                // sequences to the child.
-                this.savePartialSgr(buf.subarray(i));
-                return Buffer.from(out);
-            }
-            if (buf[i + 1] !== LBRACKET) {
-                // ESC + non-`[` — Alt+key or another ESC-prefixed combo. Emit
-                // both bytes immediately so Alt+key combos are not delayed.
-                out.push(b);
-                i++;
-                continue;
-            }
-            // We have ESC `[`. Find the CSI final byte in the range 0x40-0x7e.
-            let j = i + 2;
-            while (j < buf.length) {
-                const t = buf[j];
-                if (t >= 0x40 && t <= 0x7e)
-                    break;
-                j++;
-            }
-            if (j >= buf.length) {
-                // Unterminated CSI — buffer the partial for the next chunk to
-                // complete. This covers all reviewer-flagged splits: ESC alone,
-                // `ESC [`, `ESC [ <`, `ESC [ < 64 ;`, etc.
-                this.savePartialSgr(buf.subarray(i));
-                return Buffer.from(out);
-            }
-            const params = buf.subarray(i + 2, j).toString("ascii");
-            const final = buf[j];
-            // SGR mouse-wheel sequence: ESC `[ < cb ; cx ; cy M` where
-            // cb=64 (wheel up) or cb=65 (wheel down). Anything else (clicks,
-            // releases, non-mouse CSI) is passed through unchanged.
-            if (params.startsWith("<") && final === 0x4d /* M */) {
-                const cb = parseInt(params.slice(1).split(";")[0] ?? "", 10);
-                if (cb === 64) {
+        // Host owns the batch — pull wheel events into scrollback, ETX into
+        // interrupt, page/home/end into scroll callbacks; forward whatever
+        // remains to the child via the encoder.
+        const forward = [];
+        for (const ev of filtered) {
+            if (ev.kind === "wheel") {
+                if (ev.direction === "up") {
                     this.options.onScrollBackLines?.(WHEEL_LINES_PER_EVENT);
-                    i = j + 1;
-                    continue;
                 }
-                if (cb === 65) {
+                else {
                     this.options.onScrollForwardLines?.(WHEEL_LINES_PER_EVENT);
-                    i = j + 1;
-                    continue;
                 }
+                continue;
             }
-            // Not a mouse wheel — emit the entire CSI sequence intact.
-            for (let k = i; k <= j; k++)
-                out.push(buf[k]);
-            i = j + 1;
-        }
-        return Buffer.from(out);
-    }
-    savePartialSgr(partial) {
-        this.sgrPartial = Array.from(partial);
-        if (this.sgrPartialTimer)
-            clearTimeout(this.sgrPartialTimer);
-        this.sgrPartialTimer = setTimeout(() => this.flushPartialSgr(), SGR_MOUSE_PARTIAL_TIMEOUT_MS);
-    }
-    /**
-     * Stale-partial flush. Two distinct cases:
-     *
-     * - Bare `ESC` (1 byte): flush through host shortcuts and the child
-     *   gate. The user pressed Esc and there is no continuation; the
-     *   child must still receive the byte after the safety window
-     *   (matching the dump detector's bare-Esc deferred-flush).
-     *
-     * - Truncated CSI (`ESC [ …`, 2+ bytes): drop. The user pressed
-     *   Home/PageUp/wheel/etc. and the terminal failed to deliver the
-     *   rest within the window. Forwarding raw `ESC [ < 6 4 ;` would
-     *   inject random bytes into the child agent — much worse than
-     *   losing one stray nav event.
-     */
-    flushPartialSgr() {
-        if (this.sgrPartial.length === 0) {
-            this.sgrPartialTimer = undefined;
-            return;
-        }
-        const buf = Buffer.from(this.sgrPartial);
-        this.sgrPartial = [];
-        this.sgrPartialTimer = undefined;
-        if (buf.length === 1 && buf[0] === ESC) {
-            const afterShortcuts = this.consumeHostShortcuts(buf);
-            if (afterShortcuts.length > 0)
-                this.forwardToChild(afterShortcuts);
-        }
-        // Else: drop the truncated CSI prefix.
-    }
-    resetSgrPartialTimer() {
-        if (this.sgrPartialTimer) {
-            clearTimeout(this.sgrPartialTimer);
-            this.sgrPartialTimer = undefined;
-        }
-    }
-    resetSgrPartial() {
-        this.resetSgrPartialTimer();
-        if (this.sgrPartial.length > 0) {
-            this.sgrPartial = [];
-        }
-    }
-    /**
-     * Consume host scrollback / interrupt shortcuts from the chunk. Returns
-     * the chunk with any consumed bytes removed.
-     *
-     * Recognized sequences (single-chunk only — split CSI across two
-     * chunks falls through to the child unchanged, which is acceptable
-     * because real terminals deliver these in one chunk):
-     *
-     * - 0x03                 Ctrl+C            → onInterrupt()
-     * - ESC [ 5 ~            PageUp            → onScrollPages(-1)
-     * - ESC [ 6 ~            PageDown          → onScrollPages(+1)
-     * - ESC [ 1 ~ / ESC [ H  Home              → onScrollToTop()
-     * - ESC [ 4 ~ / ESC [ F  End               → onScrollToBottom()
-     *
-     * Modifier-prefixed variants (e.g. `ESC [ 1;5 H` for Ctrl+Home) match
-     * the same callback as their unmodified form.
-     */
-    consumeHostShortcuts(buf) {
-        if (buf.length === 0)
-            return buf;
-        const out = [];
-        let i = 0;
-        while (i < buf.length) {
-            const b = buf[i];
-            if (b === ETX) {
+            if (ev.kind === "control" && ev.byte === 0x03) {
                 if (this.options.onInterrupt) {
                     this.options.onInterrupt();
-                    i++;
                     continue;
                 }
-                // No interrupt handler — fall through to child.
-                out.push(b);
-                i++;
-                continue;
             }
-            if (b === ESC && i + 1 < buf.length && buf[i + 1] === LBRACKET) {
-                // Find the CSI final byte.
-                let j = i + 2;
-                while (j < buf.length) {
-                    const t = buf[j];
-                    if (t >= 0x40 && t <= 0x7e)
-                        break;
-                    j++;
-                }
-                if (j >= buf.length) {
-                    // Unterminated — emit remainder unchanged.
-                    for (let k = i; k < buf.length; k++)
-                        out.push(buf[k]);
-                    return Buffer.from(out);
-                }
-                const params = buf.subarray(i + 2, j).toString("ascii");
-                const final = buf[j];
-                const handled = this.dispatchCsi(params, final);
-                if (handled) {
-                    i = j + 1;
-                    continue;
-                }
-                // Not a host shortcut — pass through unchanged.
-                for (let k = i; k <= j; k++)
-                    out.push(buf[k]);
-                i = j + 1;
-                continue;
-            }
-            out.push(b);
-            i++;
-        }
-        return Buffer.from(out);
-    }
-    dispatchCsi(params, final) {
-        // PageUp = ESC [ 5 ~ ; PageDown = ESC [ 6 ~ ; Home = ESC [ 1 ~ or H ;
-        // End = ESC [ 4 ~ or F. Modifier params (e.g. "1;5") are accepted so
-        // Ctrl/Shift+nav routes through the same scroll callback.
-        if (final === TILDE) {
-            const code = parseInt(params.split(";")[0] ?? "", 10);
-            if (code === 5) {
-                if (this.options.onScrollPages) {
-                    this.options.onScrollPages(-1);
-                    return true;
-                }
-                return false;
-            }
-            if (code === 6) {
+            if (ev.kind === "page") {
                 if (this.options.onScrollPages) {
-                    this.options.onScrollPages(1);
-                    return true;
-                }
-                return false;
-            }
-            if (code === 1 || code === 7) {
-                if (this.options.onScrollToTop) {
-                    this.options.onScrollToTop();
-                    return true;
-                }
-                return false;
-            }
-            if (code === 4 || code === 8) {
-                if (this.options.onScrollToBottom) {
-                    this.options.onScrollToBottom();
-                    return true;
+                    this.options.onScrollPages(ev.direction === "up" ? -1 : 1);
+                    continue;
                 }
-                return false;
             }
-            return false;
-        }
-        if (final === 0x48 /* H */) {
-            if (this.options.onScrollToTop) {
+            if (ev.kind === "home" && this.options.onScrollToTop) {
                 this.options.onScrollToTop();
-                return true;
+                continue;
             }
-            return false;
-        }
-        if (final === 0x46 /* F */) {
-            if (this.options.onScrollToBottom) {
+            if (ev.kind === "end" && this.options.onScrollToBottom) {
                 this.options.onScrollToBottom();
-                return true;
+                continue;
             }
-            return false;
+            forward.push(ev);
         }
-        return false;
+        if (forward.length === 0)
+            return;
+        this.forwardToChild(forward);
     }
-    /**
-     * Route a deferred buffer (produced by `DumpHotkeyDetector` when a
-     * pending escape sequence times out). The deferred bytes have already
-     * been screened for the dump hotkey — they must NOT pass through the
-     * detector again. They DO continue through the parent UI mode, the
-     * SGR mouse parser, host shortcuts, and the child gate so a bare Esc
-     * reaches host-backed prompts and a deferred mouse sequence is still
-     * correctly classified.
-     */
-    routeDeferred(buf) {
+    forwardToChild(events) {
+        const child = this.childHandle;
+        if (!child || !child.gateOpen)
+            return;
+        const buf = encodeKeysToBytes(events);
         if (buf.length === 0)
-            return false;
-        if (this.parentUiMode) {
-            const consumed = this.parentUiMode.onInput(buf);
-            if (consumed !== false) {
-                this.resetSgrPartial();
-                return true;
-            }
-        }
-        const afterMouse = this.consumeSgrMouseWheel(buf);
-        if (afterMouse.length === 0)
-            return true;
-        const afterShortcuts = this.consumeHostShortcuts(afterMouse);
-        if (afterShortcuts.length === 0)
-            return true;
-        return this.forwardToChild(afterShortcuts);
+            return;
+        // Forward the encoded Buffer verbatim — the PtyHandle adapter is
+        // responsible for handing it to node-pty without lossy decoding.
+        // Going through a latin1 string here would corrupt multibyte UTF-8
+        // printable chars (e.g. "中" → "中") because node-pty re-encodes
+        // the inbound string as UTF-8.
+        child.write(buf);
     }
     destroy() {
-        this.dumpDetector?.destroy();
-        this.dumpDetector = undefined;
-        this.resetSgrPartial();
         this.childHandle = undefined;
         this.parentUiMode = undefined;
     }